Troubleshooting

Most of what goes wrong leaves evidence in the run folder, so the first move is usually the same: find the run under .circuit/runs/<run-id> and read what it recorded.

A run is stuck at a checkpoint

A run that stops mid-flow is usually not stuck; it is waiting. Check its state:

circuit runs show --run-folder .circuit/runs/<run-id> --json

If the engine state is waiting_checkpoint, the run paused at a checkpoint and wants a decision. The run folder records the checkpoint request: the context to review and the allowed choices. Answer it by resuming with one of those choices:

circuit resume --run-folder .circuit/runs/<run-id> --checkpoint-choice <choice>

Two things to know:

• The choice must be one the checkpoint allows. An unrecognized or stale choice is rejected. Reread the recorded request rather than guessing.
• Some checkpoints declare a safe default. At low and medium process they auto-resolve with it. Under autonomous mode the checkpoint resolves with the flow's shipped policy when it carries one (Explore and Prototype pick the highest-scoring option) and falls back to the safe default otherwise. A pause that waits indefinitely means the run is at high process or in a tournament, where your judgment is deliberately required.

A relay step fails with a connector error

A connector is the backend that runs a relay step. When one fails, check these in order:

1. Is the backend installed? The builtin codex connector shells out to the Codex CLI. If it is missing, install it: npm install -g @openai/codex.
2. Does the config parse? The relay block parses strictly: unknown keys are rejected, and a named reference must point at a connector registered under connectors. A typo in either fails before any work runs.
3. Is a custom connector in a role it cannot fill? Custom connectors are read-only, so they cannot take the implementer role. Use a builtin for implementer; use custom connectors for researcher and reviewer.

The failed relay's request and result are saved in the run folder, so you can see exactly what the connector was asked and what came back.

Inspecting a past run

Every run keeps its full record in its run folder: trace, reports, and evidence stay on disk after the run closes.

Project a run's status (engine state, current step, terminal outcome):

circuit runs show --run-folder .circuit/runs/<run-id> --json

Inside the folder, the trace is the ordered record of what happened (step entry, relay requests, checkpoints, completion), and each report is a typed output a step wrote. Reading the trace top to bottom is the fastest way to see where a run went sideways.

To search across many past runs instead of one folder, use the history index:

circuit history query <search text> --json

The marketplace add fails

/plugin marketplace add petekp/circuit fetches the marketplace from GitHub, so it needs network access and a reachable github.com. If the short form fails, try the full URL:

/plugin marketplace add https://github.com/petekp/circuit

A marketplace you added earlier can serve stale entries; remove it and add it again:

/plugin marketplace remove circuit
/plugin marketplace add petekp/circuit

Circuit still runs after I removed the plugin

Install adds an instruction block to AGENTS.md and CLAUDE.md that tells the agent to start every task with Circuit. That block lives in your project, not in the plugin, so removing the plugin leaves it behind and the agent keeps invoking Circuit. Strip it with circuit uninstall.

Related

• Installation
• Checkpoints
• Evidence and runs
• Connectors
• circuit uninstall