Delegates reading, fixes, tests, and reviews to cheaper parallel worker agents, returning verified answers, exact diffs, and cost receipts.
Also known as ATASTECH/pitroom
- Stars
- 53
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.29.0
- Last commit
- Oct 29, 2026
- License
- MIT
What is Pitroom MCP?
Pitroom delegates reading, fixes, tests, and reviews to cheaper parallel worker agents, returning verified answers, exact diffs, and cost receipts. It exposes 10 tools, such as pitroom_run, pitroom_wait, pitroom_show.
Summary generated from the project's README
About Pitroom MCP server
Developers using expensive coding agents can offload repetitive tasks like reading files, applying fixes, running tests, and performing reviews to a parallel crew of cheaper workers. By delegating these legwork tasks to model-agnostic workers such as OpenCode, Codex CLI, Claude Code, or Gemini CLI, your primary agent remains in control of decisions while significantly reducing token consumption. The system runs up to 20 workers in parallel to speed up workflows and provides verified answers by checking every cited file path against your local disk.
Setup involves using your existing worker CLI tools, which can include local Ollama models, free tiers, or paid versions. Pitroom manages these workers through a local dashboard and provides detailed receipts that show token usage, compression ratios, and estimated cost savings. It maintains safety through a git guard that prevents unauthorized commits or resets, and an isolate mode that runs workers in a private copy of your current state to prevent repository pollution.
What you can do with it
- 1Reducing expensive token consumptionHand off heavy file reading and scanning tasks to cheap workers so your primary model only receives the final answer.
- 2Running parallel development tasksExecute multiple research or implementation tasks simultaneously using a crew of workers to finish work faster.
- 3Verifying code changes safelyApply patches from workers in an isolated environment to ensure they do not corrupt your main repository.
- 4Tracking development costsMonitor exactly how much money and how many tokens are saved by using cheaper models for sub-tasks.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pitroom MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pitroom MCP in Claude Code
$ claude mcp add pitroom -- npx -y pitroom mcpInstall Pitroom MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pitroom": {
"command": "npx",
"args": [
"-y",
"pitroom",
"mcp"
]
}
}
}Install Pitroom MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pitroom": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"pitroom",
"mcp"
]
}
}
}Install Pitroom MCP in VS Code CLI
$ code --add-mcp '{"name":"pitroom","type":"stdio","command":"npx","args":["-y","pitroom","mcp"]}'Install Pitroom MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pitroom": {
"command": "npx",
"args": [
"-y",
"pitroom",
"mcp"
]
}
}
}Install Pitroom MCP in Codex
$ codex mcp add pitroom -- npx -y pitroom mcpInstall Pitroom MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pitroom] command = "npx" args = ["-y", "pitroom", "mcp"]
Install Pitroom MCP in Gemini CLI
$ gemini mcp add -s user pitroom npx -- -y pitroom mcpInstall Pitroom MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pitroom": {
"command": "npx",
"args": [
"-y",
"pitroom",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for pitroom 0.29.0 in an isolated container with no network and no keys. It answered and listed 10 tools.
Pitroom MCP tools 10
Read from the server with tools/listpitroom_runActionHand a bounded task to a cheaper worker agent. mode "read" (default): read-only research, an answer with verified file:line references. "isolate": the worker edits a private copy and you get the exact diff (then pitroom_review, pitroom_apply or pitroom_discard). "write": edits the working tree (undo: pitroom_revert). "tasks" or "scopes" run workers in parallel (read or isolate). Returns the report(s) and a receipt (a read question asked before on the same code comes back cached), or "still running" for pitroom_wait. The using-pitroom skill (or prompt) says when and how to delegate. Cancelling the call stops the run.
pitroom_waitRead-onlyWait for runs that came back "still running" and return their reports.
pitroom_showRead-onlyA run's report (live progress while it runs); patch: the exact diff; full: the untruncated answer.
pitroom_infoRead-onlyReports, changing nothing. topic: runs (latest runs; running, group), history (search earlier answers before asking again; text, state, model, since, limit), stats (success rate, time, tokens, audits per worker; since), savings (since, perModel), models (a backend's models and costs; worker, all), prices (USD per 1M tokens: the primary the savings are measured against, and each worker in use or the one named; worker), cooldown (rate-limited models being skipped), config, doctor (setup check).
pitroom_reviewActionA read-only reviewer (another worker by default) judges a run's change or a commit range ("main..HEAD"): findings with severities and a SPEC / QUALITY verdict.
pitroom_auditActionAnother worker re-checks a read run's answer: AGREE, PARTIAL or DISAGREE, with the disputed claims.
pitroom_applyActionLand an isolated run's patch (or a group's, in order) on the working tree; checked first. A patch deleting files needs allowDelete: pass it only after checking the deletions were asked for.
pitroom_discardActionDrop an isolated run's private copy (the patch is kept).
pitroom_revertActionUndo a mode "write" run's changes (refused if the files changed since).
pitroom_stopActionStop a running or queued run, or a group; cooldowns: try rate-limited models again now.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubPitroom
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 · 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
- 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.svgmakes 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 crewstarts several workers at once,pitroom watch --jsonstreams one line per change so your agent follows them live,pitroom wait -gcollects every answer,pitroom apply -glands 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
cheaptier, OpenCode's free model;standard(Codex) andcapable(Claude Code) are for tasks that need them, and an optionalreviewtier names who reviews. Gemini CLI with a free Google AI Studio key is one more cheap worker (small daily quota per model).pitroom modelsshows what each worker offers, the effort levels (low…xhigh) each model accepts, what you say it costs (costs) and what it used;--effortsets 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 <id>. - 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 applyrefuses a patch that deletes files unless your agent passes--allow-delete. - Real isolation.
--isolateruns 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 <id>(checked, refuses on conflict) orpitroom discard <id>. - Zero repo pollution. No
.pitroom/folder, no.gitignoreedits, 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 dashopens 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 historysearches 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.
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.
Stop and Discard. A running card has a Stop button, and a finished --isolate card that is not applied yet has Discard (the same as pitroom stop and pitroom discard; the patch file stays). A crew's card has the same for all its runs at once (Stop all, Discard all), and when some of its runs failed, timed out or were stopped, Retry command shows the pitroom run … --bg commands that start them again in the same crew, to copy into a terminal or hand to your agent (quoted for PowerShell on Windows, for a POSIX shell elsewhere). Each action asks once more. Nothing else can be done from the page: it never starts a run and never applies a patch. A POST needs the secret the page was served with (it changes every time the dashboard starts) and the page's own origin, so a web page on another site cannot press them.
The dashboard is a React app built once into dist/ui and served as two static files, so the CLI still has no runtime dependencies. It follows your system's light or dark theme (a button switches it).
Pitroom MCP questions
How do I add Pitroom MCP to Claude Code?
Run claude mcp add pitroom -- npx -y pitroom mcp in your terminal. Add --scope user to make it available in every project.
How do I add Pitroom MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Pitroom MCP provide?
It exposes 10 tools, including pitroom_run, pitroom_wait, pitroom_show, pitroom_info, pitroom_review.
Does Pitroom require a specific AI model?
No. Pitroom uses whichever default model your worker CLI is set to, from a free tier to a local or paid model.
Which worker CLIs can Pitroom use?
It supports OpenCode, Codex CLI, Claude Code, Gemini CLI, Qwen Code, Kilo Code, Antigravity CLI and Cursor CLI. A single group can mix several of them.
Can Pitroom make changes to my repository?
Workers can produce patches, but Pitroom never commits or pushes, and in isolate mode nothing reaches your tree until you apply it.
How does Pitroom prevent a worker from editing files directly?
Each run uses the worker's own permission rules to block git history changes, sudo, publishing and secrets, and a git guard blocks tricks like shell-wrapped git commands.
Is there a dashboard for watching runs?
Yes, pitroom dash serves a local page showing running workers, run history and statistics.