copperheadGitHub

Cursor for circuit boards.

An AI agent that designs, documents, and validates real PCBs from a prompt.

Quick start
npm i -g copperhead
export ANTHROPIC_API_KEY=<api-key>
copperhead create --brief brief.md

Proven on real copper.

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

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

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, describe the board you want in a short brief.md, and run create.

npm i -g copperhead
export ANTHROPIC_API_KEY=<api-key>
copperhead create --brief brief.md
brief.md
# Pocket Morse key

A pocket-size Morse key that types over Bluetooth as a standard keyboard.

- ESP32-S3, BLE HID
- Li-Po cell, USB-C charging
- Sleep current budget: 25 µA
- 3.5 mm jack for an external paddle

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.