Introduction

_{AI agents / LLMs: fetch the live index / full docs blob.}

RimZ is a realtime dashboard for harnessing agentic coding: one human and tens of agents working together in one Zellij or tmux room, where everything about every agent reads at a glance. Every agent gets a live card (state, task, context health, live cost), and the sidebar routes your attention to whichever one needs you.

_{The sidebar triages the fleet on the left; agents work in their own panes.}

RimZ stays out of your way: one lightweight binary inside the Zellij or tmux you already run. Your keybinds stay, the agent CLIs run stock, and the official web, desktop, and mobile apps keep working untouched.

That same small footprint carries the primitives harness engineering and loop engineering build on: the sidebar for observability, one command grammar for every supported agent, durable messages that steer and queue, supervised runs with exit codes for scripts and CI, and scheduled wakeups that keep the fleet on a clock. The harness itself (guardrails, policies, self-running loops) is yours to build on top.

Project status

RimZ is beta software: the basic features work smoothly for daily use, and it is still moving fast. Expect the occasional rough edge, and expect the surface to keep shifting while the design settles — commands, flags, config keys, and output formats can change between releases. The changelog records what moved in each release.

It is also heavily used, on itself. RimZ is built with RimZ: the fleet behind this repository routinely runs 50–100 concurrent agents across 10–30 parallel worktrees and PRs, and a single room stays responsive with 100+ agents from multiple providers working at once. Driven through teams and loops, most of the routine engineering here — features, bug fixes, CI repair — already flows through the harness with little hand-holding.

Read that as: ready for personal, daily use today; for production workflows that need a stable interface, wait for the 1.0 release.

What it does

_{Realtime harness dashboard, with rich information at a glance}

• Extremely Lightweight: a single binary that hooks the agents you already run, inside your familiar Zellij or tmux: same keybinds, same terminal, zero learning curve; the official CLI, web, desktop, and mobile apps all keep working
• Realtime Harness Dashboard: working state and task, model and effort, context health and compactions, live token stats and dollar cost, and the subagent tree
• Attention, Routed: one glance at the cockpit line (? 2 ! 1 …) reads the whole fleet, the column below arrives already triaged, and one click drops you into the pane that is waiting
• Know Your Pace: spending and token insight for today, week, and month, with plan and 5h/7d budget bars for providers that expose those account surfaces; one look tells you where the week is going
• Worktrees, for every Agent: open agents together, side by side in an isolated worktree with dynamic layout: claude,codex starts Claude planning beside Codex reviewing, vim,codex+term puts your editor, an agent, and a shell in one tab
• Teams, cross-model by design: pair a Fable planner with a Sol coder and launch them as one team, each role on the model best at its job (reasoning depth, instruction following, speed, price); a mixed team catches what a single model lets through, and delivers better results faster for less
• Messages, agents chat as in Slack: every agent answers to a handle (@codex, @planner); steer/queue delivery guarantees the message lands, respecting agent state and the context window, and agents talk to each other and to you inside channels
• Scriptable, End to End: rimz agents -p is claude -p for every agent, with exit codes, JSON output, streaming, and the full transcript kept, so agents drop into scripts, CI, and workflows
• Loops, Yours to Engineer: rimz loop schedules supervised runs on a clock (calendar, interval, cron, or a check-guarded watchdog that runs a command and wakes an agent on the result), and notification handlers run your own command the moment a row needs eyes
• Auto Continue, while you're Away: a rate-limit pause resumes the moment the budget window resets and transient API overload retries on a backoff ramp; agents recover themselves and keep working while you're gone
• Steer the Fleet from your Phone: when an agent stops to ask, the question reaches you in the official Claude and ChatGPT mobile apps, exactly as if you were driving the CLI by hand; answer there and it lands in the same terminal session, the fleet moving on in its panes as if you had typed it, with RimZ never between you and the official apps
• Pets, your beloved Companion: an animated sprite on the provider dashboard that keeps you company, running while the agents run and waving when one waits
• Local or Remote, Continuously: start on your MacBook or a server, close the laptop, and reattach from anywhere; the link heals itself every time you reconnect

How it works

 terminal — ghostty · iterm2 · warp · kitty · vscode …
   zellij or tmux — your keybinds, your layout

     ┌─────────┐       ┌────────────────────────────────────┐
     │ sidebar │       │ claude · codex · pi · opencode · … │
     └────▲────┘       └────▲────────────────────┬──────────┘
          │                 │                    │
          │ renders         │ types into panes   │ hooks · transcripts (.jsonl) · oauth api
          │ the fleet       │ messages · -p runs │ statusline (claude) · app-server (codex)
          │                 │                    │ extensions (pi/opencode) · …
          │                 │                    ▼
          └─────────────────┴──────────────────  rimz  ◀──  git status · /proc stats

• Agents report themselves: sessions, tool calls, live status, and blocking questions arrive the moment they happen, through each agent's own hooks, transcripts, and APIs
• RimZ drives the panes: messages, steering, and -p harness runs land as keystrokes in the agent's own pane, so every agent runs its stock CLI in a full terminal, exactly as if you typed
• RimZ fuses every channel: agent events, git churn, process stats, and account state combine into one live picture, and the sidebar renders it

→ DESIGN.md · ARCHITECTURE.md

Agent compatibility matrix

Claude Code and Codex are the daily drivers and give the best experience today.

Pi and OpenCode are in alpha — wired end to end and close behind.

Every other agent is experimental: wired and tested against its documented surface, but not yet dogfooded enough by the author, so expect the occasional bug and please report what you hit. Any of them still mostly just works: the CLI runs stock in your terminal and the official apps stay untouched.

A mark answers what you see and when, rather than how RimZ reads it:

• State — the card tracks the agent's whole life: it appears at session start, follows working, waiting, and idle, and clears when the session ends
• Live — while a turn runs: context-window fill, the token breakdown behind it, and a dollar figure for the work in flight
• History — every past session readable end to end, with per-turn tokens and dollars feeding rimz stats and the provider dashboard
• Account — your login and plan, plus each usage window (5h/7d, monthly credits, a balance) with its fill and reset
• Ask — the agent stops to ask, the card raises Waiting, and the question's own text and options reach rimz asks
• Subagents — child agents nested under the parent card as they start, each with its name, task, and model

A ◐ names its own limit: part of the detail, or the whole of it a beat late. The agent support reference spells out every cell and the mechanism behind it, and rimz coverage prints the same grid on your own machine.

Where to go next

• Quickstart gives the five-step path from install to a working fleet.
• Working with agents covers layouts, profiles, teams, and the running fleet.
• Token insight explains live cost, historical usage, and provider budget windows.
• Set up your machine covers hooks, color, pets, and multiplexer baselines.
• The sidebar documents rendered frames and the glyph legend.
• CLI reference, agent support, and configuration cover the exact command, integration, and setting surfaces.