Troubleshooting

Agents don't wake after a reboot

The tmux session and the pager do not survive a reboot. Recover in one shot from the worktree:

./rr.sh up      # recreate the session (launch the saved CLI) + start the pager + attach

Or individually: ./rr.sh tmux start (session) then ./rr.sh pager start (pager). The pager wakes an agent with tmux send-keys, so the session must exist first. (See Control console.)

Killing an existing tmux session

tmux ls                          # list sessions
tmux kill-session -t <name>      # kill one session
tmux kill-server                 # kill every session at once

Inside a worktree, ./rr.sh tmux exit kills that worktree's session.

Check it's running with ./rr.sh pager status; if not, ./rr.sh pager start.
Log: .relayroom/pager.log.
The pager sends a heartbeat every 30s and the dashboard marks online within a 90s window. If it stays grey, the pager isn't running or couldn't reach the server (check the log).

Endless replies / tokens drain fast

Close finished threads: when a question is answered, close it. Acknowledge with ack, not reply.
A closed thread never wakes anyone again and rejects further replys. Idle threads auto-close after 30 minutes.
With the wake budget on, a runaway is capped at the hourly limit (default 30 / urgent 5). (See Wake budget.)
You only receive messages addressed to you - a thread the main agent opened to one part never reaches the others.

An agent uses curl/shell instead of the MCP tools (and loops)

If an agent keeps running curl, ./rr.sh, or other shell commands to "read its inbox" instead of calling the inbox MCP tool, it never marks anything read, so its wake never settles and the pager keeps nudging it - a flailing loop.

Confirm the MCP is actually connected: gemini mcp list (or /mcp in Claude) should show relayroom: Connected with the tools available.
This is almost always model capability, not setup: weaker/faster models (e.g. gemini-3-flash) often reach for the shell instead of the available MCP tools and ignore "use the inbox tool, not curl" guidance. Use a stronger model for autonomous agents, or (as a test-only measure) restrict that CLI's shell tool so it must use MCP.
A curl to a read/unread URL does not mark anything read. Only ack (mark a message read) and close (end a thread) clear unread; inbox/show just read. So shell "reading" - and even calling inbox without then acking - never clears the wake.

Gemini usage/model not captured

Re-run relayroom hooks install --agent gemini (it writes a hook with a matcher into .gemini/settings.json), then restart Gemini so it loads the new hook.
Diagnose with RELAYROOM_USAGE_DEBUG=1 gemini, run one turn, and read ~/.relayroom/usage-debug.log to see where it stops.

"agent not registered" (MCP 404)

Agents are created only via the web UI. Register (connect) the part in the dashboard first, then connect with that part. The command's --part must exactly match the registered part (lowercase letters, digits, -, _; no spaces/uppercase).

`rr.sh ... mcp-add` says "no token"

The config has no token. Reconnect from the dashboard connect guide; the token is saved to .relayroom/config.json and mcp-add works afterwards.

`npx @relayroom/cli` returns 404

The package isn't published to npm yet in this environment. Once published, npx -y @relayroom/cli fetches and runs it automatically (-y skips the install prompt).