English | 简体中文

pi-coffee

An MCP server for running several pi coding agents on one repository without them stepping on each other. Every worker gets its own git worktree and branch; the daemon keeps the file claims, the mailbox, the shared board and an evidence trail. You stay the reviewer: nothing merges until the exact candidate has passed a fixed acceptance command and every declared requirement has a verdict.

Any MCP client can drive it — Codex and DeepSeek Harness are the reference clients. Small fixes stay direct.

Why bother

One agent in a repository is easy to supervise. Several are not: they overwrite each other's files, or they leave behind long-lived branches that are painful to merge. Copying the repo wastes the parallelism; running things strictly one after another wastes your time.

pi-coffee gives every worker a private worktree and branch, makes file ownership explicit, and keeps one supervisor responsible for the final result. When a worker finishes, you get a diff, a report, a passing acceptance run against the exact candidate, and a merge gate that refuses anything else.

Workers are worth it for clearly scoped, independent, objectively verifiable work. They are not worth it for a one-line repair or a tightly coupled change — do that yourself.

Related MCP server: agentbus

Requirements

Run the daemon, the client and the workers as the same user: they share file ownership. Root is not required — any user with a working pi and write access to the repository is fine. Provider credentials come from the generated env file or from pi's own ~/.pi/agent/auth.json.

Quick start

No checkout needed — the one-line installer fetches the newest release into ~/.pi-coffee/app and runs the same installer:

curl -fsSL https://raw.githubusercontent.com/lucasjingcn/pi-coffee/main/scripts/bootstrap.sh | bash

Or from a checkout:

git clone https://github.com/lucasjingcn/pi-coffee.git
cd pi-coffee
npm run install:local      # build, install the skill + pi CLI, register clients, start the daemon

It checks Node and git first, installs the pinned pi CLI and the pi-orchestrator skill, registers the MCP server pi with every client it finds, asks for provider, API key and model (~/.pi-coffee/env), and starts a per-user background daemon. No client is required up front: a missing Codex is skipped and the summary prints the exact command for the client you do have. For a scripted install, forward the setup options:

npm run install:local -- --provider deepseek --model deepseek-flash --api-key sk-...

A missing credential is a warning, not a failed install: run npm run setup, then the restart command the summary printed. Then check the daemon and prove the whole loop without spending tokens:

node scripts/check-health.mjs   # the daemon is up
npm run demo                    # offline end-to-end check, a few seconds

Restart your MCP client afterwards; the pi_* tools and the orchestration policy load then. Clients the installer cannot write (DSH, Claude Code, Cursor) are connected with node scripts/register-clients.mjs, which prints the exact command or snippet.

A first worker

With the pi_* tools visible, hand the client one small task and let the loop run once:

In this repository spawn one pi worker:
  spec: { goal: "make the acceptance command pass for src/app.ts", scope: ["src/app.ts"],
          task_type: "mechanical", purpose: "implementation" }
  acceptance_command: "node --test tests/app.test.mjs"
Then show me pi_diff, run pi_verify, record pi_review for the requirement, pi_merge, and
pi_finish with outcome success_first.

One task, end to end

1. Spawn. Call pi_spawn with a spec (goal, scope, purpose), a fixed acceptance_command, and acceptance_files for any independent tests. The scope is claimed before the worker starts, so an overlapping workstream is rejected immediately.

2. Work. The worker edits inside its scope in a private worktree. Questions come back through coord_ask; conflicting claims are explained instead of silently overwritten.

3. Review. When the worker settles, read the full pi_diff and commit the reviewed changes.

4. Verify. pi_verify rebuilds an isolated candidate from the exact worker and target commits and runs the acceptance command. Exit code, timeout, output, SHAs and tree evidence are recorded.

5. Approve requirements. pi_review records one verdict per hard requirement and one reason per changed existing test file, bound to that verification.

6. Merge. pi_merge refuses a changed commit, a failed or timed-out run, a dirty checkout, a scope violation, or a missing review. pi_pr and the GitHub merge queue are available when pushing is explicitly allowed.

7. Close. pi_finish records the outcome; pi_report and pi_metrics show what landed first try; pi_gc reclaims what is no longer needed.

Tools

The full reference — arguments, gates, edge cases — is in docs/reference/tools.md.

Daemon-spawned pi sessions additionally get the worker-side tools coord_ask, coord_send, coord_inbox, coord_claim, coord_release, coord_board_post, coord_board_read and coord_status.

File claims

Before a worker writes, it claims the path. edit and write claim their target file; bash claims the literal redirect, tee and sed -i targets it recognizes. If another worker holds a conflicting claim, the call is blocked and the worker is told who holds it. Claims are namespaced per repository, so two checkouts of the same repo share them and unrelated repos never collide.

Claims are coordination protection, not a sandbox: dynamic paths, variables and globs are not fully contained, and a worker can still run arbitrary code inside its worktree. For untrusted code, use the Docker sandbox — see docs/reference/coordination.md.

Configuration

Everything is set through PI_COFFEE_* environment variables, read from the private env file (~/.pi-coffee/env) or the process environment. The ones people change most:

All 50+ variables, their validation rules and the env-file precedence are in docs/reference/configuration.md.

Client timeouts

pi_verify and pi_exec may run for up to 10 minutes. Most MCP clients cap a tool call at 60 seconds, so raise the limit once per client:

[mcp_servers.pi]
# ...command/args...
tool_timeout_sec = 600

// ~/.pi/agent/mcp.json
{ "mcpServers": { "pi": { "timeout": 600 } } }

A client timeout cancels nothing: the worker keeps working and the evidence stays valid. Read the real state with pi_status / pi_list instead of treating it as a failure.

Docker

The image bundles Node, git and pi, so the only host requirement is Docker.

cp .env.example .env       # provider key and model
mkdir -p workspace         # the repository workers should edit
docker compose up -d --build
curl http://127.0.0.1:8787/internal/health

./workspace is mounted at /workspace and is the default repo; a named volume holds /data. Point your client at http://127.0.0.1:8787/mcp. Details and the no-Compose invocation are in docs/reference/operations.md.

Docs

Development

npm ci
npm run build
npm test        # build + offline suite, no credentials or network
npm run verify  # typecheck, extension typecheck, offline suite, docs contract

The offline suite drives the whole control surface against a fake pi that speaks JSONL. See docs/development.md for the architecture and release process.

Security and limits

• The daemon binds to loopback with no authentication. Set PI_COFFEE_TOKEN before exposing it, and only on a trusted network.

• Claims and digest checks block mistakes and invalid integration; they are not an OS sandbox.

• A graceful daemon stop stops workers. A crash is recovered on the next start for sessions that were active at the time; explicitly stopped sessions are not resumed, and Windows has no automatic orphan-process recovery.

• The worktree model assumes one worker per branch. The same branch in two worktrees is unsupported.

License

Apache License 2.0. See LICENSE.

Copyright 2026 lucasjing.

pi (@earendil-works/pi-coding-agent) is a separate MIT-licensed program by Mario Zechner. This repository invokes it as an external tool rather than redistributing its code; the Docker image installs it from npm at build time. pi is not affiliated with, and does not endorse, this project.