Quickstart

Start a task with one command. The agent recommends a flow, Circuit runs it, and it stops for your call when the result depends on it.

Run a task

A real run spawns worker steps that spend model time: a small first task typically takes several minutes end to end and costs a few dollars at the default dials. Flows that can edit files (Build, Fix, Prototype) say so before the work starts; Review and Explore never edit code. If you want to see what a run would do before spending anything, jump to preview below.

In your coding agent, describe the task:

/circuit:run add a rate limit to the login endpoint

The agent reads the task and recommends a flow: Build, Fix, Explore, Review, or Prototype. You do not pick it; Circuit records the selected flow when the run starts, then runs it step by step.

Respond to a checkpoint

A flow may pause at a checkpoint when it needs your decision, for example to confirm the brief before it starts changing code. Circuit shows the prompt and the choices. Pick one to continue.

At low and medium process, a checkpoint that declares a safe default resolves with it automatically; at high process or in a tournament the run waits for your answer.

From the CLI

The CLI is the engine underneath the command above; running it directly just skips the step where the agent picks the flow for you. See Installation to install it. Name the flow and pass the task as --goal:

circuit run fix --goal 'login fails when the email has a plus sign'

The CLI requires an explicit flow name. It never guesses a flow from your words; in the agent, the agent is what recommends a flow for you.

Running from a shell does not drop the agent dependency. Worker steps still route through a connector, and the default one spawns the claude CLI for each step, so keep that binary installed. Set relay.default with circuit config to route steps elsewhere.

Add --power low to a CLI run to spend less: the steps that write code drop to a cheaper model while the steps that decide direction keep theirs. See Modes for the dial.

See the plan before you spend anything

The experimental preview command shows what a flow would do before anything runs: which connector, model, and effort each step gets, at every power setting, without spawning a worker.

circuit preview build --matrix

It costs nothing to run. When the readout looks right, run the real task.

Next

• Flows: the six flows and when each one fits.
• Checkpoints: how pauses and choices work.