Copperhead Hands-On: An AI Agent That Verifies Its Own PCBs

Hardware just got its coding-agent moment. Copperhead hit Show HN today — an open-source (Apache-2.0) agent that reads and edits real KiCad files the way a coding agent edits a codebase, then refuses to commit anything until kicad-cli ERC and DRC pass. I installed it, ran its whole verification pipeline on a real board, and the interesting part isn't the LLM. It's what the agent refuses to do without.

Setup for this experiment: a 2-core Debian 13 VM with 2 GB of RAM, no GPU, and no root access. If the pipeline runs there, it runs anywhere.

Install and fail-fast design

npm install -g copperhead pulled 48 packages and gave me v0.10.0. The first thing I ran was copperhead check — and it immediately told me why it won't run, in plain prose:

$ copperhead check
kicad-cli not found on PATH
why it failed: copperhead verifies every mutation with kicad-cli ERC/DRC;
without it no edit can be checked, so no run can start

That's the thesis in one error message. This is not an agent that will hallucinate a netlist and call it done — no verifier, no run. Contrast with the average coding agent that will happily report success on a build it never ran.

KiCad without root: 20 .deb files and an LD_LIBRARY_PATH

No sudo in this VM, so I extracted Debian's KiCad 9.0.2 package (41.4 MB) and its dependency chain into /tmp with dpkg-deb -x. The final chain was ~20 packages: wxWidgets (split into base and GTK3 packages), GTK3, protobuf, OpenCASCADE (five modules for the 3D path), OpenEXR, FreeImage, libgit2, mbedtls, and more — all resolved by iterating ldd | grep "not found". Then:

export LD_LIBRARY_PATH=/tmp/kicad-root/usr/lib/x86_64-linux-gnu
export COPPERHEAD_KICAD_CLI=/tmp/kicad-root/usr/bin/kicad-cli
kicad-cli version        # → 9.0.2

Both verification engines came up on a real fixture board (open-key, from Copperhead's test suite):

$ kicad-cli sch erc open-key.kicad_sch -o erc.rpt
Found 0 violations
$ kicad-cli pcb drc open-key.kicad_pcb -o drc.rpt
** Found 0 DRC violations **
** Found 0 unconnected pads **

The check pipeline: ERC, DRC, drift — and a legibility score

With kicad-cli wired in, copperhead init scaffolded five design docs (PINOUT.md, SUBSYSTEMS.md, LAYOUT.md, DECISIONS.md, CHANGELOG.md) from the schematic. Then the real check:

$ copperhead check
ERC ✓
DRC ✓
drift ✓
legibility: 1 error, 5 advisory finding(s) across 1 sheet(s):
  1. [error] unlabeled-group @ / (120, 102) refs: Keyer — group caption
     "Keyer" names nothing in SUBSYSTEMS.md or BOM.md
  ...
legibility score: 40/100

This is the part nobody else is doing. ERC and DRC are table stakes — KiCad ships them. Copperhead's legibility gate lints the schematic against its own docs: a block captioned "Keyer" that appears nowhere in SUBSYSTEMS.md is an error, capping the score below the known-good floor of 85. Labels rotated 90° where a horizontal one would collide with nothing are advisories, as is a sheet that's only 6% utilized.

That matters because an agent can satisfy ERC and still produce a schematic no human can review. Copperhead treats the human reader as a verification target too. That's a genuinely new gate, and it's structural, not cosmetic.

graph TD
    A[Change request] --> B{OpenSpec proposal validates?}
    B -->|no| A
    B -->|yes| C[Anchored edits to .kicad_sch / .kicad_pcb + docs]
    C --> D[kicad-cli ERC]
    D --> E{Board changed?}
    E -->|yes| F[kicad-cli DRC]
    E -->|no| G{Findings?}
    F --> G
    G -->|violations| H[Repair or roll back]
    H --> D
    G -->|clean| I[DECISIONS.md + CHANGELOG + run summary]
            

Test suite receipts: 910 → 931 passing

I ran the full vitest suite twice. Without kicad-cli: 910 passed, 28 failed. With userland KiCad 9.0.2: 931 passed, 7 failed. Every remaining failure is an environment artifact, not a code defect — four need the hardcoded /usr/share/kicad schema path I can't write to without root, two are byte-identical reference-board pins generated on the exact KiCad the maintainers pin, and one expects check to fail on a broken kicad-cli where my half-wired binary reports ok. That last one is arguably my fault, not Copperhead's.

The honest caveat: I could not run the LLM-driven path (copperhead create, do) — it needs a model backend I don't have in this VM, and check/demo --tour/init deliberately never call one. So this review covers the deterministic spine: the gate, the verifier, the doc memory. The spine is the part that has to work; if it doesn't, the agent is theater.

Bottom line

Copperhead 0.10 is early — the README says so, the spec is still moving — but the architecture is the right one: an OpenSpec-gated edit loop where every mutation is verified by ERC/DRC before commit, decisions live in markdown as agent memory, and a legibility gate makes the output reviewable by humans, not just correct by simulation. The whole thing is CI for circuit boards, and the deterministic spine held up on a 2 GB VM with zero root. Hardware engineering is the last place "trust me, it compiles" survived. It just stopped surviving.