This KiCad Agent Hides Its Own Edit Tools From the Model
TL;DR
On September 8 a Show HN called copperhead took 213 points and 85 comments with a four-word pitch: Cursor for circuit boards. It is an Apache-2.0 CLI agent that reads and writes real KiCad files, the s-expression .kicad_sch and .kicad_pcb text your editor already opens, then runs ERC and DRC through kicad-cli until the checks pass. The part worth stealing has nothing to do with copper. The agent's file-editing tools do not exist until a validated change proposal exists, and every mutation runs inside a git snapshot that reverts on a failed check. The part the launch page does not lead with: the project's own maturity note says that loop is "implemented, not yet proven."
What it actually is
Two commands carry the product. copperhead do "add reverse-polarity protection on VIN" operates on an existing KiCad repo the way a coding agent operates on a codebase. copperhead create --brief brief.md runs a natural-language brief through eight ordered stages: spec, architecture, parts, schematic, layout, fab outputs, firmware scaffold, dev plan. Each stage is its own agent run, each has to leave its artifact on disk before the next one starts, and each lands as its own commit.
A third command matters more than either. copperhead check runs ERC, DRC, doc-drift detection and spec validation with zero LLM calls, which makes it CI-safe and free. The deterministic half of this tool costs nothing to run and does not need a credential.
Requirements are boringly concrete: Node 20 or newer, KiCad 8 or newer with kicad-cli on PATH, and one model backend. That backend can be an API key, or a saved login from Claude Code, Codex CLI, or the Cursor Agent CLI. Point compat: at any OpenAI-compatible endpoint and a local Ollama works too.
Two gates, and why they are the story
The README states the design as two invariants, and they are the reason to care about a PCB tool even if you will never open KiCad:
Nothing starts without a spec. The agent cannot touch a KiCad file until a validated change proposal exists; the edit tools are structurally unavailable until it does.
Nothing is "done" until the tools agree. Every file mutation is followed by an ERC/DRC run before the agent reports success.
Read that first one again. It is not a prompt asking the model to please write a plan first. The tool schema the model sees does not contain an edit function until the proposal validates. It is the difference between a sign on the knife drawer that says "check the order ticket first" and a drawer that physically will not open until the ticket prints.
The MCP server is the strongest argument
Coding agents are already pointed at KiCad repos through generic file tools, which means any host agent can rewrite a .kicad_sch with no spec gate, no verification and no rollback. Copperhead's answer is copperhead mcp, an experimental Model Context Protocol server that exposes exactly five tools: copperhead_check, copperhead_do, copperhead_sync, copperhead_init, copperhead_doctor. Nothing finer.
There is no file-edit tool on that surface. No raw KiCad tool. No partial-loop tool. A host agent cannot skip spec-gating or verification by any sequence of calls, because the calls that would let it do that were never offered. That is a generalizable pattern for anyone shipping agent tooling this year: if a guardrail matters, do not describe it in a system prompt, delete the primitive that routes around it.
What it refuses to be
- Not an autorouter. Routing stays human or delegated. Copperhead aims to produce the DRC-clean draft that layout tools optimize from.
- Not a new editor. Your KiCad install stays the editor, git stays the safety net, and the outputs are plain markdown, JSON and KiCad files in your own repo.
- Not the engineer of record. The docs are explicit that a human signs off and that the agent never claims a design is fab-ready beyond "ERC/DRC clean."
The export bom command is a good tell for how much of this is real engineering versus model output. It turns a drift-checked docs/BOM.md into a supplier file for JLCPCB, DigiKey or Mouser, deterministically and offline, and it refuses to export while the BOM disagrees with the schematic. It also over-orders passives on purpose: quantity is rounded up by a spares percentage, then floored at two extra per line for resistors, capacitors and inductors, because losing a couple of 0402s to tweezers is the normal outcome, not the exception. Somebody who has actually built a board wrote that rule.
The numbers, and the gap between them
The repository was created on July 18, 2026. Latest release is v0.10.0, published August 26. Ninety open issues and ninety-one open pull requests sit on a seven-week-old project with sixteen contributors, which is either healthy velocity or a review backlog, depending on how charitable you feel before coffee.
The honest part
Copperhead's README contains a "Maturity" section that most launches would have quietly omitted, and it splits the project into three honest buckets.
The deterministic half is done. init, check, the s-expression reader, drift detection and fab export are LLM-free and covered by an offline test suite against a real KiCad fixture, green in CI. The safety half is done: every mutation runs inside a git snapshot and rolls back on failed verification.
The agent half is the open question. In the project's words, the loop behind do, sync --resolve and create is complete and structurally gated, "but its acceptance tests need a live model and have not been observed passing end to end."
Its companion benchmark tells the same story. copperbench scores model agents on verified hardware edits using electrical verification as the oracle and reporting cost next to pass rate, with one rule that deserves wider adoption: grading never calls a model, so every published score is recomputable offline by someone who does not trust the publisher. It ships the standard, JSON schemas, four real open-hardware fixtures, two worked tasks, a scorer, and two provider-free modes that prove the suite discriminates before a credential is spent. What it does not ship is results. The research page says it plainly: no model matrix has been run yet. The scoreboard is built and nobody has played a game on it.
The hardware engineers pushed back
The Show HN thread did not roll over. The recurring objection is that PCB layout is combinatorially brutal, that autorouters have underdelivered for decades, and that the distance between a competent hardware engineer and current model output is wider than the equivalent gap in code, because standards compliance and manufacturability are learned over years and are not visible in a netlist. Commenters pointed at Flux and Quilter as prior attempts at adjacent problems.
That critique lands mostly on autorouting, which copperhead explicitly declines to do. It lands less on the actual claim, which is narrower and more defensible: propagate a change across every artifact that references it, then ask KiCad whether the result is still legal. The project's framing post makes the case with a scenario any hardware person recognizes, a pullup removed on purpose to protect a microamp-scale sleep budget, silently re-added six weeks later by a reviewer who never saw the reason. Software gets a compiler error for that class of mistake. Hardware gets a respin.
One asterisk on the reference board
The landing page points at Open Telegraph, a pocket-size ESP32-S3 Morse key, as proof the workflow produces real copper. The repo is genuine: a hierarchical KiCad project with power, USB, MCU, IO and header sheets and a half-megabyte .kicad_pcb, released under CERN-OHL-S v2.0, spec'd at roughly 25 microamps in deep sleep on a 250 mAh cell.
It also predates copperhead. Open Telegraph's first commit landed July 10, 2026; the copperhead repository was created eight days later, and Open Telegraph's own README says the board was designed with Claude Code. That is a reasonable origin story rather than a contradiction, the tool is the productized version of a workflow that clearly worked once, but it is not independent evidence that the packaged agent reproduces it. The firmware directory is still an empty placeholder.
Should you run it
If you keep hardware in git and have ever shipped a board where the BOM and the schematic disagreed, copperhead check is worth ten minutes. It is free, offline, calls no model, and either finds drift or does not. That is a real answer either way.
The agentic half is early software with a good architecture, a copper-clean rollback story, and a maintainer who documents what is unproven. Run it on a branch, on a board you do not care about, and treat the output as a draft that still needs an engineer. Which, to be fair, is exactly what the README already told you.
Key Takeaways
- The gate is structural, not prompted. Copperhead's edit tools are unavailable to the model until a validated change proposal exists, and every mutation is followed by an ERC/DRC run inside a git snapshot that reverts on failure.
- Its MCP server is the pattern to copy. Five outcome-level tools, no file-edit primitive, so a host agent cannot route around the gates by any call sequence.
- The deterministic half is the usable half today.
init,check, drift detection and BOM export are LLM-free, CI-safe and covered by an offline suite against a real KiCad fixture. - The agent loop is unproven by the project's own admission. Acceptance tests need a live model and have not been observed passing end to end, and copperbench has run no model matrix.
- Adoption is early. 213 Hacker News points and 176 stars against 513 npm installs in 30 days, 16 contributors, and 91 open pull requests on a repo created July 18, 2026.
- The economics are the pitch. A software regression costs a redeploy; a schematic regression costs a fab run and the wait to discover the next one. Machine-checkable design docs are the cheapest defense available.
Sources: copperhead on GitHub, Show HN: Copperhead, Cursor for circuit boards, copperhead.sh, copperhead documentation, copperbench, copperhead research, Drift is a build failure, copperhead on npm, Open Telegraph