> For the complete documentation index, see [llms.txt](https://docs.fritesai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fritesai.com/architecture/mcp-worktree-mode.md). # MCP worktree mode MCP worktree mode (`apps/mcp`, `@frites/mcp`) is frites's **Stance B** surface: an on-demand MCP tool that runs N competing full implementations as real agents in isolated git worktrees, filters them through the repo's test suite as the ground-truth oracle, and recommends one vetted diff. It exposes two tools over stdio: `frites_implement` and `frites_apply`. Impersonation is the wrong fit here: returning N candidate diffs plus a comparison and running minutes-long worktree agents needs a tool call, not a single model turn. So the heavy multi-agent file-edit work lives on the MCP surface rather than the gateway. ## MCP transport and host quirks The tools run over stdio. Several MCP host behaviors are load-bearing and were verified against the real hosts: * **Progress notifications are display-only. They do NOT extend either host's deadline.** Size timeouts to worst-case wall-clock up front. * **Claude Code:** set the per-tool `timeout` to `600000` and `alwaysLoad: true` so the tool isn't hidden behind Tool Search. It renders `notifications/progress` inline. * **Codex:** `tool_timeout_sec` defaults to **60s and MUST be raised to 600** or every run dies. * **Result size:** Claude warns at \~10k tokens and hard-caps at \~25k. Return compact `structuredContent` plus a `resource_link` to each diff, never inline N full diffs. * **No MCP `sampling` for the judge:** Claude Code doesn't implement a sampling client and Codex explicitly refused to. frites calls models with its own credentials instead. ## Worktree execution When the host calls `frites_implement {task, repoPath, n?, agents?}`, the engine: 1. Selects N agents from the task or config and resolves the base commit. 2. Creates one isolated git worktree per agent (managed by `@frites/isolation`). 3. Spawns detached headless children that edit in their own worktree concurrently, each launched with an allowlist env built by the `EnvSandbox` (auth kept, base-URLs scrubbed, `FRITES_DEPTH` incremented). 4. Streams `notifications/progress` ("agent 2 editing app.ts / running tests") as the children work. The worktree lifecycle, diff capture, and cleanup are documented in [Isolation](/architecture/isolation.md). ## Candidate diffs and oracle filtering Each child's work is captured as a candidate diff (`git diff --staged`). The engine then runs the configured or auto-detected oracle commands (build, lint, test) against each candidate and reconciles them into one recommendation: * Candidates that errored, timed out, were empty, or touched no files are ignored. * If oracle commands exist, only candidates whose oracle passed are kept; the closest near-miss is surfaced if none pass. * One passing candidate is recommended directly; multiple passing candidates are tie-broken by the deterministic smallest-blast-radius `heuristicJudge` (fewest changed lines, then fewest files). An optional, on-by-default synthesis stage can integrate the passing candidates' deltas into one re-validated candidate. The full reconciliation and synthesis algorithm is canonical in [Synthesis & reconciliation](/concepts/synthesis-and-reconciliation.md), and the oracle mechanics are detailed in [Worktree oracle](/concepts/worktree-oracle.md). ## Apply flow The MCP path lands changes only via an explicit, gated apply. It never auto-merges or pushes: 1. `frites_implement` returns `structuredContent` plus `resource_link`s to each candidate diff. The caller persists diffs and run metadata for review. 2. The user reviews the recommended diff and the per-candidate comparison. 3. `frites_apply {runId}` lands the diff on a fresh branch: `git switch -c frites/ && git apply --3way`. It accepts a `candidateId` so a reviewer can land a tighter passing child instead of the recommended candidate. This explicit apply is the one mandatory human gate. The permission posture for worktree children (bypassed permissions for Claude, `-s workspace-write` with approvals disabled for Codex) is canonical in the [Safety model](/product/safety-model.md). ## Related pages * [Isolation](/architecture/isolation.md): worktree lifecycle, diff capture, apply-to-branch. * [Worktree oracle](/concepts/worktree-oracle.md): the test/build/lint oracle. * [MCP tools](/reference/mcp-tools.md): the `frites_implement` / `frites_apply` tool reference. * [Core engine](/architecture/core-engine.md): the shared engine state machine. * [Data flow](/architecture/data-flow.md): the end-to-end worktree sequence. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.fritesai.com/architecture/mcp-worktree-mode.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.