⚡ perch-agent

Delegate tasks from Claude Code / opencode to Perch AI as an autonomous worker agent.

One MCP server. Your orchestrator keeps the plan — Perch does the work, verifies it, and comes back with evidence.

Architecture · Quick Start · Tools · Benchmarks · Troubleshooting

🏗 Architecture

Claude Code (or opencode) stays the orchestrator. This server translates one MCP tool call into the official perch CLI (perch run "<task>" --json) — no unofficial internal APIs, no session-token proxying — and returns a structured result: final answer, thread id, model identity and token usage.

Related MCP server: outsrc

✨ Features

• 🔁 Async job model — long tasks return a job_id in seconds; poll perch_job_status or cancel with perch_job_cancel (kills the whole process tree).

• 🧭 Karpathy guidelines baked in — every delegated task is prepended with working discipline: surface assumptions, minimal change, surgical scope, verification with real command output. (guidelines: false to disable.)

• 📊 Live progress — notifications/progress every 5s while a task runs; renders in Claude Code.

• 🧵 Thread continuation — pass a previous thread_id and the worker remembers the conversation.

• 🎯 Model pinning — tier (standard/pro) or pin id (qwen-3.8-max, glm-5.3-flash-starter, …).

• 🧾 Evidence-first output — assistant_text, model_id, usage, thread_id, exit codes, and human-readable plan-gate errors instead of raw stack traces.

• 🔒 Local-first — everything runs on your machine; the only network hop is the official CLI → Perch's own API, using your existing login. No keys to manage.

• 🧪 Battle-tested — unit + E2E suite, plus a real benchmark harness (Exercism polyglot, agentic coding, differential reasoning) included in bench/.

🚀 Quick Start (3 Steps)

Step 1 — Prerequisites

• Node.js 20+

• Perch CLI installed and logged in (the MCP reuses this session — no API key):

npm i -g perchai-cli
perch login          # browser sign-in (Google/GitHub)
perch status         # must show "Signed in as …"

Step 2 — Get this repo

git clone https://github.com/DMCconnect/perch-agent-mcp.git
cd perch-agent-mcp
npm install
npm test             # parser self-check

Step 3 — Register with your harness

Claude Code (user scope):

claude mcp add --scope user perch-agent \
  -e PERCH_AGENT_MODEL=qwen-3.8-max \
  -e PERCH_AGENT_EFFORT=high \
  -- node "C:/path/to/perch-agent-mcp/index.js"

claude mcp list      # → perch-agent: ✓ connected

For long delegations also set MCP_TOOL_TIMEOUT=900000 in your environment (Claude Code's default MCP call timeout is short).

opencode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "perch-agent": {
      "type": "local",
      "command": ["node", "C:/path/to/perch-agent-mcp/index.js"],
      "enabled": true,
      "timeout": 1200000
    }
  }
}

Any other MCP client — it's a plain stdio server:

command: node <path>/index.js

Done. In your harness, say: "Use perch-agent to fix the failing tests in ./app".

🛠️ Tools

Result shape (success):

{
  "job_id": "pj-95c583b8",
  "status": "finished",
  "perch_status": "completed",
  "ok": true,
  "thread_id": "cli-cwd-a713c141ff2d4ddb",
  "assistant_text": "…final worker answer…",
  "model_id": "Qwen/Qwen3.8-Max",
  "usage": { "input_tokens": 15761, "output_tokens": 30, "total_tokens": 24495 }
}

🎛️ Environment

🔥 The free Qwen 3.8 Max pin

Qwen 3.8 Max is free on the Perch Starter plan until Nov 20, 2026 (announcement). To make it the default worker:

PERCH_AGENT_MODEL=qwen-3.8-max   PERCH_AGENT_EFFORT=high

After the promo expires, the CLI rejects the pin with a clear plan error — switch back to standard (or any current Starter pin) with one env change.

🧠 The karpathy preamble

Every delegate_to_perch task ships with this discipline header (the whole point of a worker — it must not wander, and it must prove it finished):

1. Think before coding — state your assumptions explicitly…
2. Simplicity first — the minimum change that solves the problem…
3. Surgical changes — touch only what the task requires…
4. Goal-driven verification — run the tests/builds, quote the real command
   and its output as evidence. Never claim verification without evidence.

Disable per-call with guidelines: false.

📈 Benchmarks

Real runs by this repo's harness against the live Perch service (Starter plan), graded objectively — pytest/exit-codes/answer-checking, never the model's self-report:

Is the pinned model real? Perch's own accounting reports Qwen/Qwen3.8-Max per turn and the timing fingerprint differs from standard per task type — while short-form reasoning scores are tied. Harness: bench/ · methodology borrowed from aider's polyglot benchmark (Exercism + pytest, self-correction loop).

🧪 Testing

npm test              # parser hardening self-check
npm run e2e           # full MCP E2E: happy path, threads, error surfacing, async+cancel
npm run bench:polyglot  # Exercism exercises, pytest-graded (needs: python + pytest)

The E2E covers: inline completion, thread continuation, plan-gate error surfacing, async job_id handoff, and mid-run cancellation.

🔧 Troubleshooting

🤖 For agents (machine-readable)

• llms.txt — condensed install + tool contract for LLM agents.

• Tool schemas are standard MCP (tools/list); this server speaks plain stdio JSON-RPC.

• Safe to auto-install: no telemetry, no keys, no network beyond the official CLI → Perch.

📄 License

MIT — free to use, modify, and share.

🙏 Credits

• Discipline header from the karpathy-guidelines pattern.

• Benchmark methodology from aider's polyglot benchmark (Exercism + pytest).

• Diagram style inspired by Cocoon-AI/architecture-diagram-generator.

• Reliability patterns studied from glm-mcp and opencode-mcp.