Installation

Circuit is a workflow engine driven from the command line. The Claude Code and Codex plugins are the bridge that teaches a host agent to drive it, and today they are also how most people install Circuit and start a run. Pick the path that matches how you work.

Requirements

• Node >= 22.18.0

No API keys go in Circuit. The host agent (Claude Code or Codex) handles auth. Configuration is optional.

Claude Code

Run these in the agent:

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

The install worked when typing /circuit lists the plugin's commands, /circuit:run among them. If the marketplace add fails, see Troubleshooting.

Codex

Run this in your shell:

codex plugin marketplace add petekp/circuit --ref circuit--v0.1.0-alpha.10

CLI

Install the CLI directly from npm:

npm install -g @petekp/circuit
circuit doctor

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; connector CLIs no flow chooses are listed as optional and never fail the check.

Run a task with circuit run <flow> --goal '<your task>'. The CLI requires an explicit flow name: build, fix, explore, review, or prototype.

Working from a repo checkout instead:

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

Optional: Codex as a worker

Circuit can route work to the Codex CLI through the codex connector. Install it only if you use that connector:

npm install -g @openai/codex

Removing Circuit

Run circuit uninstall in a project to strip the Circuit instruction block from its AGENTS.md and CLAUDE.md. It then prints the commands that remove the plugin from your host. For Claude Code:

claude plugin uninstall circuit@circuit
claude plugin marketplace remove circuit

For Codex:

codex plugin marketplace remove circuit

Next

• Quickstart runs your first task.
• Flows overview covers the flows.