Pitroom

Pitroom

A free pit crew for your expensive coding agent

Cheaper and faster: hand the reading, fixes, tests and reviews to workers that run in parallel. Keep the decisions.

Model-agnostic · Verified answers · Receipts, not vibes · OpenCode / Codex / Claude Code / Gemini CLI / Qwen Code / Kilo Code / Antigravity workers

[Quick start](#quick-start) · Dashboard · Benchmarks · Workflow · Skills · Commands · Workers · Responsibility · Write an adapter

Your agent decides · Cheap workers do the typing · A second model reviews

pitroom dash, with sample data

---

Why Pitroom?

Claude Code, Codex and friends spend premium tokens *reading*: grepping, opening files, scanning code they'll never quote.

Pitroom goes one step further:

Your agent stays in the driver's seat. A pit crew of cheap workers does the legwork in parallel, while your agent keeps going, and hands back only the answer, the exact diff and a receipt.

Your model, not ours

No model is hardcoded.

Pitroom uses your worker CLI's default model: a free tier, a local MLX/Ollama model or a cheap paid one. Switch there and Pitroom follows.

Any worker CLI

OpenCode, Codex CLI, Claude Code, Gemini CLI, Qwen Code, Kilo Code, Antigravity CLI and Cursor CLI (the last two beta on Linux and Windows).

One group can mix them, and a fallback chain can cross them (how adapters work).

Verified answers

Every path:line a worker cites is checked on disk. A cite without its directory (ipc.ts:218, src/main/ipc.ts:218) is found in the project, and a call such as Schema.parse:432 is not mistaken for a file.

Your agent trusts what checks out and skips re-reading it.

Safe by construction

No commit, push, reset or bulk delete. A git guard stops the tricks.

In isolate mode nothing reaches your tree until you apply it.

And more

12 more features

• Receipts, not vibes. Tokens the worker burned, tokens returned to your agent, compression ratio, and an estimate of what your primary model would have charged. pitroom savings --card card.svg makes a shareable card.
• Self-healing worker chain. Free models get rate-limited or retired. List fallback workers once (fallback) and a run that hits "model not found", 429 or quota errors moves to the next model automatically, also when a plan's usage limit stops a worker part way (the next one finishes the task). Still no model hardcoded: the chain is yours.
• A crew, not just one worker. pitroom crew starts several workers at once, pitroom watch --json streams one line per change so your agent follows them live, pitroom wait -g collects every answer, pitroom apply -g lands isolated patches in order. Up to 20 workers run at once by default (maxParallel, 30 at most), the rest queue, and the fallback chain absorbs free-tier rate limits; parallel writers are refused.
• Faster, not only cheaper. Workers run in the background and side by side (up to 20 at once) while your agent keeps working, so slow reading and review stop blocking it. In the benchmark, 470 s of worker time finished in 156 s of wall clock, about 3× faster than one question after another, and your agent's own context stayed small.
• Free first, dearer only when needed. Runs and plan tasks start on the cheap tier, OpenCode's free model; standard (Codex) and capable (Claude Code) are for tasks that need them, and an optional review tier names who reviews. Gemini CLI with a free Google AI Studio key is one more cheap worker (small daily quota per model). pitroom models shows what each worker offers, the effort levels (low … xhigh) each model accepts, what you say it costs (costs) and what it used; --effort sets the level per run. Details: Models, costs and effort.
• Exact changes, even in a dirty tree. Pitroom snapshots the working tree with a throwaway git index (your index, branches and stash are never touched), so it reports *only the worker's* edits and can undo exactly those: pitroom revert .
• Your agent sets the permissions. It creates each worker with the permissions the task and your session allow (read-only, isolated copy, in-place edits, web), and a worker never widens its own. A fixed floor stays for every run: no git history changes, no sudo, no publishing, no secrets. A worker cannot land a deletion either: pitroom apply refuses a patch that deletes files unless your agent passes --allow-delete.
• Real isolation. --isolate runs the worker in a private copy of your current state (its own repository, sharing your objects read-only), uncommitted and untracked files included, then hands you a patch: pitroom apply (checked, refuses on conflict) or pitroom discard .
• Zero repo pollution. No .pitroom/ folder, no .gitignore edits, no branches. Records live in ~/.local/state/pitroom.
• Works with any agent. Fourteen Agent Skills: the superpowers development workflow run by workers, plus delegation (using-pitroom, pitroom-research, -crew, -implement), a CLI, and a Claude Code / Codex plugin whose session-start hook loads the workflow. Claude Code, Codex, Gemini CLI, Cursor, or anything that can run a shell command.
• A live dashboard and a searchable history. pitroom dash opens a local page of every run (the task, what the worker did step by step, its result and diff) with history and statistics, for the agent apps that show neither hooks nor a status line; pitroom history searches everything Pitroom ever ran. See Dashboard.
• Small. About 6,500 lines of TypeScript in the CLI, a ~210 KB CLI bundle (plus the ~1.9 MB of dashboard files it serves, with syntax highlighting for ten languages), zero runtime dependencies.

How it stays safe

Each run gets the worker's own safety mechanism set to the mode (for OpenCode, a permission profile injected through OPENCODE_CONFIG_CONTENT): no commit/push/reset/checkout/stash/clean/rebase, no bulk deletes, no sudo, a file-reading tool that refuses .env and key files (OpenCode and Claude Code workers), no web tools unless you pass --web, no subagents, no recursive delegation. Only allow/deny rules, so a headless run never stalls on a prompt. A git guard on the worker's PATH also stops sh -c "git push", env git reset, aliases and scripts from committing, pushing, resetting, stashing or touching your index. Your opencode.json is never touched. These safeguards reduce risk; they are not a security boundary (see Responsibility and SECURITY.md).

---

See it work

A real run on a free OpenCode Zen model: your agent reads ~554 tokens instead of 163,000.

$ pitroom run "Which function builds the read-only permission profile, and which bash commands does it allow?"

pitroom ✔ done · read · 30s · run 20260930-003902-3270 session ses_… · model opencode/muse-spark-1.3-contributor-free

SUMMARY: The read-only permission profile is built by readProfile() in src/profiles.ts:89. Its bash allow-list is READ_ONLY_BASH in src/profiles.ts:29-46. DETAILS:

• Allowed (src/profiles.ts:31-41): git status*:31, git diff*:32, … rg *:40, wc *:41.
• Explicit sub-denies: rg *--pre*:43, git *--output*:44, git *--ext-diff*:45.

FILES CHANGED: none

── receipt: worker processed 163k tokens in 6 steps (7 tool calls) · worker cost $0.000 · returned ~554 tokens, 294× compression · est. saved $0.152 vs Claude Sonnet

Every run prints a receipt, and pitroom savings adds them up (--card writes this shareable card; the numbers here are sample data, and a real measurement follows in Benchmarks):

---

Dashboard

pitroom dash --detach prints the address of a live page on 127.0.0.1 (this machine only; it reads your runs and changes nothing but the two actions below). It is for the places where hook messages and status lines do not reach, such as the Claude Code and Codex apps: open it in a browser or in the app's own browser pane. The skills tell your agent to start it and give you the address when it runs workers in the background.

The screenshots below show sample data (an imaginary shop-api project), not a real one.

Live. What is running now, and the latest runs. Running cards show a timer, the worker's last words and its animated pixel mascot (a finished card shows the worker's logo); finished ones show the result and, for reviews, the findings.

Cards, audits, history, Stats, and Stop/Discard

Click a card and it grows into a panel with the task, what the worker did step by step (files read, searches, commands, edits, with times, failed ones marked), its result, the files and diff it changed, and the details (model, tokens, cost, fallbacks, reference check).

Audits and skipped workers show on the card. A research answer that another worker re-checked (Audits) carries an audited · agrees / partly agrees / disagrees badge and, when it disagrees, the claims it disputes; a worker left out because its quota ran out is listed under the details ("Skipped … cooling down until 14:05", see pitroom cooldown).

History searches everything Pitroom ever ran (the full text of tasks, answers and steps), with filters by state, model and period; each run opens as the same card as on Live. Stats shows runs, success rate, time, tokens and savings, per worker and model and per day.

<img src="docs/dash-history.png" width="49%"