Maintenance CLI

These commands inspect, upgrade, repair, clean up, and remove RimZ. Which ones write, and what they reach:

"The current workspace" is the one the current directory resolves to, or --root; gc also follows the running room's identity (room resolution). All of these take the global flags. Configuring the machine is rimz config, and the workflows for a stuck room, a stale pane, and full removal are in the troubleshooting guide.

Check adapter coverage

rimz coverage [--wiring] [--json]

rimz coverage prints what RimZ can observe for each agent, read from the adapters' own declarations. It needs no room and writes nothing. The default report is one grid, WHAT EACH AGENT GIVES YOU, with an agent per row and the six user capabilities as columns:

$ rimz coverage
RimZ coverage

WHAT EACH AGENT GIVES YOU
AGENT        state  live  history  account  ask  subagents
claude       ✓      ✓     ✓        ✓        ✓    ✓
codex        ✓      ✓     ✓        ✓        ✓    ✓
amp          ✓      !     !        !        ✓    ✗
…
  legend ✓ full   ! partial   ✗ unsupported

DETAIL
CAPABILITY  DETAIL

claude
state       ✓ the card opens at session start, follows every turn, and clears when Claude exits
…

Under each grid, DETAIL repeats every cell for every agent with its reason: what a full cell covers, what a partial cell shows and where it stops, and why an unsupported cell is empty. Valid agent plugins appear after the built-in agents. What each capability and mark means for your work is in agent support.

Each JSON matrix is {"agents": [...], "rows": [...]}. A row is one capability, concern, or signal: {"label", "cells"}, with one cell per entry in agents, in the same order. A cell is {"state", "detail"}, where state is ok, partial, or absent.

Resolve a workspace

rimz workspace resolve [PATH]

resolve prints, as JSON, the workspace that PATH (default .) belongs to. It writes nothing, so a script can call it to learn which room a directory maps to before running other tools.

$ rimz workspace resolve
{
  "workspace_id": "ws_f89e49906df0621ad2765112",
  "project_root": "/home/me/code/query-engine",
  "cwd_project_root": "/home/me/code/query-engine",
  "root_class": "repo",
  "worktree_root": "/home/me/code/query-engine-worktrees/docs",
  "worktree_branch": "docs",
  "session_name": "query-engine-f89e",
  "mux_hint": null
}

Move a store after the project moves

rimz workspace migrate <OLD_ROOT> <NEW_ROOT>

The workspace ID is derived from the project root, so a project moved on disk resolves to a new, empty workspace. migrate carries the old store over: it moves the store directory to the new ID and rewrites the workspace identity in its events, queued messages, and workspace record. OLD_ROOT may be a path that no longer exists. Run it before starting a room in the new location.

$ rimz workspace migrate ~/code/query-engine ~/src/query-engine
migrated ws_f89e49906df0621ad2765112 -> ws_0b7d3c1e5a9f2468ace13579
  old root: /home/me/code/query-engine
  new root: /home/me/src/query-engine
  messages: 12
  events:   4810

It refuses, and changes nothing, when:

Rotate the event log

rimz workspace rotate-events [--max-bytes <SIZE>] [--archive-older-than <DURATION>]

rotate-events archives the current workspace's active event log once it reaches --max-bytes, and a fresh log starts with the next event. Rotation keeps the prior-agent carryover, so the sidebar and a later rebirth still know the room's agents. The command then deletes archives older than --archive-older-than. RimZ also rotates on its own when the log reaches 64 MiB, so you rarely need this by hand.

SIZE is an integer with an optional unit and no space: none or B for bytes, K or KB, M or MB, G or GB for powers of 1000, and KiB, MiB, GiB for powers of 1024.

The output opens with event-log rotated (then the bytes rotated, the archive path, and the carryover agent count) or event-log rotation skipped (then the current size and the threshold). Both end with the number of archives and bytes pruned. How rotation and carryover work is in store internals.

Update RimZ

rimz update [--version <TAG>]

update upgrades RimZ through the method that installed the running binary:

When the binary changed, update runs the new build's rimz reload, so live sidebars and dashboards move to it. If that reload fails, update exits 1 with RimZ updated, but `PATH` reload exited with STATUS; rerun `rimz reload` .

--version <TAG> picks the release:

A script or downloaded install stops with a fix in these cases:

Installing and choosing a method is covered in the installation guide.

Reload running sidebars

rimz reload [--repair]

reload moves every running RimZ surface on the machine to the binary you invoke, without changing any pane. It runs from any directory, inside or outside a room. One run:

• publishes the invoking build as the target of every live room, so each room's sidebars restart onto it in place;
• stops each live room's running hook drainer after its current frame, then nudges a replacement on the recorded build; a room with no running drainer starts none;
• upgrades a room's Zellij presence plugin when its build or configuration differs, and leaves a current one alone;
• restarts held rimz stats --refresh dashboards on the new build;
• reaps sidebar processes whose pane is gone, and sweeps leftover processes and runtime files from stopped sessions;
• restarts the shared web daemon if it is running. A stopped daemon stays stopped, and a failed restart prints a warning without failing the reload.

It never starts a stopped session, creates or closes a pane, or touches an agent process. If the new build fails to start, each sidebar keeps running on its old build.

A drainer that cannot stop within the bounded wait keeps its old build until it goes idle or a later reload succeeds. Reload reports it and continues with the other surfaces and rooms. Pending hooks stay queued across a restart.

A room whose sidebar pane was closed has nothing to reload, so the report counts it and names the verb that fixes it: 1 room with no sidebar reporting in; mount or replace it with `rimz reload --repair`. That room still counts as a live session, so No running sidebars to reload. never covers this case. The same line covers a sidebar running a protocol this build cannot signal, which repair replaces rather than mounts. --repair, or rimz sidebar repair on its own, is what does it; with --repair already passed the line is left out, since the repair runs next.

The report prints a line per non-zero count:

--repair runs rimz sidebar repair after the reload finishes, as a separate step: a repair that cannot run does not undo the reload. How a sidebar hands over to a new build is in sidebar internals.

Repair sidebars

rimz sidebar repair

sidebar repair fixes the sidebar panes themselves, in every live room: it adds a missing sidebar, closes duplicate or unresponsive ones, and restores a sidebar's docking and width. A replacement pane must start and report on the current build before the old one closes. It publishes no build; use reload for that.

The repair rules are in sidebar internals.

Reset a wedged room

rimz reset [--yes] [--no-start] [--hard] [--account <KIND@NAME>]... [PATH]

reset tears down the room for PATH (default .) and rebuilds it empty. Use it when a room is stuck, or came back wrong after a reboot. In order, it:

1. deletes the room's multiplexer session and purges the multiplexer's resurrection cache for it;
2. signals the room's orphaned processes and clears disposable runtime classes, keeping lock inodes;
3. cancels the room's active supervised runs, which report canceled to anyone waiting on them, and drops every pending stop --when-idle request;
4. archives the active event log, clears rebuildable caches and its recorded provider accounts;
5. starts the room again and attaches, with no prior agents recovered.

Your agents' own session files and the room's archived records stay on disk. A plain reset keeps the prior-agent carryover as history; the reborn room still starts with no agents. A plain reset run with no terminal (--yes from a script) ends none of the top-level agents: the ones the old room lost stay parked, and rimz agents resume <lane> brings a lane back. Their subagents are closed (rimz.child-not-resumed), because a resumed parent relaunches any children it still needs. With --hard, the prior-agent carryover is deleted: those agents are no longer offered for recovery, even if their identities remain in the pending record.

On a room with sandbox isolation, a process an agent left running in the background can still be inside the agent's sandbox view, using the /tmp that --hard deletes. After step 2, reset --hard ends every such process and reports Sandbox views: ended N processes still inside the room's sandbox views. If one cannot be ended, reset stops before step 3 with each remaining pid and command line: stop them, then run rimz reset --hard again. Processes outside a sandbox view are left alone, and a plain reset ends none (temp units).

rimz accounts use moves a running room's launch default in place; reset --account rebuilds the room under a different account instead.

Reset refuses before prompting or changing anything when --mux names a backend other than the one the room runs on. A listed session without its own live sidebar also refuses if another room holds the workspace: close that leftover session from its multiplexer instead. Without --yes and without a terminal it fails with `rimz reset` deletes the session and sweeps its processes; pass --yes to confirm without a terminal. Answering anything but y prints Reset aborted; nothing changed. and exits 0.

The report goes to stderr before the rebuild:

The report names the session deletion, process sweep, preserved temporary files, archive path, canceled runs, removed cache entries, and whether the prior-agent rollup was kept. Hard reset additionally removes audit, owned state, tmp/, shared/, and out/.

For a room written by an older RimZ, reset instead removes the whole room and its runtime tree, without carrying over history. If a running room holds that workspace, reset refuses with the held-room error before prompting or changing anything; close that session from its multiplexer first. For other rooms, soft reset keeps transcripts, message history, run records, agent scratch and handled skill copies, agent temp files, the room's shared/ and out/ directories, and standing fleet budget choices. Both resets clear handleless skill copies in cache/skills/. --hard deletes audit/, owned/ except owned/runs/, tmp/, shared/, out/, the active log and carryover; the rotated log archive remains. Run waiters can read Canceled after reset; terminal run records are reclaimed after the owned GC grace. Neither reset of a current room removes state locks/.

What reset does to the store is in store internals.

Sweep stale state

rimz gc [--older-than <DURATION>] [--dry-run] [--json] [--all]

gc removes state that has outlived its use and keeps anything dirty, unlanded, or unknown. By default it sweeps only the current room: --root overrides the running room's identity, which otherwise takes precedence over directory resolution. --all adds every room and shared machine state, while store maintenance and worktrees remain current-room only. Resolution failure exits non-zero and asks you to run inside a room or pass --root.

With either scope, a current room written by an older RimZ refuses the command with a layout error; run rimz start or rimz reset there to replace it with a fresh room.

GC never creates a store. Without one, messages, event log, agent cache, and repository worktrees show skipped — no rimz store here; outside a repository, worktrees shows skipped — not inside a git repo. An absent room state root produces no room class block.

The worktrees area is the one that reaches past RimZ's own files: removing a tree deletes that checkout and its files, and deletes the branch behind it. A dirty, occupied, or unmerged tree is kept and reported rather than forced. The branch is the exception: when git branch -d refuses it as unmerged, RimZ compares its content against the base and deletes it with git branch -D once that comparison says the work already landed. A branch it cannot prove landed is kept.

Automatic sweeps

Every open room runs gc on its own once a day, with the gc.older_than cutoff. The first sweep waits until the room has been up for 5 minutes, so a room coming back from a reboot finishes restoring its panes before the worktree area judges them. The last sweep time is kept per workspace, so a reboot does not reset the day. Each run, failed or not, appears in rimz stats --assists as a ♻ line. Set gc.auto = false (configuration) to sweep only by hand. While a machine config file fails to load (rimz config get names the error), automatic sweeps pause rather than fall back to the defaults.

One of those helpers is elected for a machine sweep when the last automatic machine attempt is at least 24 hours old, or none is recorded. It runs the same scope as --all, including its own room; the other helpers sweep only their rooms. Failed machine attempts also wait a day before retrying. Closed rooms wait for that elected sweep or a manual --all; they do not start helpers themselves.

The report

gc shows progress while it runs, then prints a line per area with its verdict: ✓ healthy, ✦ acted, ⚠ warning, ✗ failed, – skipped. Each kept, removed, or failed worktree gets its own line under worktrees. Kept lines name every reason (in use, uncommitted changes, unlanded work, unknown) and the holders when present; removed lines say landed, with the branch-deletion outcome.

The header gives total reclaimed bytes and the area count/cutoff, ending in · room <workspace-dir> or · machine. It then lists the selected rooms with one class · file count · bytes row per lifetime class, followed by the eight area verdicts and any kept/removed worktree reasons.

The second line counts the areas that ran: normally checked 7 of 8 areas for a room, with workspaces skipped and a hint to use --all. Dry runs skip another four store and schedule areas. The header adds a problem count (· 1 problem) when a worktree removal failed, a dead workspace could not be removed, a workspace record was unreadable, or the event log needed repair. Problems do not change the exit code: gc exits 0 whenever the sweep completes. Automatic-sweep assist records carry scope (room or machine) and class_bytes, reclaimed bytes by class for the helper's own room only, even in a machine sweep. Other assist totals cover the run's full scope.

Owned state has a seven-day grace; audit files expire after 30 days or oldest-first above 64 MiB. The empty class keeps an agent's empty working directory while any retained session records it, then removes it once its directory mtime is older than seven days. The room-level directory stays while its store exists. Once the store is gone, a machine sweep removes agent directories past the same grace and removes the room-level directory when empty. Unknown entries and symlink targets stay untouched. The workspaces area reports both the files removed and the agent directories still within the grace. --older-than does not change those policies. Rooms written by an older RimZ are removed along with their runtime trees.

JSON output

What each sweep removes on disk is in store internals.

Uninstall RimZ

rimz uninstall [--state] [--config] [--all] [--keep-binary] [--yes]

uninstall removes RimZ from the machine. It prints a preview of every root, room, hook, skill-link root, timer, and binary it will touch, plus the account homes it keeps, asks [y/N], and then reports each removal. Preview and report go to stderr.

--all is --state plus --config. --yes skips the prompt and is required when stdin is not a terminal. The paths above are the defaults; RIMZ_HOME moves them. Anything else under the home, such as cache/ and the run link, is removed.

Run it from outside any RimZ room: inside one it fails with detach and rerun from outside the RimZ room. A Homebrew install also needs brew uninstall rimz. When any step fails, the rest still run, and uninstall exits 1 with uninstall incomplete: and one line per failure. A binary it had no permission to delete gets a sudo rm PATH line to run.

Check that the binary runs

rimz ping
test "$(rimz ping)" = ok

ping prints ok and exits 0 when the binary starts and its global flags parse. It touches no room, so it is the cheapest liveness probe for a script or health check.