circuit

circuit-next

Structured flows for coding agents.

Circuit is an orchestration layer for structured, resumable, multi-stage developer flows. Ask Circuit to handle a task in natural language. In Claude Code, /circuit:run selects the right flow before it starts. In Codex, @Circuit lets Codex choose the best bundled Circuit skill. In the local CLI, circuit-next run --goal keeps the deterministic router path.

Once a flow is selected, Circuit runs the same headless engine in every host and checks each step's output against a contract before moving on.

• Configurable relay steps. Pick the model, reasoning effort, connector, and optional local skills through flow and config selection layers.
• Resumable. If a session dies mid-run, you can pick up where it left off.
• Adjustable autonomy. Steer at checkpoints or run unattended.
• Mode-driven depth. Use the default mode, or pick Lite for a faster pass and Deep for a more thorough one.

Get Started

Circuit is currently a pre-release alpha. Install it directly from a checkout:

git clone https://github.com/petekp/circuit-next.git
cd circuit-next
npm install
npm run build

Then run a flow through the local launcher:

./bin/circuit-next run --goal '<your task>'

The CLI router classifies your task and runs the right flow. To use the slash commands inside Claude Code, load the self-contained plugin package:

claude --plugin-dir ./plugins/claude

To use Circuit from Codex, install or refresh the Codex plugin package and ask Codex to use @Circuit. Codex can choose the best bundled Circuit flow skill from your natural-language request.

Optional but recommended: drop a personal config at ~/.config/circuit-next/config.yaml to set defaults (model, reasoning effort, local skills, connector routing) across every project. A repo-local ./.circuit/config.yaml overrides those defaults per project. See User-Space Configuration for details.

How It Works

Circuit replaces ad-hoc skill invocation and copy-pasted instructions. Use one natural-language front door for normal work, or call a flow directly when you already know what you want.

Core Flows:

These flows ship with the plugin. Build, Fix, Explore, Review, Migrate, and Sweep can all be selected by the host model or invoked explicitly.

Flow	Purpose
Explore	Investigate, understand, choose among options, shape a plan
Build	Features, refactors, docs, tests, mixed changes
Fix	Bugs, regressions, flaky behavior
Review	Audit-only review, no implementation
Migrate	Framework swaps, dependency replacements, architecture transitions
Sweep	Cleanup, quality passes, coverage improvements

Modes:

Each flow accepts a mode at run time that scales how thorough the run is and which review steps fire.

Mode	Behavior
Default	Plan, act, verify, independent review where the flow includes one.
Lite	Skips the review relay where the flow allows it. Use for small, low-risk changes.
Deep	More thorough analysis and review. Pauses for input at architecture-class checkpoints.
Tournament	Competing proposals with adversarial evaluation. Available on Explore and Review.
Autonomous	Checkpoints auto-resolve to safe defaults. Useful for unattended runs.

Pass a mode with --entry-mode <lite|deep|autonomous> (or --mode, the shorter alias). Tournament is a depth-level option exposed through --depth tournament on the flows that support it. Mode availability varies by flow; see each flow's src/flows/<id>/schematic.json for the authoritative list.

Every flow is built from a fixed set of stages: Frame, Analyze, Plan, Act, Verify, Review, Close. Not every flow runs every stage, but the order holds.

1. The flow is selected. In host plugins, the host model may choose a flow before calling Circuit. In CLI router mode, Circuit's deterministic router chooses.

2. Steps run in the right order. Research before decisions. Decisions before implementation. Implementation gets an independent review from a separate worker. Every step writes a typed report and an entry in the run trace.

3. Progress survives session crashes. Each run gets its own folder with a trace, reports, and evidence. If a session dies, resume against that folder and Circuit picks up at the last completed step.

4. Stay in the loop. Flows pause at checkpoints when they need scope confirmation or a tradeoff decision. Everything else runs autonomously. Autonomous mode resolves checkpoints to their safe default and keeps going.

Commands

Default front doors: