Configuration
Configuration file
Where Circuit config lives and how layers combine.
Config is optional. With no config file, Circuit runs on built-in defaults. A file lets you pin connectors, selection, skills, and per-flow overrides.
Where it lives
Circuit reads two files:
| Path | Layer |
|---|---|
~/.config/circuit/config.yaml | user-global |
.circuit/config.yaml (project root) | project |
Either can be absent. A missing file is skipped, not an error.
How layers combine
Four layers compose in precedence order, later wins:
default < user-global < project < invocationdefault is the built-in baseline. invocation is what a single run passes in. Each layer overrides the one before it for the keys it sets.
Schema versions
The first key is schema_version.
1: selection config (the keys below).2: a policy envelope (advanced):policy.rules,policy.limits,policy.preferences,policy.defaults.
Most projects want version 1.
Example (version 1)
schema_version: 1
# Stable identity for project memory across worktrees and clones.
project_id: my-app
# Host the agent runs under: generic-shell | claude-code | codex.
host:
kind: claude-code
# Relay routing to connectors. See Connectors.
relay:
default: auto
# Skill slot bindings. See Skills.
skills:
bindings:
reviewer: code-review
# Per-flow overrides, keyed by flow id.
circuits:
fix:
selection:
depth: high
# Baseline selection and dial defaults applied to every run. See Selection.
defaults:
power: low
selection:
effort: highParsing is strict. Unknown keys are rejected at parse time, so a typo like defuults: fails loudly instead of being silently ignored.
Version 1 keys
| Key | Description |
|---|---|
schema_version | 1. Required. |
project_id | Stable id for project memory. Inferred from the git remote when omitted. |
host | kind: generic-shell, claude-code, or codex. |
relay | Relay routing to connectors. See Connectors. |
skills | Skill slot bindings. See Skills. |
skill_hooks | Skill-hook policy and detection. |
circuits | Per-flow overrides, keyed by flow id. |
power_tiers | Per-connector tier tables for the power dial, keyed by connector name. |
power_auto | Floor and ceiling bounds for the auto power dial. Concrete tiers, each optional; the floor must not be above the ceiling. Inert unless the dial is auto. |
defaults | Baseline selection (defaults.selection) and the power dial default (defaults.power: auto, low, medium, or high) for every run. See Selection. |