EDA KiCad Agent.

What it does

This project turns Claude Code into a PCB designer. The agent reads a contract that describes the board to be built, drives KiCad 9.x through its pcbnew SWIG Python API, and runs through an adversarial review loop until every contract item passes a pytest-based gate. The point is not to replace the human engineer but to take the rote, error-prone parts of EDA — placing components, laying out routes, running design-rule checks, generating manufacturing outputs — and let an agent handle them under tight constraints, with the human focused on high-level architecture and final review. The repository is publicly available so the toolchain, the agent rules, the contract format and the verification workflow are all visible to anyone who wants to reproduce the setup or fork it for a different EDA tool.

How it’s structured

The repository follows a strict contract-driven layout. CLAUDE.md is the agent’s primary routing directory and tells Claude how to behave. config.json carries the local machine paths and the Python interpreter configuration that lets the system Python talk to KiCad’s internal Python environment, which is the bridge that took the longest to get right. api_manifest.json is the verified surface of the KiCad 9.x SWIG API — generated programmatically rather than hand-typed, because the API changes often enough that hand-written documentation rots. .claude/ holds the subagent definitions and the slash commands the human invokes; agent_docs/ collects the system rules and PCB design skills the agents share; contracts/ holds the per-board completion criteria; scripts/ carries the toolchain verification utilities; and tests/ holds the pytest fixtures and per-design tests that act as the contract’s enforcement mechanism. Slash commands cover the workflow end-to-end: /new-board creates a contract and pytest stubs interactively, /review-board runs the reviewer/defender/referee pipeline, and /research-api delegates a read-only API exploration to a dedicated subagent.

How it works

A design starts with /new-board, which interactively constructs a contract and a matching set of pytest stubs. The agent then drives KiCad through the verified pcbnew API surface — the verified surface itself is captured in api_manifest.json, regenerated by discover_api.py against the installed KiCad version so the agent never works against stale docs.

The agent completes the contract item by item, and keeps the contract checklist in front of it the entire time so that scope creep is impossible. The output of a worked example — the blue_pill development board built end-to-end by the agent against its contract — is below, both as a 3D render and as the 2D top-side layout that the manufacturing drawings derive from.

Once the agent believes the design is finished, /review-board triggers the adversarial review pipeline: a Reviewer agent looks for anything that violates the contract or established PCB practice, a Defender agent argues from the design’s point of view and either fixes the finding or pushes back with reasoning, and a Referee agent decides who is right and updates the design accordingly. DRC and toolchain verification are non-negotiable gates — a failure there blocks the contract from being marked complete, regardless of how much of the design looks right, and the agent has no path to rationalise around the failure because the gate is enforced by pytest, not by self-report. Throughout, the agent prefers to validate the actual API surface programmatically rather than trust documentation, because the SWIG bindings change often and stale docs are how an agent ends up in a long, confident, completely wrong refactor.

What I learned

The biggest insight was how much agent reliability depends on choosing the right gates. A pytest contract in the loop, a verified API manifest, a hard DRC check — those are the things that turn a generative agent from a confident hallucination machine into something that can actually produce a manufacturable board. The adversarial Reviewer/Defender/Referee pipeline taught me that giving the agent two adversarial roles and a separate arbiter is dramatically more effective than asking the same agent to self-correct: the structural separation forces real disagreement, and the referee makes the final call cleanly. I also learned how subtle the bridge between system Python and KiCad’s internal Python actually is on Windows — the path configuration and interpreter choice are the kind of details that trip every new contributor, which is exactly why the verification script in scripts/ exists, and why the toolchain check is the first thing the agent does on every session start.