# copperhead

> An open-source AI agent that designs, documents, and verifies printed circuit boards by working directly on KiCad files with spec-gated edits and ERC/DRC verification.

Copperhead is an open-source AI engineering platform described on its homepage as "Cursor for circuit boards." Built by Chouhan Industries and released under Apache-2.0, it helps hardware teams design, verify, and ship PCBs by operating directly on KiCad repositories — reading and editing real `.kicad_sch` and `.kicad_pcb` files, maintaining markdown design docs as memory, and running KiCad's own ERC/DRC checks until they pass. The GitHub repository lists the latest release as v0.10.0, published in August 2026.

## What It Is

Copperhead is an AI product-development agent for hardware engineering. Given a natural-language product brief or a change request, it runs a structured pipeline — spec, architecture, part selection, schematic, layout, gerbers, firmware scaffold, and dev plan — and produces a complete, manufacturable design package. Unlike generic coding agents pointed at KiCad files, Copperhead enforces two hard invariants: nothing touches a KiCad file until a validated change proposal exists, and nothing is marked done until ERC/DRC checks pass. The tool is installed as a global npm package (`npm i -g copperhead`) and requires Node.js ≥ 20 and KiCad ≥ 8 with `kicad-cli` on PATH.

## How the Eight-Stage Pipeline Works

The `copperhead create` command runs a fixed sequence of eight stages, each producing a gated artifact on disk before the next stage starts:

- **Spec** → `docs/SPEC.md` (budgets section filled in)
- **Architecture** → `docs/SUBSYSTEMS.md` (reasoning under every subsystem)
- **Parts** → `docs/BOM.md` (part numbers verified against datasheets)
- **Schematic** → `design.kicad_sch` (symbols placed, ERC clean)
- **Layout** → `design.kicad_pcb` (footprints on board, DRC clean)
- **Outputs** → gerbers, drill files, STEP
- **Firmware** → `firmware/` scaffold with `pins.h`
- **Dev plan** → `docs/DEVPLAN.md` (bring-up and test plan)

If a gate fails, the run stops there. Every stage commits one artifact, so the design history is fully traceable. The `copperhead do "<change>"` command operates on an existing KiCad repo the same way a coding agent operates on a codebase — surgical edits to the s-expression source, propagated across all referencing docs, then verified.

## Model Backends and Integration

Copperhead is model-agnostic. It supports Claude (via `ANTHROPIC_API_KEY`), GPT-5 (via `OPENAI_API_KEY`), Claude Code (via saved OAuth token), Cursor Agent CLI (via saved login), Codex CLI, and any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, local Ollama) via `COPPERHEAD_BASE_URL`. Users can bring their own API key or, on paid cloud tiers, use managed inference. An experimental MCP server (`copperhead mcp`) exposes five opaque, outcome-level tools to MCP hosts — `copperhead_check`, `copperhead_do`, `copperhead_sync`, `copperhead_init`, `copperhead_doctor` — with no raw file-edit tool available, so host agents cannot bypass spec-gating.

## Open-Source Deployment Model

The entire agent core, prompts, and tools are public under Apache-2.0. The project describes itself as "open core": the CLI is free and always will be, funded by grants rather than hosted revenue. Paid tiers add hosting, collaboration, and governance on top of files users already own in their own git repos. All output is plain markdown, JSON, and KiCad files — no proprietary formats, no lock-in. The project states that canceling a paid plan drops users back to the free CLI working on the same files. Open hardware repos released under CERN-OHL-S or an OSHWA-certified license qualify for the Cloud tier at no cost, per the pricing page.

## Update: v0.10.0

The GitHub repository shows v0.10.0 as the latest release, published 2026-08-26, with the repository last updated 2026-09-11. The README describes the current maturity honestly: `init` and `check`/`verify` are deterministic, LLM-free, and covered by an offline test suite against a real KiCad fixture; the agent loop (`do`, `sync --resolve`, `create`) is complete and structurally gated but described as "implemented, not yet proven" end-to-end with a live model. Every mutation runs inside a git snapshot and rolls back if verification fails, so the worst case is a no-op commit rather than a corrupted schematic. The project self-describes its status as "early" with the surface expected to move before 1.0.

## Features
- Full pipeline from natural-language brief to gerbers, firmware, and dev plan
- Operates on existing KiCad repositories with surgical s-expression edits
- Spec-gated edits: KiCad files cannot be touched until a validated change proposal exists
- ERC/DRC verification after every file mutation via kicad-cli
- Eight-stage gated pipeline: spec, architecture, parts, schematic, layout, outputs, firmware, dev plan
- Drift detection: docs and schematic kept in sync, drift treated as a build failure
- Model-agnostic: Claude, GPT-5, Claude Code, Cursor Agent, Codex, OpenAI-compatible endpoints
- Bring-your-own API key or managed inference
- Supplier-ready BOM export for JLCPCB, DigiKey, and Mouser
- Experimental MCP server with five opaque outcome-level tools
- Git-snapshotted mutations with automatic rollback on verification failure
- Decision log and changelog written automatically after every real decision
- copperhead check: LLM-free ERC/DRC and doc-drift CI check
- copperhead init: idempotent doc scaffolding from existing schematic
- Interactive agent shell (REPL mode)
- Plain markdown, JSON, and KiCad output with no proprietary formats

## Integrations
KiCad, kicad-cli, Claude (Anthropic API), Claude Code (OAuth), Cursor Agent CLI, OpenAI Codex CLI, GPT-5, Groq, OpenRouter, Gemini, Ollama, JLCPCB, DigiKey, Mouser, OpenSpec, Git, npm, MCP (Model Context Protocol)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source, Free tier available

## Version
v0.10.0

## Links
- Website: https://copperhead.sh
- Documentation: https://docs.copperhead.sh
- Repository: https://github.com/copperheadhq/copperhead
- EveryDev.ai: https://www.everydev.ai/tools/copperhead