copperhead

Cursor for circuit boards.

copperhead is an open source AI agent that designs, documents, and verifies real PCBs from a prompt. On your files, in your repo, with KiCad's own checks as the gate.

Quick start
npm i -g @chouhan/copperhead

Proven on real copper.

Render of the Open Telegraph board, a 40 by 40 mm ESP32-S3 Morse key

Open Telegraph is a pocket-size Morse key: an ESP32-S3, one button, one RGB LED, and a battery, designed to live inside a 25 microamp sleep budget. It was built with this workflow, and every decision, every trap caught, and every file is public.

Read the build storyBrowse the repo

A loop, not a chatbot.

It looks a lot like pair programming, except the codebase is a circuit board.

  • Starts from the docs

    Every decision lives in the design docs, so the agent knows the whole design, not just the part in front of it.

  • Nothing starts without a spec

    The agent cannot touch a design file until a validated change proposal exists. The edit tools stay locked until it passes.

  • Nothing is done until the tools agree

    Every change is followed by ERC on the schematic and DRC on the board. Violations get read, fixed, and re-run.

  • Changes propagate

    Change one value and it carries across every file that references it. The boring, easy-to-get-wrong step is the one the agent is best at.

  • A product, not a chat log

    Schematic, board, gerbers and drill, DXF and STEP, renders, an orderable BOM, a firmware scaffold, and a bring-up plan. All on disk, in your repo.

  • Open because it has to be

    Apache-2.0, on an open stack. Everything it writes is plain markdown and JSON in your own repository. No proprietary formats, no lock-in.

    Built on KiCad and OpenSpec.

The draft layout is correct, not optimal, and says so itself.LAYOUT.md lists exactly what is solid and what a specialist should redo before fab. Non-optimal is acceptable. Unlabeled non-optimal is not.

Never ship a board your docs no longer describe.

copperhead is open source and free to use. Install once, point it at a KiCad repo, and run do.

npm i -g @chouhan/copperhead
export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY
cd your-kicad-repo
copperhead init
copperhead do "add a second RGB LED on an RTC-capable pin"

Requires Node 20+ and kicad-cli. The agent refuses to run on a dirty git tree, refuses edits without a validated proposal, and refuses changes that break your documented budgets. You will come to like being told no.