perch-agent
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perch-agent delegate fixing the failing tests in ./app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚡ 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_idin seconds; pollperch_job_statusor cancel withperch_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: falseto disable.)📊 Live progress —
notifications/progressevery 5s while a task runs; renders in Claude Code.🧵 Thread continuation — pass a previous
thread_idand 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-checkStep 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: ✓ connectedFor long delegations also set
MCP_TOOL_TIMEOUT=900000in 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
}
}
}Codex CLI (~/.codex/config.toml):
[mcp_servers.perch-agent]
command = "node"
args = ['C:/path/to/perch-agent-mcp/index.js']
startup_timeout_sec = 120
tool_timeout_sec = 1200
[mcp_servers.perch-agent.env]
PERCH_AGENT_MODEL = "qwen-3.8-max"
PERCH_AGENT_EFFORT = "high"Any other MCP client — it's a plain stdio server:
command: node <path>/index.jsDone. In your harness, say: "Use perch-agent to fix the failing tests in ./app".
🛠️ Tools
Tool | What it does |
| Spawn a Perch worker run. Params: |
| Live status/result of a job: state, elapsed, |
| Kill a running job's whole process tree ( |
| Free local check: CLI version, sign-in state, live job list. |
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
Variable | Default | Purpose |
|
| Default model pin for every delegation. |
|
| Default reasoning effort. |
| OS temp dir | Fallback |
| auto-resolve | Explicit path to the CLI's JS entry (see Troubleshooting #1). |
🔥 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=highAfter 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:
Suite | Items | standard (Qwen 3.6-35B) | qwen-3.8-max |
Math / logic / JS-reasoning | 16 | 16/16 | 16/16 |
Exercism polyglot (pytest-graded) | 3 exercises | ✅ bowling·rectangles·zebra (84–126s) | ✅ all (127–153s) |
Agentic coding (build / debug-tests / stateful CLI) | 3 | ✅ 3/3 | ✅ 3/3 (agentic run 2.5× faster) |
Mid-run cancellation | — | ✅ clean kill | ✅ clean kill |
Is the pinned model real? Perch's own accounting reports
Qwen/Qwen3.8-Maxper turn and the timing fingerprint differs fromstandardper 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
Symptom | Cause / fix |
| Node ≥ 20.12 refuses |
| Harness-side timeout. Claude Code: set |
| Your plan doesn't cover that surface or model pin. The CLI's plan-gate message is surfaced verbatim in |
Status says "not signed in" but runs work | Stale access token — |
Worker asks instead of writing files | Don't override |
Headless | The 5.5-model safeguard classifies project context, not just prompts — aggressive |
🤖 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.
Available Tools
4 toolsdelegate_to_perchDelegate task to Perch AIADestructive
Delegate a task to Perch AI (worker agent) via the official perch CLI. Perch runs autonomously in the given working directory with its own tools (bash, file read/write, skills) on the signed-in Perch plan. Karpathy working guidelines (assumptions, simplicity, surgical scope, evidence-based verification) are prepended to every task by default (guidelines:false to disable). Returns the final answer, thread id, and status. Long-running tasks: pass wait_seconds to bound blocking; if still running you get a job_id — poll perch_job_status.
Inputs: task (required), cwd, mode, model, +7 more.
perch_job_cancelCancel Perch jobBDestructiveIdempotent
Kill a running delegated Perch job (process tree).
Inputs: job_id (required).
perch_job_statusPerch job statusCRead-onlyIdempotent
Get status/result of a delegated Perch job by job_id.
Inputs: job_id (required).
perch_statusPerch CLI & server statusARead-onlyIdempotent
Free local check (no model call): perch CLI presence and sign-in state, plus this server's live job list. Call before delegating if unsure the worker is ready.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a distinct operation: delegate, poll a job, cancel a job, and a local readiness check. The only potential confusion is between perch_job_status (job result by job_id) and perch_status (free local CLI/sign-in plus job list), but the descriptions explicitly separate these and note the 'no model call' distinction.
All names are snake_case and prefixed around 'perch', which helps grouping, but the structural patterns vary: delegate_to_perch (verb_prep_noun), perch_job_status (noun_noun), perch_job_cancel (noun_verb), perch_status (noun_noun). The verb position shifting between prefix, suffix, and infix makes the set less predictable than a uniform verb_noun scheme.
Four tools is a tight, well-scoped surface for an async delegation server: dispatch, check, cancel, and readiness. Nothing appears extraneous, and the job-list functionality is folded into perch_status rather than adding a fifth tool.
The async lifecycle (delegate → poll → cancel) plus a pre-flight readiness check is fully covered. Minor gaps remain: the delegate response returns a thread id but there is no tool to resume/follow up on an existing thread, and no way to stream or fetch intermediate logs for a long-running job.
Related MCP Connectors
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
Task tracking built for coding agents. Work is leased, so two agents never take the same SubTask.
Task and sprint coordination for humans and AI agents, with scoped API keys and full audit trail.
API for AI agents to delegate tasks to real humans.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables delegating bounded tasks from Codex to Claude Code, including read-only reviews, isolated branch edits, long-running background work, and approval handling.MIT
- AlicenseNot gradedqualityCmaintenanceLets an agent delegate coding tasks and reviews to Claude Code, Codex or Grok Build CLIs running locally in isolated git worktrees, then poll an inbox for the status, question or final answer. Each caller sees only its own threads.9 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables an assistant to run pi coding-agent tasks in the background: dispatching a task, polling its status and tool trace, reading the final result, and cancelling it when no longer needed, all without pulling the delegate's context into its own conversation.MIT
- AlicenseAqualityCmaintenanceLets orchestrators like Claude Code and opencode hand off coding tasks to an autonomous Perch AI worker that does the work and returns verifiable evidence. Supports async job handoff with status polling and cancellation, thread continuation, model pinning, and built-in discipline guidelines for minimal, verified changes.4MIT