Copperhead: Accelerating Hardware to the Speed of Software

Copperhead is an open-source AI-driven engineering ecosystem designed to empower hardware teams to design, validate, and manufacture circuit boards with the agility of software development. Think of it as ~~a basic script~~ Cursor for circuit boards.

🛠️ The AI-Powered Workflow in Action

Copperhead doesn't just suggest changes; it executes them. Below is a simulation of the agent adding a USB-C power input to a project:

# Installation
$ npm i -g copperhead

# Project Initialization
$ copperhead init

# Requesting a change
$ add a USB-C power input to the key

⚡ Execution Trace

The agent follows a rigorous verification loop:

Analysis: Reads docs/POWER.md $\rightarrow$ identifies missing VBUS, CC1, and CC2 nets.
Validation: Validates the change against existing constraints.
Execution:
- Edits hardware/open-key.kicad_sch (Adds USB-C receptacle and $5.1\text{k}\Omega$ CC pulldowns).
- Updates docs/POWER.md (Sets VBUS budget to $5\text{V}$ at $1.5\text{A}$ ).
- Verification: Runs kicad-cli for Electrical Rule Check (ERC).
- Audit: Records the decision in DECISIONS.md and CHANGELOG.md.

Result: $\text{ERC Clean} \rightarrow \text{Committed } \texttt{3f2c9a1}$ .

🚀 How It Works: The 8-Stage Pipeline

Copperhead operates through a sequence of agent runs. Each stage must produce a verified artifact on disk before the next can begin.

Stage Detail Table

Stage	Artifact	Gate/Requirement
01 Spec	`docs/SPEC.md`	Budget section must be fully populated.
02 Architecture	`docs/SUBSYSTEMS.md`	Detailed reasoning for every subsystem.
03 Parts	`docs/BOM.md`	Part numbers must be verified against datasheets.
04 Schematic	`design.kicad_sch`	Symbols placed, docs aligned, ERC clean.
05 Layout	`design.kicad_pcb`	Footprints placed, DRC clean.
06 Outputs	Gerbers/Drill/STEP	Files must physically exist on disk.
07 Firmware	`firmware/`	Source code and `pins.h` aligned with pinout.
08 Dev Plan	`docs/DEVPLAN.md`	Written bring-up and testing strategy.

💰 Pricing & Tiers

The core CLI is Apache-2.0 and will always be free. You pay for hosting, collaboration, and enterprise governance.

Plan Comparison

Tier	Price	Key Features
CLI (Community)	Free	Local runs, BYO API key (Claude/GPT-5), Git repo integration, Markdown/JSON/KiCad output.
Cloud	$49/user/mo	Hosted runs, Web viewer (live schematic/board render), Private repos, 200 managed credits/seat.
Team	$49/user/mo +$ 199/mo	Everything in Cloud + CI bot (PR status checks), Shared constraint libraries, SSO/SAML.
Enterprise	Custom Annual	Self-hosted/VPC, Altium support, RBAC, Full audit trails, Flat annual license.

[!IMPORTANT] Free for open hardware repositories.

🧠 Philosophy & Technical Constraints

Copperhead is designed to prevent the "expensive mistake." In hardware, a mismatch between a schematic and a power budget can cost $\$ 5,000 $to$ $50,000 $and$ 6\text{--}8$ weeks of delay.

Core Guardrails

Git Integrity: Refuses to run on a "dirty" git tree.
Proposal First: No design file is edited without a validated change proposal.
Constraint Enforcement: Refuses changes that violate documented budgets or constraints (citing the specific line of documentation).
Fact-Based: Never suggests a part number that cannot be justified by a datasheet.
Surgical Edits: Modifies KiCad s-expressions directly. This ensures diffs remain small and reviewable, avoiding the entire file being regenerated.

System Requirements

Node 20+
KiCad (with kicad-cli in the system path)
Model API Key (e.g., Anthropic or OpenAI)

🏁 Getting Started

Install the CLI
Describe your board in brief.md
Run copperhead create (for new designs) or copperhead init (for existing ones)

"Never ship a board your docs no longer describe."