pitroom 0.14.1 → 0.16.0

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.14.1",
+  "version": "0.16.0",
   "author": {
     "name": "TahaAtas"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pitroom",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "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,25 @@
 # Changelog
 
+## 0.16.0
+
+### MCP server
+- **Progress notifications.** A call that waits for a run reports how it is doing every few seconds (`notifications/progress`, when the client sent a progress token), so the agent sees what the worker is doing; a client that resets its timeout when progress comes in (the protocol allows it, not every client does) does not give up on a long run.
+- **Cancellation.** A client that cancels `pitroom_run`, `pitroom_crew`, `pitroom_review` or `pitroom_audit` (`notifications/cancelled`) stops the run or group it started and gets no answer, as the protocol says; a cancelled `pitroom_wait` only stops waiting. A client that sends its requests and closes the pipe still gets the answers.
+- **Resources.** The latest runs are resources, `pitroom://run/<id>` (the report) and `pitroom://run/<id>/patch` (the exact diff), with resource templates; anything else is "not found" (-32002).
+- **Prompts.** `research`, `implement`, `review` and `crew`, with their arguments checked.
+- **Nine new tools** (18 in all): `pitroom_crew` (independent tasks in parallel as one group), `pitroom_list`, `pitroom_history` (search earlier answers), `pitroom_stats`, `pitroom_savings`, `pitroom_models`, `pitroom_cooldown`, `pitroom_doctor` and `pitroom_revert` (undo a write run); `pitroom_run` takes `continue` for a follow-up in the same worker session, and `pitroom_apply` can apply a group.
+- **HTTP transport.** `pitroom mcp --http [--port N]` serves the same server over Streamable HTTP at `http://127.0.0.1:7117/mcp`, for clients that connect to a URL. Local by construction: 127.0.0.1 only, a bearer token (generated on first start into `<state dir>/mcp-token`, mode 0600, or `PITROOM_MCP_TOKEN`; compared in constant time), and a Host or Origin that is not local is refused with 403 (DNS rebinding). Sessions per client (`Mcp-Session-Id`), so a cancel only touches the cancelling client's request even when two clients use the same request id; a call that sends a progress token is answered as an event stream. Ending a session (DELETE) or stopping the server ends the waiting, not the runs. When 64 sessions are open, the one unused longest makes room for a new one. Checked with the real Claude Code client (`claude mcp add --transport http …`, `claude mcp list`: connected).
+- `pitroom mcp -d DIR` (stdio or HTTP) works in that project, for clients such as Claude Desktop that start the server somewhere else; `--port` without `--http` is a usage error.
+- The server is split into protocol (`mcp.ts`), tools (`mcp-tools.ts`), resources and prompts (`mcp-extras.ts`) and what they share (`mcp-support.ts`).
+
+## 0.15.0
+
+### `pitroom install --mcp`
+- Registers `pitroom mcp` in the MCP clients found on the machine, so setting it up is one command: Claude Code, Codex and Gemini CLI are changed with their own `mcp add` command (user scope where they have one), Cursor and Claude Desktop have their JSON config merged (other servers and settings kept, a `.bak-pitroom` backup the first time, a file that is not valid JSON left alone). `--dry-run` only says what it would do, `--client cursor,claude-desktop` limits it, `--no-skills` skips linking the skills, and `pitroom uninstall` removes the registrations again (a client whose command is gone cannot be asked to, which is reported and exits 1).
+- The command registered is the launcher by its full path (apps such as Claude Desktop start without your `PATH`), and only when that file really is a Pitroom launcher. Whether a client already has the server is read from its config file, never by starting the server; a client that runs a different command (a Codex entry included) is updated, and `--force` registers again.
+- `pitroom doctor` has an MCP section: where `pitroom mcp` is registered, and a warning for a client that runs another command.
+- Checked with the real `claude`, `codex` and `gemini` commands in a throwaway home: right entries written, a second run "already registered", `uninstall` removed exactly those. The change was reviewed by a free Pitroom worker before merging; its findings (a foreign file at the launcher path, unguarded writes, the Codex command not compared, uninstall failures, a few messages) are fixed.
+
 ## 0.14.1
 
 ### Docs

package/README.md

@@ -273,7 +273,15 @@ npm i -g pitroom
 
 **Any agent that speaks MCP (Cursor, Claude Desktop, and the three above too)**
 
-Pitroom is also an [MCP](https://modelcontextprotocol.io) server on stdio: nine tools (`pitroom_run`, `pitroom_wait`, `pitroom_status`, `pitroom_show`, `pitroom_review`, `pitroom_audit`, `pitroom_apply`, `pitroom_discard`, `pitroom_stop`) instead of shell commands and skills. After `npm i -g pitroom`:
+Pitroom is also an [MCP](https://modelcontextprotocol.io) server on stdio: tools instead of shell commands and skills (`pitroom_run`, `pitroom_crew`, `pitroom_wait`, `pitroom_review`, `pitroom_audit`, `pitroom_apply`, `pitroom_revert`, … 18 in all, covering the commands an agent needs), the runs as resources, and four prompts. After `npm i -g pitroom`, let Pitroom register itself in the clients it finds (Claude Code, Codex, Gemini CLI, Cursor, Claude Desktop):
+
+```bash
+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:
 
 ```bash
 claude mcp add pitroom -- pitroom mcp
@@ -287,7 +295,13 @@ or, for Cursor (`~/.cursor/mcp.json`), Claude Desktop (`claude_desktop_config.js
 { "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 the client starts it in.
+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.
+
+- **Progress.** While a call waits for a run, a client that sent a progress token gets a `notifications/progress` every few seconds ("running · read · 12s · 3 steps, 2 tool calls · last: …"), and a client that resets its timeout when progress comes in (the protocol allows it; not every client does) does not give up on a long run. **Cancelling** a `pitroom_run`, `pitroom_crew`, `pitroom_review` or `pitroom_audit` call stops the run it started (a cancelled `pitroom_wait` only stops waiting).
+- **Resources.** The latest runs are listed as `pitroom://run/<id>` (the report) and, for runs that changed files, `pitroom://run/<id>/patch` (the exact diff), so a client can attach one to a conversation.
+- **Prompts.** `research`, `implement`, `review` and `crew` say how to use Pitroom for that job (in Claude Code they appear as `/mcp__pitroom__research`, …).
+- **Also as tools:** `pitroom_crew` (independent tasks in parallel), `pitroom_list`, `pitroom_history` (find an earlier answer), `pitroom_stats` and `pitroom_models` (pick a worker), `pitroom_savings`, `pitroom_cooldown`, `pitroom_doctor`, `pitroom_revert`, and a `continue` option on `pitroom_run` for a follow-up.
+- **Over HTTP.** `pitroom mcp --http [--port N]` (default 7117) serves the same tools at `http://127.0.0.1:7117/mcp` for clients that connect to a URL, for example `claude mcp add --transport http pitroom http://127.0.0.1:7117/mcp --header "Authorization: Bearer $(cat ~/.local/state/pitroom/mcp-token)"` (the command is printed when it starts). It is a local service: it listens on 127.0.0.1 only, needs the bearer token (made on first start, kept at `<state dir>/mcp-token` with owner-only permissions, or set with `PITROOM_MCP_TOKEN`), and refuses a Host or Origin that is not local, so a web page cannot use it. Anyone who has the token can run workers as you, so keep it private. It works in the directory it was started in (printed when it starts; `-d DIR` for another). Each client has its own session; a call that asks for progress is answered as an event stream. Ending a session or stopping the server ends the waiting, not the runs: collect them with `pitroom_wait` or the CLI. `pitroom install --mcp` registers the stdio command, which needs no token and no running process.
 
 **Any other agent (a plain shell) or just the CLI**
 
@@ -482,7 +496,7 @@ pitroom crew [-i] [-g NAME] "task 1" "task 2" …   (or --task-file with --- sep
 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 mcp                  # serve Pitroom as MCP tools on stdio
+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
@@ -495,7 +509,7 @@ 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] · pitroom uninstall
+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
 ```
 
 Exit codes: `0` ok · `1` worker failed · `2` usage · `3` refused/setup · `4` timeout · `5` read-only violation · `6` verify failed · `75` still running.