Quickstart

Get started in five steps

# 1. Install
cargo install --locked rimz

# 2. Open the room
cd ~/code/query-engine
rimz

# 3. Launch agents and work
claude
# or: codex, pi, opencode

# 4. Worktrees, teams, dynamic layout
rimz agents claude,codex --worktree=feat-x
rimz agents 'vim,claude+term' --worktree=feat-y

# 5. Native SSH remote with reconnect
rimz remote connect dev-box:~/code/query-engine

Hooks install on first rimz run, with consent and a diff preview. The sidebar guide shows what happens after the room opens.

One spec describes the shape: commas split columns, + tiles rows, and / stacks panes. A trailing prompt goes to the team's configured leader, its first role, or the first agent cell; use rimz message @all when everyone needs the same text.

rimz agents claude,codex "Refactor token refresh; keep the public API stable."
rimz agents 'vim,codex+term'
rimz agents claude/codex/term

Deep dive: Agent control CLI.

Give each task its own worktree

--worktree launches into an isolated RimZ-owned Git worktree. The tab name becomes the agents' channel.

rimz agents claude,codex --worktree=feat-x
rimz agents claude --worktree "Take one approach."
rimz agents codex --from-pr 42 "Review this pull request."

Deep dive: RimZ-owned worktrees.

Save layouts as teams

A named team in agents.toml gives each role a handle. Launch the team, or re-add one role to the running team.

rimz agents peer --worktree=feat-x
rimz agents forge
rimz agents forge.reviewer

Deep dive: Configuration.

Pick up where you left off

--resume reopens the freshest closed session, cohort, or team matching the spec. rimz start offers the whole prior room back after a reboot.

rimz agents claude --resume
rimz agents forge --resume
rimz agents forge -w feat-x --resume
rimz start

Deep dive: Teams and resume.

Message agents like teammates

Every agent gets a handle such as @codex#feat-a. Default delivery parks until the agent's turn ends; --steer interrupts now.

rimz message @claude "add coverage for the expiry edge cases"
rimz message --steer @claude "stop: the parser test comes first"
rimz message @coder --after @planner "planner is done — read plan.md and start"
rimz message @coder --wait "did the migration land? one line"
rimz message --schedule 60m @codex#feat-b "run the smoke test"
git diff main | rimz message @reviewer --stdin "review this"

Deep dive: Messaging.

Script an agent like a CLI

-p runs one supervised turn and exits with the run's status code, so scripts and CI can branch on the outcome.

rimz agents codex "Prepare the release checklist." -p --timeout 30m --output-format json
cat build-error.txt | rimz agents claude -p --stdin 'explain the root cause' > out.txt
rimz agents claude "Run the migration audit." -p --bg
rimz agents wait swift-otter --stream

Deep dive: Scripting.

Keep the fleet moving

Scheduled pings prime provider budget windows, and check-guarded loops wake agents when tests or CI fail.

rimz loop add morning --agent claude-ping --prompt ping --every weekday --at 07:00
rimz loop add watchdog --check "cargo test" --on fail \
  --agent codex --prompt "fix the failing test" --every 15m

Deep dive: Set up your machine.

Work from anywhere

A room is plain zellij or tmux under SSH. Save an alias, connect with reconnect, or open the room in a browser.

rimz remote add dev dev-box:~/code/query-engine
rimz remote connect dev
rimz remote connect dev --web
rimz web open

Deep dive: Remote attach and Web access.

Answer asks from your phone

Claude Code and Codex can keep their own remote-control bridges running with the room, so provider-app questions reach your phone and answers return to the same terminal session. Both integrations are off by default.

rimz config set remote_control.claude true
rimz config set remote_control.codex true

Deep dive: Remote control.