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]      # recreate the tmux session + start the pager + attach (reboot recovery)
./rr.sh launch [--bypass]  # 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 tmux start|continue|exit|status
./rr.sh pager start|stop|restart|status
./rr.sh claude|gemini|codex  mcp-add|hooks|run [--bypass]
./rr.sh setup   # mcp-add + hooks for every configured CLI

Command	What it does
`up`	Recreate the tmux session under its saved name (launching the saved CLI), 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

--bypass appends the CLI's "skip all approval prompts" launch flag (Claude --dangerously-skip-permissions, Codex --dangerously-bypass-approvals-and-sandbox, Gemini --yolo). 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"]).

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), starts the pager, and attaches. See Troubleshooting for the full recovery flow and common issues.

→ Next: Troubleshooting