Reference

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.

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

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.

V21 builds on that admitted V20 boundary with generic causal-topology completion and bounded repair. It derives structural obligations from behavior, terminal contracts, and the current graph; applies only canonical generic graph operations; and preserves exact V20 analysis/model/solver admission before any new topology work. The September 6 review found unsound structural certificates, evidence-hash errors, and bound-enforcement defects in its original evaluator. These are corrected in maintenance revision 1. The original 24-case evaluation is retained as historical evidence, not validation of the repaired code or proof of its previously claimed six-case advancement. A separate frozen maintenance run completed all 24 public cases twice and passed its advancement and preservation gates: four selected cases across four domains advance to a later behavioral-evidence blocker, all 16 unselected raw case objects remain byte-identical to V20, and the V18 pass and safety result are preserved. Outcomes are 1 pass, 6 unsupported, 1 unsafe, and 16 exhausted; there are no additional complete circuit passes. V21 remains experimental and does not change the v1 support claim. See the review and corrections and corrected V21 maintenance audit.

The subsequent V22 post-topology electrical-repair experiment completed all 24 public cases twice. Compact first-failed-gate diagnostics identified the four selected candidates' electrical blockers, but bounded generic control-terminal rebinding produced no additional complete pass. All case outcomes, full replay hashes, and gate records remain identical to corrected V21; the existing pass again clears both installed-KiCad promotions. Independent development fixtures passed, but do not count as corpus improvement. V22 remains experimental and does not expand v1. See the root-cause report, negative evaluation result, and timing/evidence-size observations.

V23 then isolated a generic stale op-amp clamp defect and added a bounded, version-isolated solver correction. Its separate frozen evaluation completed all 24 cases twice on September 10: 1 pass, 6 unsupported, 1 unsafe, and 16 exhausted, with no additional complete passes. All case outcomes, full synthesis replay hashes, and gate records match V22; the existing KiCad-backed pass and safety outcomes are preserved. The complete retained evidence is authenticated, but the capability-improvement criterion was not met. V23 remains experimental and does not expand v1. See the final results and validation.

The subsequent practical sensor/controller-board goal remains unachieved. Its original live baseline produced 0/8 complete boards. The renewed completion attempt stopped before paid evaluation: six human-authored development probes failed before electrical synthesis or native generation, with unresolved requirement/provider qualification and interface-encoding gaps. No new API requests or complete-board passes were claimed. The full short software suite passed, but that does not establish practical board readiness. See the negative readiness publication for retained clauses, evidence, source-bound checks and local-review limits.

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

Maintained source (newer than v1.0.1)

The schematic, capability explore, review, doctor, conformance, repro, adapter, and family workflows below were added after the v1.0.1 tag. Build the maintained source to use them; downloading v1.0.1 does not provide them. For a small schematic-first workflow that needs no API key, try:

make build
bin/kicadai --output ./out/divider schematic example divider
bin/kicadai --output ./out/my-session schematic new

Open the generated report.html for component explanations, calculations and explicit check statuses. Add --require-erc before schematic to require native KiCad validation. See the guided schematic workflow. This produces a schematic candidate, not a board or fabrication approval.

Discover supported workflows with bin/kicadai capability explore. For bounded solver comparisons and compact failure replay, see numerical conformance and reproduction.

For an existing schematic, use review schematic; use doctor to diagnose local dependencies. See project review and local integrations for catalog self-test kits and the versioned NetForm adapter.

Published v1.0.1 binary

After installing and verifying v1.0.1, use its supported direct-file LED example instead. Put global flags before the command, and create the parent output directory first:

mkdir -p ./out
kicadai --output ./out/led_demo generate-led-demo
# Optional minimal PCB output (not a placed/routed or manufacturing-ready board):
kicadai --output ./out/led_with_pcb --with-pcb generate-led-demo

The project files use the output directory's basename unless --name is set. Without --with-pcb, only a schematic and project are generated. These offline examples need neither an API key nor installed KiCad. Native ERC/DRC checks do require KiCad. These file-writer demos can report ERC/DRC findings; they are not clean-check acceptance examples (see check fixtures). v1.0.1 silently ignores trailing flags such as generate-led-demo --output DIR; maintained source rejects them before writing.

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. Supported source builds use the exact patched Go release in .go-version (currently 1.26.10) through Make; protoc is needed only when regenerating vendored protobuf bindings. See the v1 support contract and v1.0.1 installation guide. v1.0.1 is a security maintenance release; existing v1.0.0 users should replace their binary, not merely update system Go.

git clone --branch main 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 assets contain four platform binaries, RELEASE_MANIFEST.json, and SHA256SUMS. Download the matching binary and verify its checksum before installing it 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.

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.