pitroom 0.6.3 → 0.6.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pitroom",
   "description": "A free pit crew for your expensive coding agent: the superpowers development workflow, run by cheap workers. Delegate research, fixes, tests, reviews and whole plans from Claude Code, Codex or any agent to OpenCode, Codex or Claude Code workers, with receipts that prove the savings.",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "author": {
     "name": "TahaAtas"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pitroom",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "A free pit crew for your expensive coding agent: delegate research, fixes, tests, reviews and parallel investigations to cheap worker agents running your own models, with verified answers, exact diffs and cost receipts.",
   "author": {
     "name": "TahaAtas"

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.6.5
+
+### Models, costs and effort
+- `pitroom models [worker] [--all] [--json]` lists what Codex (from its model cache), Claude Code (aliases) and OpenCode (`opencode models`) offer, the effort levels each model accepts, your costs and what your own runs used (runs, average tokens, reported dollars).
+- Config `costs` (`{"codex:gpt-6-sol": 1, "codex:gpt-6.1-sol": 2}`): your relative cost per model. Pitroom cannot know vendor prices, so it does not guess them; `pitroom doctor` prints the cost of the models in use and notes a cheaper one you priced.
+- `--effort LEVEL` for every worker (`model#level`: Codex effort, Claude Code `--effort`, OpenCode variant). The skills tell the agent to pick the cheapest model and the lowest effort that fits.
+- Fix: a target that names only an effort (`codex:#low`) skipped the configured `models` default and ran the vendor's own default model. It now gets the configured model with that effort. A Codex or Claude Code worker with no pinned model gets a warning.
+
+### More workers, free first
+- Up to 20 workers run at once by default (`maxParallel`), 30 at most; before, the default was 4. The rest queue and the fallback chain absorbs free-tier rate limits.
+- An optional `review` tier in `tiers` names who reviews a run (and needs no same-backend warning). The skills start on the `cheap` tier, OpenCode's free model, and raise a task only when it needs more; plans are written the same way.
+
+### Project files
+- `THIRD_PARTY_NOTICES.md` carries the MIT notice of superpowers, which the workflow skills are adapted from, and ships in the npm package; the README stays clean and links to it.
+- `CODE_OF_CONDUCT.md`, issue forms (bug report, feature request), a pull request template and a contact-link page for security reports.
+- `npm run bump -- patch|minor|major|X.Y.Z` moves the version in `package.json`, `package-lock.json` (which still said 0.1.0) and both plugin manifests together and adds a CHANGELOG heading; a test fails while any file disagrees or the new CHANGELOG heading still has its placeholder text.
+
+### README
+- The workflow and the architecture are SVG diagrams (they render on GitHub and on npm, unlike mermaid). The speed gain is stated with measured numbers: 470 s of worker time in 156 s of wall clock.
+- Install commands per agent as copy-and-paste blocks (Claude Code, Codex, npm), with update and uninstall; diagrams for the workflow and for how a run flows; the free-first setup, `pitroom models`, costs and effort are explained; the hard-coded version line is gone (the badges show the real versions).
+
+### Seeing Pitroom at work
+- The card hook also reaches the agent (`additionalContext`), so the user hears which worker and model ran even where the host shows no hook messages. Runs that finished without a card are announced on the next `pitroom` command.
+- `pitroom savings --models` lists workers and models with runs, tokens, cost and savings.
+
+## 0.6.4
+
+### Deleting is the user's call
+- `pitroom apply` (and `apply -g`) refuses a patch that deletes files unless you pass `--allow-delete`; nothing of the patch is applied. The run report flags deletions with a warning, for isolated runs and for `-w` runs (undo: `pitroom revert`).
+- Workers are told to delete a file only when the task explicitly asks for it, to list every deleted file, and to propose any other deletion under OPEN ISSUES instead of doing it.
+- The skills (`using-pitroom`, `pitroom-implement`, `pitroom-driven-development`, `pitroom-crew`) make the primary agent the decider: it sets each worker's permissions from the task and the user's session (read, isolate or write mode, `--web`), decides whether a deletion is wanted and passes `--allow-delete` itself, asking the user only when the worker deleted something that was not asked for. A fixed floor (no git history changes, no `sudo`, no publishing, no secrets) stays in place.
+
 ## 0.6.3
 
 ### Skills

package/PRIVACY.md

@@ -2,29 +2,45 @@
 
 _Last updated: 2026-09-30_
 
-Pitroom is a command-line tool and a set of agent skills that run on your own computer. This page says what it does with your data.
+Pitroom is a command-line tool and a set of agent skills that run on your own computer. This page says what data is involved, what for, who receives it, how long it is kept and what you can do about it.
 
 ## What the Pitroom authors collect
 
 Nothing. Pitroom has no accounts, no analytics and no telemetry, and its own code makes no network requests. No data is sent to the authors.
 
-## What happens when you delegate work
+## Data categories and purposes
 
-Pitroom starts a worker agent CLI that you installed and signed in to yourself. Whatever you ask a worker to do is handled by that CLI and by the model provider behind it:
+When you delegate work, Pitroom handles these categories of data, only to carry out that work:
 
-- the task text you or your agent write;
-- the files the worker reads in your project;
-- for reviews, the diff under review with 10 lines of context, written to a package file the reviewer reads.
+| Data | Purpose |
+|---|---|
+| The task text you or your agent write | Tell the worker what to do |
+| Files of your project that the worker reads, and its edits | Let the worker do the task; return an exact diff |
+| For reviews, the diff under review with 10 lines of context | Let a second worker review the change |
+| Run records: the task, the worker's answer, diffs, timings | Let your agent and you read results, apply or undo them |
+| Savings ledger: token counts, cost estimates, worker and model names per run (no task text, no code) | Show what delegating saved |
+| Settings you choose (`~/.config/pitroom/config.json`) | Remember your worker, models and tiers |
 
-That data goes to the provider of the worker's model, under that provider's terms and privacy policy, not under this one. Pitroom does not filter the content it hands to a worker: secrets that are committed to a reviewed range are sent as they are. Workers cannot read `.env` files or private key files through Pitroom's permission profiles. To keep code on your machine, point the worker at a local model.
+Project files may contain personal data of yours or of third parties; Pitroom does not look for it, filter it or add to it.
 
-## What Pitroom stores on your computer
+## Recipients
 
-- Run records (the task, the worker's answer, diffs, receipts and the savings ledger) in `~/.local/state/pitroom`, or in the folder named by `PITROOM_HOME`.
-- Optional settings in `~/.config/pitroom/config.json`.
-- Private working copies of your project for isolated runs, inside the state folder. They are removed when you apply or discard a run.
+Pitroom starts a worker agent CLI that you installed and signed in to yourself. The task text, the files it reads and, for reviews, the diff go to that CLI and to the provider of the worker's model, under that provider's terms and privacy policy, not under this one. Pitroom does not filter this content: secrets committed in a reviewed range are sent as they are. The file-reading tools of OpenCode and Claude Code workers refuse `.env` files and private keys, but Codex workers are not restricted that way and a shell command can still read such files, so keep secrets out of the project folder you delegate in. To keep code on your machine, point the worker at a local model. Nobody else receives data from Pitroom.
 
-Nothing is stored in your repository. To delete the records, run `pitroom clean` or remove the state folder.
+## Where data is stored and for how long
+
+- Run records and the savings ledger: `~/.local/state/pitroom`, or the folder named by `PITROOM_HOME`. Pitroom never deletes them by itself: they stay until you remove them.
+- Private working copies of your project for isolated runs: inside the same folder, removed when you apply or discard the run.
+- Settings: `~/.config/pitroom/config.json`, until you delete it.
+
+Nothing is stored in your repository.
+
+## Your controls
+
+- `pitroom clean --yes` removes run records older than 14 days (change it with `--days N`); unapplied isolated patches are kept, and so is the savings ledger.
+- Delete the state folder to remove everything, including the ledger; delete the settings file to reset your settings.
+- `pitroom discard <run>` removes a run's private working copy.
+- You choose which worker CLI and model receive your data (`-W`, `config`), and whether a worker may use the web (`--web`, off by default).
 
 ## Changes and contact
 

package/README.md

@@ -4,7 +4,7 @@
 
 ### A free pit crew for your expensive coding agent
 
-**Send the reading, fixes, tests and reviews to cheap workers. Keep the decisions.**
+**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 workers
 
@@ -20,10 +20,12 @@ Model-agnostic · Verified answers · Receipts, not vibes · OpenCode / Codex /
 <br />
 
 **[Quick start](#quick-start)** ·
+[Benchmarks](#benchmarks) ·
 [Workflow](#workflow) ·
 [Skills](#skills) ·
 [Commands](#commands) ·
 [Workers](#workers) ·
+[Responsibility](#responsibility) ·
 [Write an adapter](docs/backends.md)
 
 <br />
@@ -36,8 +38,6 @@ Model-agnostic · Verified answers · Receipts, not vibes · OpenCode / Codex /
 
 </div>
 
-> **Current version: 0.6.0.**
-
 ---
 
 ## Why Pitroom?
@@ -46,7 +46,7 @@ Claude Code, Codex and friends spend premium tokens *reading*: grepping, opening
 
 Pitroom goes one step further:
 
-> **Your agent stays in the driver's seat. A pit crew of cheap workers does the legwork, and hands back only the answer, the exact diff and a receipt.**
+> **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.**
 
 <table>
 <tr>
@@ -98,8 +98,11 @@ In isolate mode nothing reaches your tree until you apply it.
 
 - **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. 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. A queue (`maxParallel`) keeps free tiers from rate-limiting you; parallel writers are refused.
+- **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](#benchmarks), 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. `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](#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 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 <id>` (checked, refuses on conflict) or `pitroom discard <id>`.
 - **Zero repo pollution.** No `.pitroom/` folder, no `.gitignore` edits, no branches. Records live in `~/.local/state/pitroom`.
 - **Works with any agent.** Fourteen [Agent Skills](https://agentskills.io): 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.
@@ -107,7 +110,7 @@ In isolate mode nothing reaches your tree until you apply it.
 
 ### 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`, no `.env` or key files, 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.
+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](#responsibility) and [SECURITY.md](SECURITY.md)).
 
 ---
 
@@ -131,77 +134,91 @@ FILES CHANGED: none
    · returned ~554 tokens, 294× compression · est. saved $0.152 vs Claude Sonnet
 ```
 
-Every run prints a receipt, and `pitroom savings` adds them up:
+Every run prints a receipt, and `pitroom savings` adds them up (a bigger measurement follows in [Benchmarks](#benchmarks)):
 
 <p align="center"><img src="docs/card.svg" width="520" alt="Pitroom savings card"></p>
 
 ---
 
-## Quick start
-
-<table>
-<tr>
-
-<td width="25%" valign="top">
-
-### 01
+## Benchmarks
 
-**Install**
+Measured on a real, public repository: [PI-Desktop](https://github.com/vastsa/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.
 
-Plugin or npm (below)
+| Question | Worker time | Tokens processed | Returned to the agent | Compression | Refs verified |
+|---|---|---|---|---|---|
+| Where is the plugin runtime, and which functions activate and deactivate a plugin? | 37 s | 405,380 | 767 | 529× | 10/11 |
+| When does the agent runtime compact a conversation? (function and exact condition) | 90 s | 1,250,719 | 763 | 1,639× | 17/17 |
+| Where is session state persisted to disk in the Rust host? | 71 s | 854,969 | 1,426 | 600× | 29/45 ¹ |
+| Which IPC channels expose window management to the renderer? | 32 s | 165,180 | 716 | 231× | 3/28 ¹ |
+| How does a tool call travel from the agent runtime to the Rust host? | 119 s | 1,818,524 | 866 | 2,100× | 14/15 |
+| Which packages and apps depend on the i18n package? | 33 s | 271,297 | 656 | 414× | 15/16 |
+| Where is auto-update implemented, and what does the Windows portable target change? | 29 s | 215,693 | 743 | 290× | 20/21 |
+| Which tests cover the RPC layer? | 59 s | 511,209 | 1,747 | 293× | 6/7 |
+| **All eight** | **156 s** wall clock | **5,492,971** | **7,684** | **715×** | 114/160 |
 
-</td>
-
-<td width="25%" valign="top">
+Workers read 5.5 million tokens of code and docs (96 steps, 179 tool calls) and handed the agent 7,684 tokens, about 960 per answer. The eight runs add up to 470 s of worker time but finished in 156 s of wall clock, because four ran at a time (the limit then; the default is now 20): about 3× faster than one after another. That compares the same workers with themselves, not with your agent doing the reading alone, which I did not measure. `pitroom savings` estimates $3.86 saved for these eight at Claude Sonnet list prices.
 
-### 02
+**Were the answers right?** Checked by hand against the repository: 46 key claims across all eight answers (the cited line and what it says) were all correct, and two completeness checks held (exactly 6 invoke and 3 event window channels; no tests in `config_sync_rpc.rs`). The i18n answer lists the 12 source files that import the package and leaves out 11 test and fixture files that do too, which the question did not ask about. Pitroom's own checker marks fewer references as verified than that: ¹ those two answers cite bare file names (`transcripts.rs:651`) that it cannot resolve to a path, and it counts them as unverified although the lines are right.
 
-**Connect a worker**
+**A change in an isolated copy:** "add a one-line comment above `resolveUpdateMode`" finished in 16 s and 4 steps (142,491 tokens). The patch was one file and one line, the comment matched the code, and your working tree is untouched until you apply.
 
-OpenCode, Codex or Claude Code
+**What this does not show**
+- One repository, one free model, one run per question: there is no variance here, and another model or repository will differ.
+- 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.
 
-</td>
+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`.
 
-<td width="25%" valign="top">
+---
 
-### 03
+## Quick start
 
-**Check it**
+You need Node.js 18+ and at least one worker CLI: [OpenCode](https://opencode.ai) v2+ (the default worker, with free models), [Codex CLI](https://github.com/openai/codex) or [Claude Code](https://claude.com/claude-code).
 
-`pitroom doctor --probe`
+### 1. Install: pick your agent
 
-</td>
+**Claude Code**
 
-<td width="25%" valign="top">
+```bash
+claude plugin marketplace add ATASTECH/pitroom
+claude plugin install pitroom@pitroom
+```
 
-### 04
+<sub>Inside a session: `/plugin marketplace add ATASTECH/pitroom`, then `/plugin install pitroom@pitroom`.</sub>
 
-**Use it**
+**Codex**
 
-Ask your agent, or run `pitroom`
+```bash
+codex plugin marketplace add ATASTECH/pitroom
+codex plugin add pitroom@pitroom
+npm i -g pitroom
+```
 
-</td>
+**Any other agent (Cursor, Gemini CLI, a plain shell) or just the CLI**
 
-</tr>
-</table>
+```bash
+npm i -g pitroom
+pitroom install
+```
 
-Requires Node.js 18+ and at least one worker CLI: [OpenCode](https://opencode.ai) v2+ (the default worker), [Codex CLI](https://github.com/openai/codex) or [Claude Code](https://claude.com/claude-code).
+| Path | You get |
+|---|---|
+| Claude Code plugin | The 14 skills, the session-start hook that introduces Pitroom, and a card after each `pitroom` command. |
+| Codex plugin | The 14 skills. Codex has no session-start hook, so Pitroom is not introduced on its own: the skills load when a task matches, or name one. `pitroom` itself comes from npm. |
+| npm + `pitroom install` | The CLI, and the skills linked into `~/.agents/skills` and `~/.claude/skills`. |
 
-### Choose how to 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).
 
-| You use | Install | What you get |
-|---|---|---|
-| **Claude Code** | `claude plugin marketplace add ATASTECH/pitroom`<br>`claude plugin install pitroom@pitroom`<br>(inside a session: `/plugin marketplace add ATASTECH/pitroom`, `/plugin install pitroom@pitroom`) | The 14 skills, the session-start hook that introduces Pitroom, and a card after each `pitroom` command. The plugin is the published npm package: under 0.5 MB, no dependencies. |
-| **Codex** | `codex plugin marketplace add ATASTECH/pitroom`<br>`codex plugin add pitroom@pitroom`<br>and `npm i -g pitroom` | The 14 skills. Codex plugins have no session-start hook, so Pitroom is not introduced on its own: the skills load when a task matches, or ask for one by name. The `pitroom` command itself comes from npm. |
-| **Any other agent, or only the CLI** | `npm i -g pitroom`<br>`pitroom install` | The CLI, and the skills linked into `~/.agents/skills` and `~/.claude/skills`. |
+### 2. Check the setup
 
 ```bash
-pitroom doctor --probe   # worker CLI, models, permissions, skills, one live round trip
+pitroom doctor --probe
 ```
 
-Pick one path: `doctor` warns if the skills load twice. To run `pitroom` yourself in a terminal (`watch`, `savings`, the status line below), install it from npm as well; the plugins alone do not put it on your PATH.
+It checks the worker CLIs, models, permissions and skills, and runs one live round trip.
 
-### Your first run
+### 3. Use it
 
 Pitroom is a toolbox, not a procedure: your agent uses it when it helps, or you ask explicitly:
 
@@ -213,8 +230,26 @@ Or start a worker yourself and read its receipt:
 ```bash
 pitroom "Which files read the session cookie? Cite file:line."
 pitroom savings          # what all your runs saved so far
+pitroom models           # what each worker offers, what it costs you, what it used
 ```
 
+<details>
+<summary>Update and uninstall</summary>
+
+```bash
+# 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
+```
+
+</details>
+
 ---
 
 ## Modes
@@ -240,17 +275,18 @@ Long jobs: `--bg` returns immediately; `pitroom wait <id>` blocks for up to 9 mi
 
 Pitroom ships a full development methodology as skills, adapted from [superpowers](https://github.com/obra/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.
 
-```text
-pitroom-brainstorming ──► spec (docs/pitroom/specs/)
-pitroom-writing-plans ──► plan (docs/pitroom/plans/), every task tagged with a worker tier
-pitroom-driven-development, per task:
-  pitroom run -i --plan PLAN --step N    implementer worker, isolated copy, TDD evidence, STATUS line
-  pitroom review <run>                   read-only reviewer on another backend: SPEC and QUALITY verdicts
-  pitroom run --continue <run> "…"       fix rounds; the re-review sees only the fix diff
-  pitroom apply <run> · tests · commit   the primary lands it; workers never commit
-pitroom review --range main..HEAD --plan PLAN   whole-branch review on the capable tier
-pitroom-finishing ──► merge, PR or keep (asked, never automatic)
-```
+<p align="center"><img src="docs/workflow.svg" width="100%" alt="Workflow: brainstorming, then a plan with a worker tier per task, then for every task a worker implements in an isolated copy, another model reviews, fix rounds repeat until approved, and your agent applies, tests and commits; then a whole-branch review and finishing."></p>
+
+| Step | Skill | Command |
+|---|---|---|
+| Design | `pitroom-brainstorming` | writes the spec to `docs/pitroom/specs/` |
+| Plan | `pitroom-writing-plans` | writes the plan to `docs/pitroom/plans/`, a worker tier on every task |
+| Implement | `pitroom-driven-development` | `pitroom run -i --plan PLAN --step N` |
+| Review | `pitroom-review` | `pitroom review <run>` (a read-only reviewer on another model) |
+| Fix | `pitroom-receiving-review` | `pitroom run --continue <run> "…"` (the re-review sees only the fix) |
+| Land | `pitroom-driven-development` | `pitroom apply <run>`, your tests, your commit |
+| Branch review | `pitroom-review` | `pitroom review --range main..HEAD --plan PLAN` |
+| Finish | `pitroom-finishing` | merge, pull request or keep: asked, never automatic |
 
 A review package holds the diff under review with 10 lines of context, and the reviewer's CLI sends it to that worker's model provider. Pitroom does not filter it: secrets committed in a reviewed range go along as they are.
 
@@ -271,6 +307,9 @@ pitroom crew -g v04-demo \
 pitroom watch -g v04-demo --json   # what the primary agent follows, one line per change:
 ```
 
+<details>
+<summary>What the crew prints: the stream your agent follows and the status table</summary>
+
 ```text
 {"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"}
@@ -287,9 +326,11 @@ RUN                   STATE  MODE  TIME  STEPS  WORKER                    NOW /
 20260930-102812-a65d  done   read  39s   7      opencode (default model)  maxParallel is enforced by file-based slots (`s…
 ```
 
+</details>
+
 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. At most `maxParallel` workers (default 4) run at once, the rest queue; only one `--write` run per repository is allowed. `pitroom stop -g NAME` stops running and queued workers.
+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.
 
 ---
 
@@ -316,6 +357,9 @@ For changes, `pitroom crew -i …` gives every worker its own isolated copy of y
 
 ## Commands
 
+<details>
+<summary>All commands and exit codes</summary>
+
 ```text
 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"
@@ -327,13 +371,16 @@ pitroom status|wait|watch [run… | -g NAME]        wait: --any --brief --timeou
 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] [--card file.svg] [--badge]
+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 install [--copy] [--force] · pitroom uninstall
 ```
 
 Exit codes: `0` ok · `1` worker failed · `2` usage · `3` refused/setup · `4` timeout · `5` read-only violation · `6` verify failed · `75` still running.
 
+</details>
+
 ### Seeing Pitroom at work in Claude Code
 
 Two settings make every delegation visible, whether or not the agent mentions it. A status line shows running workers and this week's savings (`--then` keeps your own status line first); a card appears after each `pitroom` command the agent runs, once per phase (started, finished with its result, applied). The plugin registers the card hook itself; with `pitroom install`, add both to `~/.claude/settings.json`:
@@ -353,19 +400,14 @@ Two settings make every delegation visible, whether or not the agent mentions it
 
 ![Pitroom workflow: primary agent → Pitroom CLI → OpenCode, Codex or Claude Code workers → verified answer, exact diff and receipt returned to the primary agent.](docs/pitroom-flow.png)
 
-```text
-primary agent ──(skill: "delegate?")──► pitroom run "task"
-                                          │ snapshot tree (throwaway index)      [write]
-                                          │ isolated copy of current state       [isolate]
-                                          │ worker adapter: mode → the CLI's own permissions
-                                          ▼
-    worker CLI, e.g. opencode run --standalone --format json   (stdin closed, git guard, your default model)
-                                          │ NDJSON events
-                                          ▼
-                     final answer · exact diff · receipt ──► primary agent verifies / applies
-```
+<p align="center"><img src="docs/architecture.svg" width="100%" alt="How a run flows: the primary agent delegates to the Pitroom CLI, which starts a worker CLI in read, isolate or write mode; events, then the answer, an exact diff and a receipt come back."></p>
 
-Known headless footguns handled for every worker: `opencode run` blocks forever on an open stdin pipe; `ask` permissions stall headless runs; default output carries ANSI and banners; and in OpenCode v2 a plain `run` attaches to the shared background service, where per-run permissions and the git guard would not apply. Pitroom closes stdin, uses allow/deny-only profiles, parses `--format json` and always runs a private `--standalone` server.
+<details>
+<summary>Headless problems Pitroom handles for every worker</summary>
+
+Handled for every worker: `opencode run` blocks forever on an open stdin pipe; `ask` permissions stall headless runs; default output carries ANSI and banners; and in OpenCode v2 a plain `run` attaches to the shared background service, where per-run permissions and the git guard would not apply. Pitroom closes stdin, uses allow/deny-only profiles, parses `--format json` and always runs a private `--standalone` server.
+
+</details>
 
 ---
 
@@ -376,7 +418,8 @@ A worker is named by a target: `backend[:model]`.
 ```bash
 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' "…"                          # Codex's default model, low reasoning effort
+pitroom run -W 'codex:#low' "…"                          # the model from config "models" (not Codex's default), low reasoning effort
+pitroom run --effort high "…"                           # any worker: model#level (Codex, Claude Code, OpenCode)
 pitroom run -W claude:haiku "…"                          # Claude Code on a cheap model
 pitroom run -m nvidia/z-ai/glm-5.3 "…"                   # another model on the preferred worker
 ```
@@ -388,24 +431,42 @@ pitroom run -m nvidia/z-ai/glm-5.3 "…"                   # another model on th
 | Claude Code | ✅ | tool allowlist (`--restricted --safe-mode`, `dontAsk`) | reported | `claude auth login`; its default is often Opus, so prefer `-W claude:haiku` |
 | Gemini CLI | soon | approval mode + policy engine | | |
 
+### Models, costs and effort
+
+`pitroom models` lists what each worker offers (Codex from its own model cache, Claude Code's aliases, OpenCode's `opencode models`), the reasoning-effort levels each model accepts, what you say it costs and what your own runs used:
+
+```text
+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          ?     -     -           -       -
+```
+
+Pitroom cannot know vendor prices and does not fetch them, so a cost is what you enter: `"costs": {"codex:gpt-6-sol": 1, "codex:gpt-6.1-sol": 2}` in the config, in any unit (they are only compared). `pitroom doctor` then prints the cost of the models in use and says when you priced a cheaper one of the same worker. A target that names only an effort (`codex:#low`) uses the model from `models`; a Codex or Claude Code worker with no pinned model gets a warning, because it would run the vendor's own default, which can change and cost more. `--effort LEVEL` sets the level for one run; your agent picks model and level from `pitroom models` (cheapest that fits: `low` for lookups, `medium` for ordinary changes, `high` for reviews).
+
 Fallbacks cross backends (e.g. `"fallback": ["codex:#low", "opencode"]`): a worker that is rate-limited, logged out or missing its model hands the task to the next. Follow-ups (`--continue`) always stay on the worker that owns the session. Writing an adapter: [docs/backends.md](docs/backends.md).
 
 ---
 
 ## Configuration
 
+<details>
+<summary>Environment variables</summary>
+
 | Env | Default | |
 |---|---|---|
 | `PITROOM_WORKER` | `opencode` | Preferred worker target: `backend[:model]` |
 | `PITROOM_MODEL` | the worker's default | Model for the preferred worker |
 | `PITROOM_FALLBACK` | none | Comma-separated targets to fail over to on model/provider errors |
 | `PITROOM_TIMEOUT` | `30m` | Per-run timeout |
-| `PITROOM_MAX_PARALLEL` | `4` | Workers running at once; more queue |
+| `PITROOM_MAX_PARALLEL` | `20` | Workers running at once (at most 30); more queue |
 | `PITROOM_PRIMARY` | `sonnet` | Pricing preset for the savings estimate: `sonnet`, `opus`, `haiku`, `gpt-5` |
 | `PITROOM_PRICE` | | Custom primary price, USD per 1M tokens: `"in,out[,cachedIn]"` |
 | `PITROOM_HOME` | `~/.local/state/pitroom` | Where run records and the ledger live |
 | `PITROOM_<WORKER>_BIN` | on PATH | Path to a worker CLI, e.g. `PITROOM_OPENCODE_BIN` |
 
+</details>
+
 Or put defaults in `~/.config/pitroom/config.json` (flags and env still win); `pitroom config` shows every effective value and where it came from. `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:
 
 ```json
@@ -413,19 +474,25 @@ Or put defaults in `~/.config/pitroom/config.json` (flags and env still win); `p
   "worker": "opencode",
   "fallback": ["opencode:opencode/space-bunny-free", "codex"],
   "models": { "codex": "gpt-6.1-sol", "claude": "claude-sonnet-5-5" },
-  "tiers": { "cheap": "opencode", "standard": "codex", "capable": "claude" },
+  "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": 3
+  "maxParallel": 20
 }
 ```
 
+- `worker` and `fallback`: who runs a task when you name no one, and who takes over when it fails; `models`: the model each worker uses when a target names none.
+- `tiers`: `cheap`, `standard` and `capable` name the workers for plan tasks and `--tier`; an optional `review` tier names who reviews a run (by default another worker than the implementer's, `standard` first).
+- `costs`: your relative cost per `worker:model`, only compared with each other; `maxParallel`: workers at once (default 20, at most 30).
+
+
 ---
 
 ## FAQ
 
-**Where does my code go?** To whichever provider your worker's model uses. For private code, point the worker at a local model. `.env` files and private keys are blocked from the worker either way.
+**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.
 
@@ -435,9 +502,17 @@ Or put defaults in `~/.config/pitroom/config.json` (flags and env still win); `p
 
 ---
 
+## Responsibility
+
+Pitroom is provided as is, under the [MIT License](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](PRIVACY.md).
+
+---
+
 ## Contributing
 
-Issues and pull requests are welcome. Worker adapters are the easiest place to start: [docs/backends.md](docs/backends.md).
+Issues and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md): setup, tests, the dist bundle and the commit style. Worker adapters are the easiest place to begin: [docs/backends.md](docs/backends.md).
 
 ```bash
 npm install
@@ -445,14 +520,18 @@ npm test          # end-to-end tests against a fake worker CLI + adapter contrac
 npm run typecheck
 ```
 
+**Security:** please report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md), not in a public issue.
+
 **[Report an issue](https://github.com/ATASTECH/pitroom/issues/new)** ·
-[Open issues](https://github.com/ATASTECH/pitroom/issues)
+[Open issues](https://github.com/ATASTECH/pitroom/issues) ·
+[Security policy](SECURITY.md) ·
+[Code of conduct](CODE_OF_CONDUCT.md)
 
 ---
 
 ## Credits
 
-The workflow skills (brainstorming, planning, worker-driven development, review, debugging, TDD, verification, worktrees, finishing) are adapted from [superpowers](https://github.com/obra/superpowers)
+The workflow skills (brainstorming, planning, worker-driven development, review, debugging, TDD, verification, worktrees, finishing) are adapted from [superpowers](https://github.com/obra/superpowers) by Jesse Vincent, under the MIT License; the notice is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
 ## License
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+Pitroom itself is licensed under the [MIT License](LICENSE). The workflow skills in `skills/` (brainstorming, planning, worker-driven development, review, debugging, TDD, verification, worktrees and finishing) are adapted from the skills of **superpowers** by Jesse Vincent, <https://github.com/obra/superpowers>, used under the MIT License reproduced below. They were rewritten so that their subagents are Pitroom workers.
+
+## superpowers
+
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Not bundled
+
+Pitroom starts worker CLIs you install yourself (OpenCode, Codex CLI, Claude Code). They are not part of this package and keep their own licenses and terms.