> 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/overview.md).

# Overview

frites is a coordinator that dispatches a task to **multiple full coding agents**, has each do real work, then **diffs / tests / judges** their results into one vetted answer, driven from your normal Claude Code or Codex session. The value is *reconciliation quality*: many independent attempts filtered by execution, not vibes. The moat is the selector, not the fan-out.

This page is the entry point for the architecture cluster. It covers the repo-level shape, the high-level decisions that drove it, and the layer diagram. Each subsystem has its own page linked below.

## Repository shape

frites is a TypeScript pnpm monorepo split into thin **apps** (runnable entry points) and the heavy logic in **packages** (libraries with no entry points). The deliberate goal is to keep all reconciliation logic in `packages/core` so it stays transport-agnostic and fully unit-testable with mocked runners and oracles.

```
apps/                              # runnable tools (deployables / entry points)
  gateway/     @frites/gateway    TRANSPARENT PROXY (primary surface): impersonates /v1/messages
                                   (Claude Code) + /v1/responses (Codex); intercepts every prompt,
                                   answer/action-council fan-out per fanOutPolicy + fanOutScope,
                                   SSE streaming, per-turn cost telemetry. Stance-A: synthesizes the
                                   assistant turn — emits host-executed tool_use on coding turns.
  mcp/         @frites/mcp        on-demand MCP tool surface (Stance B): frites_implement +
                                   frites_apply — heavy multi-agent file edits in worktrees → diffs
  cli/         @frites/cli        standalone `frites run` + `frites config` — same engine
packages/                          # libraries (no entry points)
  core/        @frites/core       engine (funnel) + oracle + judge + config + answer-council
  isolation/   @frites/isolation  git worktree lifecycle, diff capture, apply-to-branch
  agents/      @frites/agents      headless claude/codex runners + completions + cost estimation
                                   + EnvSandbox (recursion guard)
```

The apps stay thin: each transport adapts a wire format and streams progress, but the funnel, oracle, judge, config, and councils all live in `packages/core`.

## Two surfaces, one engine

frites ships two transports over one shared engine, for different needs:

| Surface                         | Stance                              | Best for                                                                                      |
| ------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
| **Gateway** (transparent proxy) | Stance A: answer/action synthesizer | The frictionless everyday brain: Q\&A, reasoning, and coding edits on *every* prompt, metered |
| **MCP** (worktree mode)         | Stance B: agentic broker            | Deliberate heavy multi-agent file edits in worktrees, filtered by tests                       |

The gateway is the **primary, everyday surface and is Stance A**: children are stateless completions, the host keeps its tool loop, and frites fans out per turn and synthesizes the assistant turn. On a coding turn it emits the `tool_use` the host executes (the children *decide* the action; they don't edit files). The MCP path is Stance B: children are full agents that do real file edits in isolated worktrees, and frites reconciles their work with the test suite as the ground-truth oracle.

The standalone CLI (`frites run` / `frites config`) calls the same engine for testing, CI, and power use.

## High-level decisions

* **Both stances ship.** The transparent-proxy gateway is the primary, lowest-friction surface (Stance A, verified editing real code end-to-end via host-executed `tool_use`, no API key). The MCP `frites_implement` path is Stance B, for when you want N competing full implementations filtered by tests.
* **"N-way merge" is the wrong mental model.** frites never mechanically merges N divergent edit trees. Reconciliation is LLM-mediated best-of-N selection, with the test suite as the ground-truth oracle and the judge scoped to *only* tie-break test-passing survivors. See [Synthesis & reconciliation](/concepts/synthesis-and-reconciliation.md).
* **Diversity comes from model-mix + prompt-framing, not temperature.** Neither `claude` nor `codex` exposes a temperature flag, so candidate diversity must come from mixing model families (claude × codex) and prompt framing. The default leans toward N=2 (1 claude + 1 codex).
* **Fan-out is scoped to the substantive turn.** The gateway does not fan out a full council on every mechanical tool-loop step or on background/utility traffic. See [Fan-out scope](/concepts/fan-out-scope.md).
* **Language: TypeScript, pnpm monorepo.** I/O-bound orchestration glue around finicky wire formats, where the official SDKs are TS-first.

## Engine state machine

The engine is a state machine over a funnel and holds zero CLI/MCP coupling:

```
DISPATCH → EXECUTE (N children in worktrees, concurrent)
        → ORACLE-FILTER (run repo tests/build/lint per candidate)
        → reconcile:  1 survivor → done
                      0 survivors → one grounded feedback round → re-filter;
                                    else surface best near-miss
                      ≥2 survivors → JUDGE (pairwise tie-break, prefer smaller diff)
        → optional gated SYNTHESIS (re-validated through oracle)
        → PRESENT (recommended diff + per-candidate comparison)
        → APPLY (on approval: git switch -c frites/<runId> && git apply --3way)
```

The engine internals, event model, and failure modes are documented in [Core engine](/architecture/core-engine.md).

## The rest of the architecture cluster

* [Gateway](/architecture/gateway.md): transparent proxy design, `/v1/messages` + `/v1/responses`, SSE, action synthesis, tool-call emission.
* [MCP worktree mode](/architecture/mcp-worktree-mode.md): MCP transport quirks, worktree execution, candidate diffs, oracle filtering, apply flow.
* [Core engine](/architecture/core-engine.md): engine internals, synthesis engine shape, event model, failure modes.
* [Agents & runners](/architecture/agents-and-runners.md): headless claude/codex runners and completions.
* [Isolation](/architecture/isolation.md): git worktree lifecycle, diff capture, apply-to-branch.
* [Data flow](/architecture/data-flow.md): end-to-end request flow for both surfaces.
* [Risks & tradeoffs](/architecture/risks-and-tradeoffs.md): the "better output, slower" tradeoff and the top risks.

For the safety and permission posture, see the canonical [Safety model](/product/safety-model.md). For child auth and billing, see [Auth & billing](/product/auth-and-billing.md).


---

# 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/overview.md?ask=<question>
```

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.