Getting started CLI

These commands open, find, and diagnose a room on this machine: bare rimz, start, attach, sessions, list, setup, and doctor. A room is a plain Zellij or tmux session with the RimZ sidebar added, so your keybinds, layout, and scrollback stay yours, and leaving it is a normal multiplexer detach. Which room a directory maps to, and the global flags (--root, --mux, --color), are defined on the CLI reference. A room on another host is rimz remote; a room in the browser is rimz web.

rimz setup                 # once per machine: report, write config, offer hooks and appearance
cd ~/code/query-engine
rimz                       # open this project's room and attach

Command, flag, and live session-name completion is set up in the shell completion guide.

Start the room

rimz [--attach | --no-attach | --print] [--no-resume] [--refresh-ms <MS>]
rimz start [PATH] [launch options] [--account <KIND@NAME>]...
rimz attach [SESSION] [launch options]

Bare rimz is rimz start .. rimz start [PATH] resolves the room for PATH (default .), creates its session if none is running, launches the sidebar, and attaches. A room written by an older RimZ is torn down and replaced by a fresh room; its history is not carried over. Replacement happens only when no running room holds the workspace; otherwise start or rimz attach without a session argument refuses with the held-room error below, leaving the room unchanged. For other rooms, a running session is reattached as it is, on the backend it runs under. A room is held while a sidebar pane or a live supervisor lives: a second birth on the same workspace exits nonzero, regardless of backend or session name. The error names the recorded session as already held by another running room, with rimz attach and rimz reset --no-start as fixes, and for a leftover or renamed session, closing it from its multiplexer (or renaming it back); the running room and its workspace record are unchanged. Once neither a sidebar pane nor a supervisor lives, the room is unheld. Attaching to that room relaunches its sidebar only if no other room holds the workspace; otherwise the attach exits nonzero without relaunching it. An attach during a sidebar restart can be refused until the sidebar returns. rimz reset is the command that rebuilds a room.

--attach, --no-attach, and --print are mutually exclusive.

Attach or print

Without an explicit attach flag, RimZ attaches only when both stdin and stdout are terminals and you are not already inside the selected backend. Outside that backend, a missing terminal makes it print the attach command on stdout and a notice on stderr: the room is open but not entered; pass --attach to enter anyway. Inside the selected backend, rimz and rimz start report the room situation instead, without opening a room or writing its state. rimz attach prints the command and a notice to detach from that backend before retrying. Explicit --print or --no-attach adds no fallback notice. When RimZ attaches, it exits with the multiplexer client's exit code once you detach.

Already in this directory's own room:

$ rimz
You're already in this directory's room (`rimz-f89e`, zellij).

This directory's room is running elsewhere:

$ rimz
This directory's room `rimz-f89e` is running in another zellij session.
Detach from this session, then run `rimz` here to enter it.

This directory's room is not running:

$ rimz
This directory's room isn't running, and zellij can't start one inside this session.
Detach and run `rimz` here, or run it from another terminal.

For tmux, the same messages name tmux instead of zellij.

Inside a session, rimz start --account fails instead, because accounts apply only when a room is born.

Attach by session name

rimz attach with no SESSION opens the current directory's room, creating it if needed. Unlike start, it skips the first-run, hook, and trust prompts below, takes no --account, and does not start the browser daemon. rimz attach <SESSION> takes an exact session name from rimz list. When RimZ has a workspace record for that session, it restores the room's sidebar and reconciles parked recovery state before attaching, creating the session if it is stopped. An attach to a running room asks nothing and leaves recovery candidates parked. A live session RimZ has no record for is attached, or printed, as a plain multiplexer session. With neither a record nor a live session, RimZ refuses instead of creating an empty session, and suggests at most one nearby recorded name:

$ rimz --mux zellij attach agnts-72ff
error: no room or zellij session named `agnts-72ff`
  did you mean `agents-72ff`?   all rooms: rimz list --all

Without a nearby name, the second line is all rooms: rimz list --all.

rimz start goes through the same health check on the way in, so either command is the way back into a room whose sidebar was closed or whose session came back wrong after a reboot.

Prompts at room birth

A rimz start that creates the session, run from a terminal, can ask up to five things before it attaches. A start or attach that reattaches a running session asks none of them.

A start without a terminal on stdin, including a remote reconnect, asks nothing: at birth it prints notices for missing hooks and undecided agent folder trust, leaves trust unchanged, and recovers prior agents. It does not remember a decline. Every start also prints the fix for saved-untrusted Codex folders, without offering a grant or remembering a decline for them. A running room leaves recovery candidates parked. The commands behind these prompts are in agent hooks and project trust; the trust model is in the security guide.

Resume on rebirth

A room is reborn when start finds its record but no running session, typically after a reboot or a multiplexer crash. RimZ first prints why the previous session ended, then offers to recover the agents that were running:

$ rimz
rimz: this room's previous session ended with agents still running (2026-07-02 17:37)
Recover 2 agents (claude, codex)? [Y/n]

After a reboot the first line reads rimz: machine rebooted since this room was last open (...). Rebirth recovery reports on stderr as rimz: resumed 2 agents: ..., and any left behind as rimz: not resumed: <label> (<reason>). When some agents cannot be resumed, RimZ lists each with its reason and asks a second question, whether to drop them, which defaults to no: kept agents are offered again at the next rebirth. --no-resume skips recovery and brings the room up with no agents, and so does answering n to the first question. Typed at a terminal, both are one-way: RimZ records the agents it did not recover as ended, so a later start without the flag has nothing left to seed from. Their transcripts and history stay on disk.

A running room never asks a recovery question, including web and remote entries, and opens no recovery tabs on entry. When agents remain parked it prints one stderr notice naming their count: rimz agents resume <lane> brings a lane back, and an attended rimz start --no-resume ends the parked candidates. The latter prints an ended count instead. With recovery on, even an unattended entry retires an old parked team session whose seat a live replacement already fills. An unattended rebirth resumes what it can and keeps the rest parked for an explicit resume or a later rebirth. The [resume] settings are in the configuration guide.

Accounts

--account <KIND@NAME> (for example --account claude@work) pins that provider's launch account from accounts declared with rimz accounts; default pins the provider's own home. Pins persist across starts. Without a pin, each launch follows the trusted project's [accounts], then the machine's [accounts.use], then default, live. Without --account, start writes no pin. On re-entry from outside the room, the flag can pin an inheriting provider or repeat its existing pin, but not replace a different pin. rimz accounts use pins future launches inside a running room; --reset unpins, without changing running agents' accounts. start checks all providers before building the room, and refuses in these cases:

The workflow is in the accounts guide.

Browser access at start

When [web] enabled = true, rimz start also starts the writable browser daemon. This is best-effort: a missing ttyd or an occupied [web] port prints a warning (rimz: browser daemon was not started: ...) and the room opens anyway. rimz attach does not start the daemon. rimz web inspects and controls browser access.

Pick a session

rimz sessions

rimz sessions opens a full-screen manager of every live RimZ room on the machine. Each room is a two-line card: the repository name and path, then live agent counts by kind (claude ×2), a ● count of agents that need attention, and the session, token, and spend totals of the sidebar's headline window (spend_window). Rooms with a prompt in the last 24 hours come first, newest prompt first; the rest follow by the time RimZ last wrote the workspace record, then by repository name and project path. A narrow terminal drops the card's right-hand metrics rather than wrapping them: the token total goes first, then the session count. The dollar figure always stays. Detaching from a room you entered returns you to the manager.

The filter line stays visible. Its cursor appears only while the filter is open; reopen it with / to edit or backspace away the text.

The new-session selector lists dormant known workspaces, then the current directory, then its non-hidden subdirectories, starting at $HOME. Typing filters the list.

An unreadable directory shows an empty directory list with a notice. rimz sessions refuses to run inside Zellij or tmux and points at rimz attach. Without a terminal on stdin and stdout, it prints the live sessions in its error message, ends with for a list, run: rimz list, and exits 1.

The browser's room picker is the same manager (web guide).

List rooms

rimz list [-a | --all] [--json]

rimz list (alias rimz ls) joins RimZ's workspace records with the live Zellij and tmux sessions, matched by session name. By default it shows running rooms and rooms active in the last 24 hours; --all adds dormant ones. Running rooms sort first, then by most recent activity. It reads records only and changes no room.

With no rows, human output leaves stdout empty and prints a hint on stderr. If the default view hides dormant rooms, the hint gives their count and names rimz list --all. With no known rooms, it says to run rimz in a project. Both exit 0. An empty JSON view prints [] on stdout and nothing on stderr.

--json prints an array with one object per row:

Set up the machine

rimz setup [--config-only]

rimz setup prints a report (multiplexer and version, project path and its kind, project trust, config path and whether it exists, and hooks grouped into installed, not installed, and not on PATH) and then acts according to how it was run. Paths under your home use ~. Installed hooks with a newer version available carry (upgrade available) after the agent name. Empty hook groups are omitted; agents found without hook-install support are omitted too. Agents with blocked hook installation stay under not installed, but are excluded from the rimz hooks install hint.

A merge names every file it wrote, merged, or left untouched. An unparseable file is left as it is, and interactive setup stops at that point until you fix it. What a merge keeps and removes is defined in the configuration guide. The hook summary points at rimz hooks install --dry-run for the exact diffs. rimz config init --force is the clean reset. The walkthrough is the setup guide.

Diagnose with doctor

rimz doctor [--audit] [--json] [--no-log-text] [--output <PATH>] [--clear]

rimz doctor reports the machine, the backend, and the room for the current directory in one pass. It does not reconfigure the room, and it exits 0 whatever it finds; read the closing line, or the JSON, to act on the result. It briefly starts configured language servers that are not already running to check startup, then terminates their process groups. Without --clear or --output, RimZ writes no state, including with --audit or --json; a configured server may write its own files. --clear writes a history watermark; --output writes the named report file.

Plain --json carries multiplexer log text verbatim, up to 8 KiB per log record; add --no-log-text to omit it without changing other report sections.

The human report opens with the RimZ version, OS user, and binary path, then prints these sections in order. A section marked conditional appears only when it has something to show.

Each row carries a glyph: ✓ healthy, ! degraded but working, ✗ broken, with the fix beside it. The closing line counts problems and warnings and names their sections, for example ✗ 2 problems in HOOKS, MESSAGES · ! 1 warning in DIAGNOSTICS, or prints ✓ everything checked is healthy. Only incidents still in the investigate state count toward it; contained, recovered, and expected incidents are summarized as context. Hook drain lag counts as one warning per episode until 15 quiet minutes pass; its row shows the worst sampled lag and peak sampled pending bytes.

The LSP startup checks use the current checkout's effective configuration and root markers. Running servers are not started again; untrusted project servers are not executed. Checks run concurrently, waiting up to ten seconds for startup. Failures, invalid configurations, and untrusted servers each count as a problem; a timeout is a warning. JSON adds lsp.ready.checks, sorted by server name, with outcomes running, started, failed, timed_out, invalid, or untrusted. No resolved workspace means an empty check array. When the checkout's LSP configuration cannot be loaded, the machine-wide table still renders, lsp.ready.checks_error carries the error, and doctor counts it as one problem.

--clear stamps the workspace, so records written before that moment stay out of this and every later report. The diagnostic files, server logs, and event log stay on disk. It fails when the current directory does not resolve to a workspace.

How to read each section and fix what it flags is the troubleshooting guide. Static adapter coverage is a separate command, rimz coverage.