Pitroom README

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 · 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.

And more

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.

Benchmarks

Measured on a real, public repository: PI-Desktop at commit c2bfe35, 2,349 tracked files and about 419,000 lines of TypeScript and Rust. Eight questions of the kind an agent asks before it changes code, run as one read-only crew (pitroom crew, at most four workers at a time) on OpenCode's free muse-spark-1.3-contributor-free model.

In short: on that repository eight questions took 156 s of wall clock, and the workers read 5.5 million tokens and handed the agent 7,684 (715× less); a later audit found some of the answers incomplete. On React, Django and Kubernetes, four free models matched gpt-6-sol on nine bounded questions, and in a planted-bug review test almost every model found almost every bug. The tables, and what they do not show, are below.

What this does not show

• One run per question and model: there is no variance here. The questions are bounded lookups that grep can answer, so they do not show how a model handles design questions or large edits, and four free models and gpt-6-sol all scoring 100% says the test is easy at the top, not that they are equal.
• An open-ended task ("find up to five spelling mistakes in docs/") did not finish: it was stopped after 19 minutes and 57 tool calls. Give workers bounded tasks.
• "Tokens processed" is what the workers read and wrote. What your agent would have spent doing the same reading itself is an estimate, not a measurement: the savings figure assumes it would process about the same tokens. The $0 worker cost is because the model is free.
• The hand check covered key claims, not every citation.

To repeat it on your own repository: pitroom crew -d <repo> -g bench "<question 1>" "<question 2>" …, then pitroom wait -g bench, pitroom show <run> and pitroom savings --models.

Platforms

macOS and Linux are the main platforms. Windows runs the same test suite in CI (Windows Server, Node 22 and 24, with the fake workers; the worker CLIs themselves are not run there), with these differences:

• The git guard is the same two layers as elsewhere, built on the sh.exe that Git for Windows ships: git's own config (a reference-transaction hook that refuses every ref update, and push URLs that go nowhere) is always on; the git shim (git.cmd for cmd.exe and PowerShell, git for Git Bash) adds friendly refusals and also blocks add, restore, clean and the rest. A worker that starts git without a shell (a plain CreateProcess) skips the shim, and is left with the config layer. pitroom doctor says which is in effect. It is verified in CI with Git for Windows, not yet with the worker CLIs on a real Windows machine.
• The launcher is pitroom.cmd (%USERPROFILE%\.local\bin), started with the Node that ran pitroom install or the one in PITROOM_NODE; it does not search for another Node.
• Line endings. Pitroom compares and applies patches byte for byte. Keep core.autocrlf off (or an eol=lf in .gitattributes, as this repository has); a checkout converted to CRLF has not been tested with apply.
• A read snapshot's files are not made read-only (Windows has no POSIX modes), and a --verify command runs in cmd.exe, which reports a missing command as is not recognized.

Quick start

You need Node.js 22.13+ and at least one worker CLI: OpenCode v2+ (the default worker, with free models), Codex CLI, Claude Code Gemini CLI (beta; it needs an API key from Google AI Studio, a Google account sign-in no longer works for it) Qwen Code (beta; any OpenAI-compatible provider, a DashScope key, or a local model) Kilo Code's CLI (beta; npm i -g @kilocode/cli, its 500+ models and providers) or the Antigravity CLI (beta; agy, signed in with your Google account).

1. Install: pick your agent

Claude Code

claude plugin marketplace add ATASTECH/pitroom
claude plugin install pitroom@pitroom

_{Inside a session: /plugin marketplace add ATASTECH/pitroom, then /plugin install pitroom@pitroom.}

Codex

codex plugin marketplace add ATASTECH/pitroom
codex plugin add pitroom@pitroom
npm i -g pitroom

Gemini CLI

gemini extensions install https://github.com/ATASTECH/pitroom
npm i -g pitroom

Cursor

npm i -g pitroom
pitroom install --mcp --client cursor

_{This adds pitroom mcp to ~/.cursor/mcp.json and leaves the other servers in that file alone; restart Cursor if it does not show up. Cursor gets the ten MCP tools described below. The skills are linked into ~/.agents/skills and ~/.claude/skills (--no-skills skips that), and Cursor's documentation lists both as places it loads skills from; we have not run that in a Cursor session, and a Cursor forum report says its CLI (cursor-agent) does not load ~/.agents/skills. pitroom install --mcp --dry-run shows what it would change first.}

Any agent that speaks MCP (Claude Desktop, and the ones above too)

Pitroom is also an MCP server on stdio: ten tools instead of shell commands and skills (pitroom_run, pitroom_wait, pitroom_show, pitroom_info, pitroom_review, pitroom_audit, pitroom_apply, pitroom_discard, pitroom_revert, pitroom_stop), the runs as resources, and four prompts. The tool definitions sit in the client's context for the whole session, so they are kept small: about 1.9k tokens. It is listed in the MCP Registry as io.github.ATASTECH/pitroom, so clients that browse the registry can find it. After npm i -g pitroom, let Pitroom register itself in the clients it finds (Claude Code, Codex, Gemini CLI, Cursor, Claude Desktop):

pitroom install --mcp               # also links the skills; add --no-skills to skip that
pitroom install --mcp --dry-run     # only say what it would do
pitroom install --mcp --client cursor,claude-desktop

It registers the launcher by its full path (apps like Claude Desktop start without your PATH), changes Claude Code, Codex and Gemini CLI with their own mcp add command (user scope where it has one), merges the JSON of Cursor and Claude Desktop without touching their other servers (keeping a .bak-pitroom backup, and leaving a file that is not valid JSON alone), skips what is already registered, and pitroom uninstall removes it again. pitroom doctor shows where it is registered. Restart the client afterwards. Or do it by hand:

claude mcp add pitroom -- pitroom mcp
codex mcp add pitroom -- pitroom mcp
gemini mcp add pitroom pitroom mcp

or, for Cursor (~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) and others:

{ "mcpServers": { "pitroom": { "command": "pitroom", "args": ["mcp"] } } }

Each tool runs the matching pitroom command, so every rule of the CLI applies unchanged (permission profiles, git guard, isolation, read snapshots). A run is waited for up to waitSeconds (default 50), then comes back as "still running" with its id for pitroom_wait; keep it below your client's tool timeout. The server works in the directory it is started in: the client's for stdio, or the one -d DIR names (Claude Desktop starts it elsewhere, so give it "args": ["mcp", "-d", "/path/to/project"]); the tools' dir argument picks another per call.

Any other agent (a plain shell) or just the CLI

npm i -g pitroom
pitroom install

Pick one path, not several: doctor warns if the skills load twice. The plugins alone do not put pitroom on your PATH, so install it from npm too if you want to run it yourself (watch, models, savings, the status line).

2. Check the setup

pitroom doctor --probe

It checks the worker CLIs, models, permissions and skills, and runs one live round trip.

3. Use it

Pitroom is a toolbox, not a procedure: your agent uses it when it helps, or you ask explicitly:

Use pitroom to map how sessions are created and invalidated, then propose a fix. Split this into a pitroom crew: audit auth, billing and uploads for missing input validation.

Or start a worker yourself and read its receipt:

pitroom "Which files read the session cookie? Cite file:line."
pitroom -W gemini:gemini-3.8-flash "…"   # the same on another worker (see Workers below)
pitroom savings          # what all your runs saved so far
pitroom models           # what each worker offers, what it costs you, what it used

# update
claude plugin update pitroom@pitroom
codex plugin marketplace upgrade pitroom
npm i -g pitroom@latest

# uninstall
claude plugin uninstall pitroom@pitroom
codex plugin remove pitroom@pitroom
pitroom uninstall && npm rm -g pitroom

Modes

Read snapshots. With secret-looking files in the directory, a read run reads a snapshot of your project's current state (uncommitted and untracked files included) without them and without git-ignored files, made from git objects, kept once per state and shared by every read run on it (twenty workers, one snapshot), and cleaned up after three days or by pitroom clean. Nothing is copied back: a read run has nothing to land. Its files are read-only, and the paths a worker cites are turned back into your project's. With no secret-looking files nothing changes: the worker runs in place. --in-place (or "readIn": "project" in the config) reads the directory itself, e.g. for a task that needs build output; "readIn": "snapshot" always uses one.

Answer cache. Ask the same read question on the same code and you get the earlier answer back at once, with no worker run: pitroom ⟲ cached answer · the same question on the same code as run … · no worker ran. "The same code" is exact: the commit and every working file, uncommitted and untracked ones included (git-ignored files are not code), so any edit makes it a new question. Only answers that held up are reused (the run finished, every file:line reference checked out, no audit disputed it) and only for 7 days ("cacheDays" in the config, 0 turns it off, or PITROOM_CACHE_DAYS). Follow-ups, web runs, plan tasks, reviews, audits, --verify runs, parallel work (crews) and changes are never answered from the cache, and --fresh asks a worker anyway (its answer is the one reused from then on). Not part of "the same code": git-ignored files (build output, installed dependencies) and the worker or model that answered; when a question depends on them, use --fresh.

pitroom run "Find every place we build SQL strings by hand; file:line and risk"
pitroom run -i --link node_modules --verify "npm test" "Fix the off-by-one in paginate() and add a test"
pitroom run -w "Rename getUserById to findUserById in src/ and fix imports"
pitroom run --continue last "Now handle the empty-page case too"

Long jobs: --bg returns immediately; pitroom wait <id> blocks for up to 9 minutes (made for agents with 10-minute tool limits; exit code 75 means "call wait again").

Workflow

Pitroom ships a full development methodology as skills, adapted from superpowers so that its subagents are cheap workers: your agent brainstorms and plans with you, then executes the plan task by task while workers do the typing and a second model does the reviewing.

Audits

Pitroom checks every path:line a worker cites, which proves a line exists, not that the claim about it is true. An audit asks a second worker to verify an answer's key claims against your project and to say AGREE, PARTIAL or DISAGREE, with the claims it disputes.

pitroom audit <run>            # now: re-check one read run (-W picks the auditor)
pitroom run --audit "…"        # re-check this run's answer when it finishes (--no-audit skips it)

or set "audit": 0.1 in the config (or PITROOM_AUDIT=0.1) to have about one read run in ten audited, in the background, without your agent asking. The same run is always in or out of the sample.

Corrections ("auditFix": true, or PITROOM_AUDIT_FIX=1; off by default). When an audit says PARTIAL or DISAGREE and names the claims it disputes, the answer goes back to the worker that gave it: a follow-up in its own session (which still holds what it read) with the disputed claims, to check against the files (the auditor can be wrong too) and to answer again in full, saying under OPEN ISSUES which claims it accepted. One round only: a correction is never sent back again. The audited run's card and pitroom show name the correction run (── fix: …). Every built-in worker can continue its session, which this needs.

A focused sample ("auditFocus": true, or PITROOM_AUDIT_FOCUS=1; off by default). With an audit rate set, the sample leans to where audits find the most: the rate is doubled for a question that asks for all of something, a list or a count, doubled again for a worker whose audited answers were confirmed less than half the time (3 audits or more in 30 days), and halved for one whose last 5 or more were all confirmed. --audit and --no-audit are never changed; the run records the chance it got and why.

Evals

Your own benchmark, on your own code: questions with known answers, put to the workers you want to compare, and scored.

pitroom eval questions.json -W opencode -W codex:gpt-6.1-sol    # every question to every worker, as one group
pitroom eval questions.json --json                               # the same as JSON: truths, rows, a summary per worker

{
  "questions": [
    { "id": "def", "kind": "definition", "task": "Which file and line define `export function loadConfig(`? The SUMMARY line must be only path:line.", "truth": { "grep": "^export function loadConfig\\(", "regex": true, "dir": "src" } },
    { "id": "count", "kind": "count", "task": "How many files under src/ contain the word effective? The SUMMARY line must be only the number.", "truth": { "grep": "effective", "word": true, "dir": "src" } },
    { "id": "list", "kind": "set", "task": "List every file under src/ that mentions node:sqlite. The SUMMARY line must be only the paths, separated by commas.", "truth": ["src/cli/commands.ts", "src/core/history.ts"] }
  ]
}

A truth is written down ("path:line", a number, a list of paths) or looked up when the eval starts with git grep (grep, and optionally dir, word, regex, exclude), so it stays right as the code changes. Scoring is that of the multi-repo benchmark: a definition gets 1 for the exact path:line and 0.5 for the right file, a count only for the exact number, a list the F1 of the paths it names (from the SUMMARY, else the DETAILS). Each worker answers for itself: no fallback, no audit, no cached answer. The runs are an ordinary group, so pitroom watch -g, the dashboard and the history show them.

Crews

A real crew over this repository, four questions at once on a free OpenCode Zen model:

pitroom crew -g v04-demo \
  "Where does Pitroom enforce the maxParallel queue, and how does a waiting run react to pitroom stop? Cite file:line." \
  "How does the git guard shim resolve git aliases? Cite file:line." \
  "Which fields of OpenCode v2 events does the parser read for token usage, refused tool calls and errors? Cite file:line." \
  "How does pitroom apply -g decide which patches to apply and in what order? Cite file:line."
pitroom watch -g v04-demo --json   # what the primary agent follows, one line per change:

{"event":"started","run":"20260930-102812-a65d","mode":"read","task":"Where does Pitroom enforce the maxParallel queue, and how d…"}
{"event":"progress","run":"20260930-102812-a65d","steps":3,"tools":4,"last":"grep SIGINT|SIGTERM|stop.*queued|stopped.*queued"}
{"event":"done","run":"20260930-102812-a563","time":"21s","worker":"opencode (default model)","summary":"The shim resolves `alias.<sub>` via `real git config --get` in a loop …","refs":"5/5"}
{"event":"all-done","runs":4,"ok":4,"failed":0}

$ pitroom status -g v04-demo
RUN                   STATE  MODE  TIME  STEPS  WORKER                    NOW / RESULT
20260930-102812-0c0d  done   read  30s   5      opencode (default model)  Parser `src/backends/opencode/events.ts` reads …
20260930-102812-7642  done   read  27s   5      opencode (default model)  `pitroom apply -g NAME` applies finished isolat…
20260930-102812-a563  done   read  21s   2      opencode (default model)  The shim resolves `alias.<sub>` via `real git c…
20260930-102812-a65d  done   read  39s   7      opencode (default model)  maxParallel is enforced by file-based slots (`s…

Humans get the same table live with pitroom watch -g NAME; pitroom wait -g NAME --brief prints one line per worker, pitroom show <run> the full answer.

For changes, pitroom crew -i … gives every worker its own isolated copy of your current state and pitroom apply -g NAME lands the patches in order, stopping at the first conflict. Up to maxParallel workers (default 20, at most 30) run at once, the rest queue; only one --write run per repository is allowed. pitroom stop -g NAME stops running and queued workers.

Skills

Commands

pitroom run [-r|-w|-i] [-W WORKER] [-m MODEL] [-d DIR] [-f FILE]… [-t 30m] [--verify CMD] [--link a,b] [--bg] "task"
pitroom run --continue <run|last> "follow-up"
pitroom crew [-i] [-g NAME] "task 1" "task 2" …   (or --task-file with --- separators)
pitroom run -i --plan PLAN --step N [--tier T] ["notes"]
pitroom review [run | --range A..B [--plan PLAN]] [--tier T | -W T] [--bg]
pitroom audit RUN [-W worker]
pitroom eval QUESTIONS.json [-W worker]… [--json]   your questions with known answers, scored per worker
pitroom mcp [-d DIR] [--http [--port N]]   # serve Pitroom as MCP tools on stdio, or over HTTP on 127.0.0.1 (bearer token)
pitroom cooldown [--clear]
pitroom plan status PLAN [--json] · pitroom plan note PLAN "Task N: …"
pitroom status|wait|watch [run… | -g NAME]        wait: --any --brief --timeout · watch: --json|--brief --interval
pitroom dash [--detach] [--port N] [--open] [--stop]   a live page of the runs on 127.0.0.1
pitroom history [TEXT] [--model M] [--state S] [--since 30d] [--limit N] [--json]   finished runs, searchable
pitroom history stats [--since 30d] · pitroom history import   per worker and model · take in older runs
pitroom show [run]                                --patch --events --full --json
pitroom apply [run | -g NAME] · pitroom discard|revert [run] · pitroom stop [run | -g NAME]
pitroom ls [--running] [-g NAME] · pitroom clean [--days 14] [--yes]
pitroom savings [--since 7d|30d|all] [--models] [--card file.svg] [--badge]
pitroom models [worker] [--all] [--json]      models, effort levels, your costs, your usage
pitroom statusline [--then CMD] · pitroom hook-card
pitroom doctor [--probe] · pitroom config · pitroom init [--model ID] [--fallback A,B] [--yes] [--force] · pitroom install [--copy] [--force] [--mcp [--client A,B] [--no-skills] [--dry-run]] · pitroom uninstall

History

pitroom history "login bug"            # full-text search over the task, the answer and the steps
pitroom history --state problem --since 7d
pitroom history stats --since 30d      # runs, success rate, average time and tokens per worker and model

Seeing Pitroom at work

{
  "statusLine": { "type": "command", "command": "pitroom statusline --then 'your-own-statusline'" },
  "hooks": {
    "PostToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "pitroom hook-card", "timeout": 10 }] }]
  }
}

How it works

Workers

A worker is named by a target: backend[:model].

pitroom run "…"                                          # preferred worker (config "worker", default opencode)
pitroom run -W opencode:opencode/space-bunny-free "…"    # a specific backend and model
pitroom run -W 'codex:#low' "…"                          # the model from config "models" (not Codex's default), low reasoning effort
pitroom run --effort high "…"                           # model#level (Codex, Claude Code, OpenCode; Gemini CLI has no effort option)
pitroom run -W claude:haiku "…"                          # Claude Code on a cheap model
pitroom run -W gemini:gemini-3.8-flash "…"               # Gemini CLI (beta; needs a Google AI Studio API key)
pitroom run -W qwen:qwen3-coder-plus "…"                 # Qwen Code (beta; your provider from ~/.qwen/settings.json)
pitroom run -W kilo:kilo/<model> "…"                      # Kilo Code's CLI (beta; any model from `kilo models`)
pitroom run -i -W antigravity "…"                         # Antigravity CLI (beta; your Google account, models from `agy models`)
pitroom run -m nvidia/z-ai/glm-5.3 "…"                   # another model on the preferred worker

Models, costs and effort

worker  model        effort (* default)                 cost  runs  avg tokens  $/run   in use
codex   gpt-6.1-sol  low*/medium/high/xhigh/max/ultra   2     20    174k        -       tier standard
codex   gpt-6-sol    low/medium*/high/xhigh/max/ultra   1     1     24k         -       -
claude  haiku        low/medium/high/xhigh/max          ?     -     -           -       -

Configuration

Or put defaults in ~/.config/pitroom/config.json (flags and env still win); pitroom config shows every effective value and where it came from. pitroom init proposes a starter config from the worker CLIs and OpenCode models you have (a fallback chain of your free models, tiers when more than one CLI is installed) and writes it only with --yes; it never picks your model for you. models gives each worker a default model for targets that name none (-W codex, a "codex" fallback); a model in the target or -m still wins. tiers names workers for --tier and for plan tasks' **Worker:** lines:

{
  "worker": "opencode",
  "fallback": ["opencode:opencode/space-bunny-free", "codex"],
  "models": { "codex": "gpt-6.1-sol", "claude": "claude-sonnet-5-5" },
  "costs": { "codex:gpt-6-sol": 1, "codex:gpt-6.1-sol": 2 },
  "tiers": { "cheap": "opencode", "standard": "codex", "capable": "claude", "review": "opencode:opencode/space-bunny-free" },
  "timeout": "20m",
  "primary": "opus",
  "link": ["node_modules"],
  "maxParallel": 20,
  "audit": 0.1
}

FAQ

Where does my code go? To whichever provider your worker's model uses. For private code, point the worker at a local model. The file-reading tools of OpenCode and Claude Code workers refuse .env files and private keys; Codex workers are not restricted that way and a shell command can still read them, so keep secrets out of the folder you delegate in.

How is "saved" computed? It assumes your primary agent would have processed about the same tokens the worker did, priced at your primary's list prices (PITROOM_PRIMARY / PITROOM_PRICE), minus the worker's cost and the cost of reading the report. It is an estimate and is labelled as one.

Can the worker break my repo? It can't touch git history, refs or your index (permission profile + git guard), can't run bulk deletes, and write-mode edits are revertible with one command. The guard is not an OS sandbox: git called by absolute path from inside a script, or non-git tools, are outside its reach, which is why --isolate exists: nothing reaches your tree until you apply it.

Can the worker read my .env? In a read run, no: when the directory holds secret-looking files (.env, prod.env, private keys and keystores, .netrc, credentials.json, secrets.json), the worker reads a clean snapshot of your project instead (see below), where they are simply not present, whatever the worker CLI would have allowed. Edits (-i, -w) and reviews are different: an isolated copy (-i) leaves out git-ignored files, so a git-ignored .env is not in it, but one that is not ignored would be copied, and Pitroom warns when it sees such files (PITROOM_NO_SECRET_WARNING=1 silences the warning). A free model may be hosted by a third party: keep real secrets out of what you delegate.

What if the worker fails? Pitroom exits non-zero with the real cause (for example a default model that no longer exists) and your agent simply continues on its own. pitroom doctor diagnoses setup problems.

Responsibility

Pitroom is provided as is, under the MIT License, and is an independent project: it is not affiliated with or endorsed by OpenAI, Anthropic, OpenCode or the other tools it can drive.

You are responsible for how you use it. You decide what you delegate and to which model provider, which permissions a worker gets, and what you apply to your projects. Workers are AI agents and can be wrong: review their changes and run your tests before you rely on them. Pitroom's permission profiles, git guard and isolated copies reduce risk, but they are not a security boundary against a determined attacker or a malicious repository. Keep secrets out of the folder you delegate in, prefer isolated mode for changes you have not reviewed, and follow the terms of the worker CLIs and model providers you connect. What reaches a provider is described in the privacy policy.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md: setup, tests, the dist bundle and the commit style. Worker adapters are the easiest place to begin: docs/backends.md.

npm install
npm test          # end-to-end tests against a fake worker CLI + adapter contract tests on recorded real streams
npm run typecheck

Security: please report vulnerabilities privately, as described in SECURITY.md, not in a public issue.

Report an issue · Open issues · Security policy · Code of conduct

Credits

The workflow skills (brainstorming, planning, worker-driven development, review, debugging, TDD, verification, worktrees, finishing) are adapted from superpowers by Jesse Vincent, under the MIT License; the notice is in THIRD_PARTY_NOTICES.md.

License

Pitroom is licensed under the MIT License. See LICENSE for details.