How Circuit works
The evidence gate, the honesty machinery, per-archetype model allocation, and the run folder that proves what happened.
Circuit is a workflow engine that runs typed developer flows. The Claude Code and Codex plugins are the bridge that teaches a host agent to drive it, and today they are also the fastest way to install Circuit and start a run. Underneath, it is a plain CLI, and everything below is true of the engine itself, whichever way you reach it.
Encode your process
You already have a way you want agent work done: a habit, a checklist, the review you always run before calling something finished. Right now you carry that process yourself, one instruction at a time, in chat. Chat is where a process gets figured out. A flow is where it goes to run.
A flow encodes that process once, as a sequence of typed steps, so you stop being the runtime that remembers the order, holds the state, and nudges the agent through it every single time you delegate the same kind of work.
The evidence gate
A CLAUDE.md instruction, or a skill, is a request the model can honor or quietly skip. A Circuit step is different: it cannot advance, and a flow cannot close, without the evidence its checks require. The check runs in the engine, not in the model, so a worker cannot talk its way past it by asserting the work is done.
Concretely, in the Fix flow: the run will not move from diagnosis to action until the diagnosis report is well formed and accepted, and it cannot close as fixed without the verification and regression-rerun output actually present. Saying "verified" is not enough; the output has to exist and pass.
This is not a claim that the work is correct, only that the required proof exists and parses. Judging whether the work itself is sound is what the independent reviewer step is for.
The honesty machinery
A flow can also be shaped as a loop: a span of steps that re-enters, pass after pass, until a reviewer step proposes the goal is met and the engine's own evidence agrees. The engine reads only the proposal's met-or-not claim, never its reasoning, and checks that claim against the pass's own verification result before it believes it.
An append-only honesty ledger backs this. If a step overclaims, or exhausts its retries without a clean check, the run does not pretend otherwise: it records an open latch and moves on. The run cannot close as succeeded while any latch is open; it closes honestly as stopped instead, and names what did not clear. Running out of iterations, budget, or progress reports as not done, never as done, and the CLI's exit code mirrors that closed outcome, so a script checking only the exit code still gets an honest answer.
This loop is proven inside the engine today by internal flows built to exercise it; no flow in the public catalog opts into it yet. See The until loop for the full mechanism and its honest limits.
One dial, per-archetype model allocation
Circuit decides model and effort per step, not once for the whole run. Each step fills an archetype, researcher, implementer, or reviewer, and turning one dial decides which model fills it: archetypes that decide direction keep the strong model, archetypes that execute run on a cheaper one, and a flow can even pin one step to a different connector entirely. Research stays on the strong tier at every dial position, because the reading that steers a run is the wrong place to save.
You do not have to take that on faith.
circuit preview prints the connector, model, and
effort every step would get, at every dial position, without spawning a
single worker. After a real run, the summary shows what each archetype actually
spent.
The run folder
Every run writes a run folder: the ordered trace of what happened, the typed report each step produced, the supporting evidence, and the state needed to resume. It is built so someone who was not watching the run can open the folder afterward and trust what it says, instead of reconstructing what happened from a chat log. See Evidence and runs for what is inside it.
The mechanics
The sections above are what a flow is for. This section is how one is put together, for when you are authoring a flow or reading a trace.
Stages and steps
A flow is organized into stages: Frame, Analyze, Plan, Act, Verify, Review, and Close. Each stage holds steps, and each step is one use of a block: a reusable kind of work that can appear in a schematic.
A step has a kind that decides what it does:
- Relay: delegate work to a worker through a connector.
- Compose: the orchestrator writes a report.
- Verification: run checks against the work.
- Checkpoint: pause for a decision.
- Fanout: run branches and join their outputs.
- Sub-run: run a child flow.
A relay step assembles a fresh worker for that step alone: a micro-harness built from a model and effort resolved from its archetype and the power dial, a tool scope, the skills it needs, and only the inputs its contract declares. The worker writes its typed output and is gone, so nothing it accumulated leaks into the next step. That is the direct answer to a long session's context rot: later steps are not carrying the chatter of earlier ones.
Typed inputs and outputs
Every block declares a typed input and a typed output. Each one is a named,
versioned contract: flow.brief@v1, plan.strategy@v1, change.evidence@v1.
A step is one use of a block, so it carries that contract: it reads inputs of
the shapes it names and writes one typed output, a
report.
A step's output is itself a contract, so it becomes the input a later step reads. Those contracts are how a flow wires together, and they are what gives the evidence gate above something concrete to check: a step is placed only where the inputs it names are already produced upstream.
Routes
Steps connect through routes: named outcome paths that decide what happens
next. A route either points to the next step or to a terminal target. The
terminal targets are @complete, @stop, @handoff, and @escalate, and
each closes the run with the matching outcome.