claude-relay

通过跨多个项目的 tmux 进行 Claude Code 的中继操作。当用户想要启动/继续 Claude Code 终端会话、发送提示、读取输出或按项目名称/路径管理后台 Claude 会话时使用。

# Claude Relay

Operate Claude Code as a persistent terminal copilot through tmux.

## Script

All actions go through `scripts/relay.sh`. Run with no args for usage help.

```bash
scripts/relay.sh <action> [project] [args...]
```

**Actions**: `start`, `send`, `tail`, `stop`, `status`, `session`

## Workflow

1. Start session: `scripts/relay.sh start <project>`
2. Send instruction: `scripts/relay.sh send <project> "<text>"`
3. Read output: `scripts/relay.sh tail <project> [lines]`
4. Repeat send/tail as needed.
5. Stop when done: `scripts/relay.sh stop <project>`

## Project resolution

The script resolves `<project>` in order:

1. Absolute path (if directory exists)
2. Alias from `projects.map` (`name=/abs/path`)
3. `$CLAUDE_RELAY_ROOT/<name>` exact match
4. Find under `$CLAUDE_RELAY_ROOT` (maxdepth=2) by folder name
5. If omitted, re-use last project

Multiple matches → script exits with candidates; ask user to clarify.

## Session naming

Deterministic: `cc_<basename_sanitized>`. One project = one tmux session.

## Error handling

- **tmux not installed**: script exits with code 2 and "missing dependency" message.
- **Claude binary not found**: same exit code 2. Verify `CLAUDE_BIN` env or default path.
- **Session not running** (send/tail on stopped session): exits code 6. Start first.
- **Project not found**: exits code 4. Check `projects.map` or project path.
- **Claude process hung**: `tail` still works — check output. If stuck, `stop` and `start` fresh.

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_RELAY_ROOT` | `$HOME/projects` | Root directory for project discovery |
| `CLAUDE_RELAY_MAP` | `<skill-dir>/projects.map` | Path to project alias map file |
| `CLAUDE_BIN` | `claude` (from PATH) | Path to Claude Code CLI binary |
| `RELAY_WAIT` | `6` | Seconds to wait after send before tailing output |

## Setup

1. Install this skill
2. Create a `projects.map` file in the skill directory (see `projects.map.example`)
3. Ensure `tmux` and `claude` are installed and in your PATH

## Notes

- Transport-focused skill (relay/orchestration), not deep code reasoning.

---

## 中文说明

# Claude Relay

通过 tmux 将 Claude Code 作为一个持久的终端副驾驶来操作。

## 脚本

所有操作都通过 `scripts/relay.sh` 进行。不带参数运行可获取用法帮助。

```bash
scripts/relay.sh <action> [project] [args...]
```

**操作**：`start`、`send`、`tail`、`stop`、`status`、`session`

## 工作流程

1. 启动会话：`scripts/relay.sh start <project>`
2. 发送指令：`scripts/relay.sh send <project> "<text>"`
3. 读取输出：`scripts/relay.sh tail <project> [lines]`
4. 根据需要重复 send/tail。
5. 完成后停止：`scripts/relay.sh stop <project>`

## 项目解析

脚本按以下顺序解析 `<project>`：

1. 绝对路径（如果目录存在）
2. 来自 `projects.map` 的别名（`name=/abs/path`）
3. `$CLAUDE_RELAY_ROOT/<name>` 精确匹配
4. 在 `$CLAUDE_RELAY_ROOT` 下按文件夹名查找（maxdepth=2）
5. 如果省略，则重用上一个项目

多个匹配 → 脚本退出并列出候选项；请用户澄清。

## 会话命名

确定性的：`cc_<basename_sanitized>`。一个项目 = 一个 tmux 会话。

## 错误处理

- **未安装 tmux**：脚本以代码 2 退出并显示 "missing dependency" 消息。
- **未找到 Claude 二进制文件**：同样以代码 2 退出。请验证 `CLAUDE_BIN` 环境变量或默认路径。
- **会话未运行**（在已停止的会话上执行 send/tail）：以代码 6 退出。请先启动。
- **未找到项目**：以代码 4 退出。请检查 `projects.map` 或项目路径。
- **Claude 进程挂起**：`tail` 仍然可用 —— 检查输出。如果卡住，`stop` 后重新 `start`。

## 环境变量

| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CLAUDE_RELAY_ROOT` | `$HOME/projects` | 项目发现的根目录 |
| `CLAUDE_RELAY_MAP` | `<skill-dir>/projects.map` | 项目别名映射文件的路径 |
| `CLAUDE_BIN` | `claude`（来自 PATH） | Claude Code CLI 二进制文件的路径 |
| `RELAY_WAIT` | `6` | send 后在 tail 输出前等待的秒数 |

## 设置

1. 安装此技能
2. 在技能目录中创建一个 `projects.map` 文件（参见 `projects.map.example`）
3. 确保 `tmux` 和 `claude` 已安装并在你的 PATH 中

## 注意事项

- 这是一个专注于传输的技能（中继/编排），而非深度代码推理。