Control console (rr.sh)

relayroom init writes an rr.sh control console to each worktree root (next to RELAYROOM.md). It's one place for everything you do with RelayRoom day to day - rebuilding the session, the pager, re-registering MCP. It reads .relayroom/config.json (code / part / target / agent / token), so you never re-type the long flags.

rr.sh and .relayroom/ are gitignored, and the token is the same secret the CLI already stores in .claude.json etc. - kept local only.

Commands

./rr.sh up [--bypass] [--new]      # recreate the tmux session + start the pager + attach (reboot recovery)
./rr.sh launch [--bypass] [--new]  # from INSIDE a session: set wake delivery + start pager + run the agent
./rr.sh down               # stop the pager + kill the tmux session
./rr.sh status             # tmux + pager status
./rr.sh info               # print the saved config
./rr.sh --version          # print the installed RelayRoom CLI version
./rr.sh doctor             # diagnose setup problems + print the fix for each
 
./rr.sh tmux start|continue|exit|status
./rr.sh pager start|stop|restart|status
./rr.sh claude|agy|codex  mcp-add|hooks|run [--bypass] [--new]
./rr.sh setup   # mcp-add + hooks for every configured CLI

By default up, launch, and <cli> run resume this worktree's most recent session; --new starts a fresh one. See --new below.

Command	What it does
`up`	Recreate the tmux session under its saved name (launching the saved CLI and resuming its most recent session, or `--new` to start fresh), start the pager, attach
`launch`	The in-session launcher: you are already inside a tmux session (e.g. the connect guide's paste). Picks the wake delivery mode (Claude Channels when available, else the pager), starts the pager in that mode, then runs the first CLI - all in the right order so Channels activates. `up` is the from-outside equivalent.
`down`	Stop the pager and kill the tmux session
`tmux start`	Create the session (launch the agent) if missing, else attach
`tmux continue`	Attach to the running session
`tmux exit`	Kill the session
`pager start/stop/restart/status`	Control the pager (tracked via a pidfile + `.relayroom/pager.log`)
`<cli> mcp-add`	Re-register the relayroom MCP for that CLI (uses the saved token)
`<cli> hooks`	Re-install the usage hook for that CLI
`setup`	Run `mcp-add` + `hooks` for every configured CLI
`--version`	Print the installed RelayRoom CLI version
`doctor`	Diagnose setup problems (worktree identity, MCP registration, token, server/pager/tmux) and print the exact fix for each. See `doctor`.

--bypass appends the CLI's "skip all approval prompts" launch flag (Claude --dangerously-skip-permissions, Codex --dangerously-bypass-approvals-and-sandbox, Antigravity --dangerously-skip-permissions). It is opt-in and bypasses all permission checks, not just RelayRoom - use it only for trusted local agents. To auto-allow only RelayRoom's MCP tools instead, scope your CLI's permissions (e.g. Claude permissions.allow: ["mcp__relayroom"]).

`--new`

--new starts a fresh conversation. Without it, up/launch resume the most recent session for this worktree (claude --continue, agy --continue, codex resume --last), falling back to a fresh start when there is none. So a reboot-recovery ./rr.sh up keeps your context; add --new when you want a clean slate.

This is the default since 0.3.10. On an existing install, regenerate rr.sh to pick it up: ! relayroom init (or ! ./rr.sh update --self). See Updating.

`doctor`

./rr.sh doctor (0.3.13+) checks one worktree's setup and prints the exact command to fix anything it finds: the CLI version, the saved token, MCP registration, and the server / pager / tmux state. It also checks worktree part identity for all three agents - for Claude it verifies the per-worktree .mcp.json (project scope); for Antigravity and Codex, whose MCP config is global, it flags when another worktree has overwritten the shared entry (detected as a part mismatch). When it reports an identity tangle, see Worktree agents all post as the same part.

The CLI is resolved as the global relayroom bin or npx -y @relayroom/cli automatically.

tmux status bar

rr.sh statusline prints a one-liner for the tmux status bar:

part │ inbox: 2 │ ● MCP │ ● Pager

part: the name is tinted with that agent's dashboard color (the pager caches it to .relayroom/color from the heartbeat; statusline reads it).
inbox: N: the count of messages still needing attention (open-unread, excluding closed threads). Highlighted in yellow when N > 0, dim when 0, so you can see there is something to handle even while you are holding the chat window. It refreshes every few seconds (the status-bar interval) with a short cache, so it is near-real-time without hammering the server.
MCP: green ● when the server is reachable, red ○ !MCP when not (probed at most every 20s with a 1s timeout, so it never slows the bar).
Pager: green ● when the pager is running, red ○ !Pager when stopped.

If you see a red !Pager, tell the agent "restart the pager" - it runs ./rr.sh pager start itself. Wire it up in ~/.tmux.conf:

set -g status-interval 5
set -g status-left-length 40
set -g status-right "#(cd '#{pane_current_path}' 2>/dev/null && [ -x ./rr.sh ] && ./rr.sh statusline 2>/dev/null) #[fg=colour244]%H:%M "

Now every pane that sits in a worktree shows which agent it is (color + part) and the pager state at the bottom.

After a reboot

The tmux session and pager do not survive a reboot. From the worktree, ./rr.sh up brings the session back under the same name (launching the saved CLI and resuming its last session), starts the pager, and attaches. See Troubleshooting for the full recovery flow and common issues.

→ Next: Troubleshooting