# copperhead

> copperhead is an open source (Apache-2.0) AI agent for hardware design — "Cursor for circuit boards." Given a plain-English change request or a product brief, it edits real KiCad files (.kicad_sch, .kicad_pcb) in your own git repository, propagates the change into every document that references it (pinout, BOM, subsystem docs, firmware scaffold), and verifies its own work by running `kicad-cli` ERC and DRC until the checks pass. It leaves artifacts on disk, not advice in a chat window.

Built by Animesh Chouhan (Chouhan Industries). Proven on Open Telegraph, a shipping 40×40 mm ESP32-S3 Morse key with a 25 µA deep-sleep budget: building that board produced copperhead, and redesigning the board through copperhead proved it.

Two invariants make the loop trustworthy:

1. Nothing starts without a spec. The edit tools are structurally locked until a validated change proposal exists, so every edit is traceable to a documented intent.
2. Nothing is "done" until the tools agree. Every file mutation is followed by an ERC/DRC run before the agent reports success, inside a git snapshot that rolls back if verification fails.

Spec-gated in, verification-gated out: the design cannot drift from its requirements, because drift is a build failure.

Key facts:

- Two ways to use it: iterate on an existing KiCad repository (`copperhead init`, then `copperhead do "..."` — the main case), or run the full pipeline from a written brief (`copperhead create --brief brief.md`) to get a spec, architecture, justified part selection, ERC-clean schematic, DRC-clean draft layout, gerbers, renders, an orderable BOM, and a bring-up plan.
- Install: `npm i -g copperhead`. Requires Node 20+, KiCad with `kicad-cli` on the path, and your own model API key (model-agnostic: Claude and GPT-5 both tested; set ANTHROPIC_API_KEY or OPENAI_API_KEY).
- Cost: roughly $0.10–$1.00 in model tokens per change request, 5–10× that for a full `create` run; billed by your model provider. copperhead itself is free. No hosted version today.
- Everything it writes is plain markdown, JSON, and KiCad source — no proprietary format, no editor to move into. Edits are surgical s-expression changes, so diffs stay small and untouched file regions stay byte-identical.
- It does not replace a hardware engineer: draft layouts are correct rather than optimal, and LAYOUT.md states exactly what a specialist should redo before fabrication. It refuses to run on a dirty git tree, refuses edits without a validated proposal, refuses changes that break documented constraints, and never invents unjustifiable part numbers.
- Data stays local: the agent runs on your machine, stores nothing on a server, and only sends design context in the model API call itself. Run transcripts live in .copperhead/runs/ with secrets redacted.
- KiCad only; no proprietary EDA formats are supported or planned.

## Docs

- [Documentation](https://docs.copperhead.sh/): full copperhead documentation (Astro Starlight site)
- [FAQ](https://copperhead.sh/blog/faq/): cost, what it refuses to do, whether it replaces an engineer, and where design data goes
- [GitHub repository](https://github.com/chouhanindustries/copperhead): source code, issues, and the best place to ask questions

## Blog

- [Meet copperhead](https://copperhead.sh/blog/meet-copperhead/): product introduction — what the agent is and the two ways to use it
- [Drift is a build failure](https://copperhead.sh/blog/drift-is-a-build-failure/): the problem — a board is a dozen documents pretending to be one thing, and drift ships to fabrication
- [Spec-gated in, verification-gated out](https://copperhead.sh/blog/spec-gated-in-verification-gated-out/): engineering — the two invariants and the six-step loop between them
- [copperhead: Cursor for circuit boards](https://copperhead.sh/blog/antler-crackathon/): the Antler Crackathon submission — problem, product, competitive field, market, and go-to-market

## Optional

- [Pitch deck (PDF)](https://copperhead.sh/Copperhead.pdf): the Crackathon pitch deck
- [Open Telegraph](https://github.com/animesh-chouhan/open-telegraph): the open source proof board (CERN-OHL-S v2.0)
- [Building open hardware with Claude](https://chouhan.ai/building-with-claude): the longer story of how Open Telegraph and copperhead came together
- [KiCad](https://www.kicad.org/): the open source ECAD tool copperhead works on