circuit

The process your coding agent follows

Circuit helps coding agents work like experienced practitioners: following a clear process, applying the right skills at the right time, and checking their work against evidence. One power dial sets the spend: Circuit picks the model, effort, and tools for each step from the step's role, so the reading that steers the run stays on the strong tier while routine steps run cheap. It gives agents and operators a better working environment than ad-hoc chat.

Circuit is a workflow engine at its core, driven from a plain CLI. The Claude Code and Codex plugins are the bridge that teaches a host agent to drive that CLI, and today they are also the fastest way to install and try Circuit.

Go from this:

• Remember which chat thread has the latest state
• Remember which skill to use and when
• Ask for routine planning, checking, and review steps by hand
• Wonder whether the agent took shortcuts or repeated an old mistake
• Keep nudging the process forward yourself

To this:

• /circuit:run build the thing

Circuit puts the process into a repeatable flow:

• Records the chosen flow, built-in or custom
• Moves through each step in sequence and/or parallelizes non-dependent steps
• Applies your preferred skills at the appropriate steps
• Uses your preferred model(s) and thinking power for particular steps
• Checks step outputs before continuing, including deterministic relay acceptance criteria where a flow declares them, with traces, reports, and evidence that show what passed

Ready to try it? Pick a host below, or point your coding agent at the setup prompt. For the full docs map, see docs/README.md.

Start Here

Pick the path that matches where you want to use Circuit. Claude Code and Codex reach the same workflow engine through a plugin; Local CLI runs that engine directly. If you want a coding agent to set this up for you, skip to Give This To A Coding Agent.

Claude Code

Install the host plugin:

/plugin marketplace add petekp/circuit
/plugin install circuit@circuit
/reload-plugins

Then ask Circuit to handle a task:

/circuit:run the checkout total is wrong when discounts and tax both apply

A real run spawns worker agents that spend model time: a small task typically takes several minutes end to end and costs a few dollars at the default dials. Review is read-only and the safest first run. The power dial spends less: --power low on a CLI run, or defaults.power in config.

The installed plugin bundles the whole engine, so you do not need to clone this repo, run npm install, install a separate circuit binary, or create a symlink to get started this way.

Codex

Install the published plugin from the marketplace:

codex plugin marketplace add petekp/circuit --ref circuit--v0.1.1

Working from this checkout instead? Refresh the local plugin package and installed host caches:

npm run plugins:refresh-local

Then ask Codex to use Circuit:

/circuit:run the checkout total is wrong when discounts and tax both apply

Codex can recommend the right Circuit flow from your natural-language request.

Local CLI

Install the CLI directly from npm:

npm install -g @petepetrash/circuit
circuit doctor
circuit run <flow> --goal '<your task>'

Circuit does the work through connector CLIs (claude by default), so a signed-in Claude Code install is a prerequisite. circuit doctor confirms the connectors your runs would actually use are ready, before a run spends anything on a broken one, and lists any other connector CLI as optional.

Working from this checkout instead?

npm install
npm run build
./bin/circuit run <flow> --goal '<your task>'

The flow name is required: one of build, fix, review, explore, or prototype. The CLI runs from any directory: it prefers compiled flows in the current project and falls back to its own bundled copies. The operator guide covers pointing at a specific flow folder with --flow-root.

Circuit requires Node.js 22.18.0 or newer.

One scope note: flows that change code (build, fix) verify their work through your project's package.json scripts (verify, test, or check), so today they need an npm-family project. review, explore, and prototype work in any repo.

For a more careful manual check, use docs/first-run.md. For the repo map, use docs/repository-map.md.

Start From An Intent

/circuit:run is the normal front door on every host. See docs/operator-guide.md for the per-host table, the CLI flow-name rule, and the host-alias status.