Claude Relay

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.

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

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.