Getting started
Welcome to copperhead
Cursor for circuit boards. An AI agent that designs, documents, and validates real PCBs from a prompt, working directly on existing KiCad repositories.
copperhead is an open-source CLI agent for KiCad. Give it a product brief or a one-line change request and it writes a change proposal, edits the .kicad_sch and .kicad_pcb files in your repository, runs ERC and DRC through kicad-cli until they pass, and records what it decided and why in your design docs.
Your KiCad install stays the editor, git stays the safety net, and a human still signs off. It is not an autorouter and it does not introduce a new file format.
Jump right in
Section titled “Jump right in”Keep exploring
Section titled “Keep exploring”copperhead basics
Section titled “copperhead basics”IntroductionWhat copperhead is, how the agent works, and what it deliberately is not.The agent loopWhat one run actually does, from reading the docs to writing down why.GuardrailsThe two invariants that gate edits in and verification out, and the ledger that keeps docs honest.Docs as memoryThe markdown in your repo is the agent's memory, its output, and the thing verification protects.
Get things done
Section titled “Get things done”Design from a briefFrom a markdown product brief to a full, verified design package.Edit an existing boardOne natural-language change request, one verified, committed change.Verify and syncKeep the KiCad files, the design docs, and the constraint registry agreeing, in CI and at commit time.Simple demoRun the create pipeline end to end against the USB-C power breakout brief.
Reference
Section titled “Reference”CLIEvery command, flag, and exit code.ConfigurationConfig file keys, environment variables, model selection, and the files copperhead writes.How schematics are draftedThe deterministic drafting engine and how a netlist intent becomes a placed, readable sheet.The schematic intent fileThe full specification of schematic.intent.json, the drafting engine's only input.Schematic legibility rulesThe drafting standard for generated schematics and the checks that enforce it.Technical specArchitecture, tool schemas, safety rails, and the binary acceptance criteria.