Claude Relay

Relay operator for Claude Code via tmux across multiple projects. Use when the user wants to start/continue a Claude Code terminal session, send prompts, rea...

Security Scan

The skill's requirements and behavior match its description: it orchestrates a Claude Code CLI inside tmux sessions per project and does not request unrelated credentials or perform hidden network activity.

Purpose & Capability

Name/description (relay for Claude Code via tmux) matches what is required and implemented: the script requires tmux and a 'claude' CLI and manages per-project tmux sessions. No unrelated binaries or secrets are requested.

Instruction Scope

SKILL.md and scripts/relay.sh are focused on session lifecycle (start/send/tail/stop/status/session). The script only reads a projects.map file, discovers projects under a configurable root, writes a single 'last_project' state file, and launches the claude CLI inside tmux. It does not attempt to read other system files, env secrets, or POST to external endpoints itself.

Install Mechanism

There is no install spec (instruction-only skill plus a shell script), so nothing is fetched or written beyond the included script. This is the lowest-risk install posture.

Credentials

No required environment variables or credentials are declared. Optional env vars (CLAUDE_RELAY_ROOT, CLAUDE_RELAY_MAP, CLAUDE_BIN, RELAY_WAIT) are reasonable for configuring where projects live and which claude binary to use. The script does use HOME and XDG_STATE_HOME to store its own state, which is proportionate to its purpose.

Persistence & Privilege

Skill is not always-enabled and does not modify other skills or system-wide agent settings. It stores only its own small state file under XDG_STATE_HOME or ~/.local/state and manages tmux sessions it creates.

Assessment

This skill appears coherent and limited to orchestrating Claude Code CLI sessions inside tmux. Before installing: 1) Verify you have the official claude CLI (the script will run whatever is at CLAUDE_BIN); a malicious claude binary could perform network/FS actions. 2) Be aware the relay launches Claude in the project directory — any prompts you send or Claude's behavior may access files in that directory. Avoid sending secrets in prompts. 3) The skill writes a small 'last_project' file under XDG_STATE_HOME (or ~/.local/state) and reads projects.map in the skill dir — ensure projects.map contents are trustworthy. 4) If you need stronger guarantees, inspect the included scripts locally and run them in a controlled environment before granting broad use.

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

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.