Claude rc

claude-rc

A thin bash wrapper that spawns claude --remote-control "<topic>" inside detached tmux sessions and tracks them in a file-based registry. One entry point, subcommand dispatch.

Invocation

Invoke the bundled CLI directly from the skill: scripts/claude-rc <subcommand>. No install step is required.

Before the first call, verify dependencies are present: command -v tmux and command -v claude. If either is missing, ask the user to install them.

Subcommands

scripts/claude-rc                       # numbered picker to attach (default when no args)
scripts/claude-rc new <topic> [path] [--mode <mode>]
                                        # start a new RC session in [path] (default: cwd)
                                        # default permission mode: auto
                                        # --mode accepts: auto | acceptEdits | plan | default | dontAsk | bypassPermissions
scripts/claude-rc ls                    # list sessions with alive / dead state
scripts/claude-rc attach [name]         # attach to a session (picker if no name)
scripts/claude-rc rm <name>             # kill tmux session AND remove registry entry
scripts/claude-rc gc                    # remove registry entries whose tmux is dead
scripts/claude-rc --help                # usage

Registry

One YAML file per session at $CLAUDE_RC_HOME/registry/<tmux_name>.yaml (default $CLAUDE_RC_HOME=$HOME/.claude-rc). Schema:

tmux_session: "claude-rc-<slug>"
topic: "<user-provided topic>"
path: "<absolute cwd>"
created_at: "<ISO8601>"
mode: "interactive-remote-control"
permission_mode: "auto"    # or acceptEdits / plan / default / dontAsk / bypassPermissions

Sessions created outside this tool (e.g. manually-spawned tmux + claude) can be tracked by dropping a YAML file with the same schema into the registry dir — ls / attach / gc will pick it up automatically.

Key behaviors to preserve when editing

• tmux session name = claude-rc-<slug>. On collision append -2, -3... Stable names mean the same topic can be re-attached predictably.
• rm vs gc: rm <name> is active teardown (kills tmux + deletes registry, works on alive sessions). gc is passive cleanup (only deletes registry entries whose tmux is already dead; never touches alive sessions).
• Killing tmux kills the shell → kills claude --remote-control → ends the remote RC session. Claude Code RC requires the local process to stay alive.
• No log files. Full transcripts are already stored by Claude Code under ~/.claude/projects/. Do not add tee or tmux pipe-pane — piping through tee breaks the TUI.
• Empty-array-with-set -u bash gotcha: loops over files[@] must use "${files[@]+"${files[@]}"}" to avoid "unbound variable" on empty registry.

Mapping user requests to commands

User request	Command
開新 RC session 做 X (在當前目錄)	scripts/claude-rc new "X"
開新 RC session 做 X 在 ~/foo	scripts/claude-rc new "X" ~/foo
開新 RC session 但要手動確認權限	scripts/claude-rc new "X" --mode default
開新 RC session 用 plan mode	scripts/claude-rc new "X" --mode plan
列出所有 RC sessions	scripts/claude-rc ls
接回之前的 session (不知道名字)	scripts/claude-rc
接回特定 session	scripts/claude-rc attach <name>
關掉 foo session	scripts/claude-rc rm claude-rc-foo
清掉死掉的 session 記錄	scripts/claude-rc gc

Dependencies

If any is missing, the script exits with a hint. Before invoking the script, check and suggest installation if needed:

Dependency	Install
tmux	brew install tmux (macOS) · apt install tmux (Debian/Ubuntu)
claude CLI, logged in with RC-capable plan	See https://code.claude.com/docs/en/quickstart

RC-capable plans: Pro / Max / Team / Enterprise. API key auth is not supported. On Team/Enterprise, an admin must enable Remote Control in org settings.

Iteration workflow

1. Edit scripts/claude-rc in this repo
2. Smoke-test from skill root: scripts/claude-rc --help, scripts/claude-rc ls, scripts/claude-rc gc
3. Commit SKILL.md + scripts/claude-rc together; bump metadata.version

Design decisions worth remembering

• One entry point, subcommands (not separate new-rc-session / list-rc-sessions scripts) — shared helpers, one registry path, simpler mental model.
• One YAML file per session (not a single append-only sessions.yaml) — delete = rm file, update = overwrite, no parse-rewrite cycle, concurrent-safe.
• Stable tmux names without timestamp — re-attach by topic is predictable; collision handled by numeric suffix.
• Default action = attach — the most common use is coming back to existing work, not creating new sessions.
• Default --permission-mode auto — RC sessions are usually driven from mobile/web where permission prompts are friction. auto has a classifier gating risky actions. Users can override with --mode. Note: auto has plan/model requirements (Max/Team/Enterprise/API, Opus 4.7 / Sonnet 4.6 / Opus 4.6; not Pro) — if Claude rejects it, the session will fail at startup and the user should pick a different mode.