KiCadAI

AI proposes. KiCadAI proves—or refuses.

KiCadAI turns bounded behavioral requirements into deterministic, evidence-backed native KiCad projects—and stops when it cannot prove a design inside its reviewed component, model, simulation, and physical-design envelope.

It is not a prompt-to-schematic wrapper or an unrestricted circuit oracle. The AI-facing boundary accepts behavior; deterministic code owns architecture and part selection, calculations, simulation, schematic and PCB generation, placement, routing, validation, and the final pass-or-refuse decision.

See The Proof

The featured demo asks for a protected 0.1 A/V programmable current output across supply, load, startup, temperature, and safe-operating-area corners. Its input names no component, topology, internal net, value, coordinate, layer, or route.

make public-demo

On the recorded KiCad 10.0.3 run, KiCadAI derived 43 candidate graphs, completed and simulated two competing physical architectures, performed 194 candidate simulations and 6,326 corner evaluations, selected real catalog parts and values, and then generated the same native KiCad project twice.

Required proof	Recorded result
Behavioral architecture search	2 complete simulation-passing architectures
Placement and routing	15/15 components placed; 12/12 nets routed
Connectivity	0 unconnected endpoints or DRC unconnected items
Writer correctness	10/10 checks passed
KiCad ERC / strict DRC	0 / 0 violations
Normalized KiCad round trip	0 differences
Deterministic physical replay	2 identical project hashes

Inspect the input, native KiCad files, screenshots, commands, compact evidence receipt, and video storyboard. The receipt binds the requirement, inventory, models, catalog, policy, architecture ranking, physical output, and verification results with content hashes. Run make public-demo-refusal to verify that an excessive thermal/SOA request exits unsuccessfully and emits no KiCad project.

This is an ERC/DRC-checked deterministic candidate, not a fabrication release. Human electrical, thermal, mechanical, compliance, and manufacturing review remains required.

What Makes It Different

• Behavior in, proof out. The open-topology input schema rejects component, topology, model, internal-net, value, geometry, route, provider, and repair instructions.
• Search is deterministic and bounded. Candidate generation, value selection, simulation corners, repairs, ranking, and tie-breaking are recorded and content-addressed.
• KiCad is part of the evidence. KiCadAI writes native .kicad_sch, .kicad_pcb, and .kicad_pro files, then uses installed KiCad for ERC, strict DRC, and normalized round trips.
• Failure is a valid result. Missing evidence, unsafe operating envelopes, unsupported behavior, exhausted search, incomplete routing, or validation failures stop project promotion instead of being papered over.
• Claims have boundaries. Supported, experimental, and unsupported states are explicit; experimental output cannot receive a promotion-pass or fabrication-ready claim.

The full path is:

behavior → capability gate → topology/value search → trusted simulation
         → native schematic/PCB → placement/routing → KiCad + writer checks
         → identical replay → pass or refusal

Capability At A Glance

State	What it means today	Evidence
Supported	Reviewed slices of analog, protected current output, low-energy nonlinear/switching, mixed-domain control, MCU, power-tree, sensor, interface, and functional hierarchical four-layer generation can reach deterministic KiCad-backed pass evidence.	Project status, mixed-domain held-out audit, hierarchical four-layer audit
Experimental	Broader AI-proposed graphs and capability expansion may generate inspectable artifacts only with explicit opt-in; they cannot be promoted as fabrication-ready.	Capability gating, AI generation
Unsupported	Arbitrary circuits and parts, mains/high-energy safety, RF power, unrestricted dense boards, unreviewed models, and automatic fabrication approval remain outside the proven envelope.	AI readiness, roadmap

The current V18 capability extension adds a version-isolated, catalog-backed path for low-voltage, high-input-impedance, multi-output analog threshold requirements. Its public replay case passes deterministic search, coupled value selection, simulation, physical lowering, and two clean installed-KiCad promotions without changing the frozen V6–V17 evaluator paths. This remains a bounded capability, not arbitrary analog synthesis. See the V18 specification.

V19 tested version-isolated causal-graph invariants, reusable topology operations, and a deterministic depth-four compositional repair beam. Its bounded Phase 6 public evaluation completed all 24 cases twice but produced no passes and did not preserve V18's admitted pass. V19 is therefore permanently retired and excluded from the v1 supported surface; V18 remains the latest publicly admitted capability. See the V19 retirement audit.

The next version-isolated successor adds deterministic analysis, simulation- model, and solver admission to the production open-topology lane. It derives analysis needs from behavior, resolves only authenticated bundled or reviewed overlay model records, records exact model/parameter/source/solver digests, and refuses before search or numerical evaluation when the combination is not reproducible. Its frozen V20 public evaluation preserved the V18 pass and advanced the selected model-availability leaf to a later topology blocker. It remains an experimental post-v1 capability and does not change the v1 support claim. See the specification and public evidence examples.

The frozen nonlinear/switching corpus provides an additional adversarial check: five behavior-only positive cases pass, while two unsafe stress cases and one unsupported dynamic envelope fail closed without a physical project.

The independently frozen mixed-domain corpus composes sensing, decisions, feedback, nonlinear transfer, switching power, and protection without naming architectures or parts. Eight feasible requirements reach deterministic installed-KiCad pass evidence; one contradictory requirement and four unsafe or unsupported requirements fail closed. See the completion audit.

A separately frozen physical-quality corpus proves a bounded next step: four behavior-only mixed-signal, amplifier, protected-control, and regulated-power requirements produce functional child sheets and deterministic four-layer boards. Each passes two clean local installed-KiCad runs with complete routing, controlled return-path evidence, filled planes, clean ERC/strict DRC, writer correctness, and zero normalized round-trip differences. This is not a claim that arbitrary dense boards are supported.

Run It In Under Ten Minutes

Released binaries require no Go installation. KiCad 10.0.3 is the supported v1 reference for installed-KiCad validation and promotion claims. KiCad 9 remains experimental for those claims. Source builds require Go 1.23 or newer; protoc is needed only when regenerating vendored protobuf bindings. See the v1 support contract.

git clone https://github.com/dshills/KiCadAI.git
cd KiCadAI
make public-demo

The demo detects standard macOS and Linux KiCad installations. If yours is in a different location, set KICADAI_KICAD_CLI, KICADAI_SYMBOLS_ROOT, and KICADAI_FOOTPRINTS_ROOT as shown in the demo instructions. The full raw search evidence can approach 1 GB; generated scratch output is kept in the ignored examples/.generated/ directory.

For a smaller first look without installed-KiCad proof, build the CLI and use the direct writers or checked-in educational examples:

make build
./bin/kicadai --help
./bin/kicadai version

Release downloads contain one platform binary, RELEASE_MANIFEST.json, and SHA256SUMS. Verify the checksum before installing, then place the binary on your PATH. A source checkout can install to ~/.local/bin with make install; set INSTALL_DIR to choose another location. The project publishes a CLI rather than a supported Go library, so versioned go install is not the v1 installation contract.

See educational circuits, the CLI reference, and the preserved detailed capability record.

AI Generation

Compile an ordinary behavior-first request without allowing the provider to choose topology, parts, nets, or layout:

kicadai \
  --file ./behavioral-request.txt \
  --provider openai \
  --ai-profile behavioral-intent-v1 \
  --output ./out/behavioral-request \
  intent compile

Only a ready result writes ./out/behavioral-request/.kicadai/behavioral-design-request.json. A clarification result writes a hash-bound follow-up template; an unsupported result writes stable capability-gap evidence and no executable design request. See Intent Planning for the follow-up and project-creation flow.

Run the recorded protected USB-C LED profile with KiCad-backed checks:

mkdir -p ./out
kicadai --prompt-file examples/ai/usb_c_led_indicator_protected/prompt.txt \
  --provider recorded \
  --provider-record examples/ai/usb_c_led_indicator_protected/recorded-response.json \
  --output ./out/ai_usb_c_led_protected --overwrite \
  --kicad-cli /path/to/kicad-cli \
  --require-kicad-roundtrip --strict-diffs \
  design create

For a live request, load OPENAI_API_KEY from the shell or a secret manager and replace the recorded-provider flags with --provider openai. Provider output is strict-decoded and remains untrusted until deterministic and KiCad-backed gates pass.

Agents that already have a valid generic-circuit-v1 graph can avoid a provider:

kicadai capability generation --json
kicadai --request ./graph.json circuit preflight
kicadai --symbols-root /path/to/kicad-symbols \
  --footprints-root /path/to/kicad-footprints \
  circuit create --request ./graph.json --output ./out/project --overwrite

For rejected generic graphs, run circuit repair-plan first. It selects an executable patch only when one safe correction is fully derived; otherwise it stops for review. See the CLI reference for the strict patch contract and evidence boundary.

See AI Generation for bounded and generic modes, live commands, evidence files, failure behavior, and current limits. AI agents should also follow the KiCadAI Agent Skill.

Reproduce Promotion Evidence

From an unmodified checkout, run:

make promotion-bundle
make held-out-promotion-bundle

The command builds the repository CLIs, resolves the version and stock libraries locked by toolchain/kicad-promotion.lock.json, bootstraps the checksum-pinned distribution only when needed, executes every required scenario twice, verifies all promotion gates and deterministic comparisons, and writes one content-addressed bundle below .tmp/clean-checkout-promotion/bundles/. No manually configured KiCad or library paths are required. The output directory must not already exist. The held-out target uses the same locked toolchain and verifier with the versioned five-scenario matrix for the two newly supported families, writing below .tmp/held-out-capability-promotion/.

Use bundle-path.txt to locate the bundle. Its included files and semantic promotion claims can be verified offline:

.tmp/clean-checkout-promotion/bin/kicadai-promotion verify \
  --bundle "$(cat .tmp/clean-checkout-promotion/bundle-path.txt)"

This is release-validation evidence for the supported corpus, not a claim that arbitrary designs or fabrication outputs are automatically qualified.

Schematic IR

The schematic design/layout IR is a strict JSON handoff for circuit intent, layout intent, and repair policy. It is not free-form natural language or KiCad S-expression syntax.

kicadai --request examples/schematic-ir/led_indicator.json schematic-ir validate
kicadai --request examples/schematic-ir/led_indicator.json schematic-ir normalize
kicadai --request examples/schematic-ir/led_indicator.json \
  --output ./out/ir_led --overwrite schematic-ir write

See Intent Planning And AI Workflow and the CLI Reference.

Documentation

Start with the documentation index.

Topic	Reference
Featured end-to-end proof	Protected Programmable Current Output
Current capabilities and limits	Project Status
v1 platforms, compatibility, and support boundary	Support Contract
Release history and safety reporting	Changelog, Security
Detailed implementation record	Capability Record
Educational generated schematics	Educational Examples
Commands and live IPC	CLI Reference
Natural-language provider workflow	AI Generation
Behavioral compilation, structured intent, and planning	Intent Planning
Circuit blocks	Circuit Blocks
Components, symbols, and footprints	Libraries And Components
Placement and routing	Placement And Routing
Validation, writer checks, and round-trip	Validation And Analysis
Clean-checkout release evidence	Validation And Analysis
Fabrication evidence	Fabrication
Direct KiCad file writers	KiCad File Writers
Tests, packages, and troubleshooting	Development Reference
Specifications, evidence, and audits	Specs Index
Priorities toward broader autonomy	Roadmap

Development

make test
make lint
make build
make release-reproducibility

See Development Reference for focused tests, coverage, protobuf maintenance, package boundaries, and troubleshooting.

License

KiCadAI is licensed under the MIT License. Vendored KiCad API materials under third_party/kicad/ retain their upstream licenses.