copperhead CLI
A CLI agent for circuit boards: edits KiCad schematics and boards from a description and checks itself with ERC and DRC
- 667 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The agent edits project files and records changes in git
- It runs kicad-cli and calls an external model with your key or a saved login
- ERC and DRC do not replace an engineer's sign-off, so review the result before ordering boards
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/copperheadDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent edits project files and records changes in git
- It runs kicad-cli and calls an external model with your key or a saved login
- ERC and DRC do not replace an engineer's sign-off, so review the result before ordering boards
This is third-party code. Review the repository files before installing.
What it does
copperhead is an AI agent for electronics design that works directly on a KiCad repository, the way a coding agent works on code. The copperhead do command takes a plain-language change, reads the real .kicad_sch and .kicad_pcb files, edits them and keeps the project's markdown docs next to them as memory. The copperhead create command goes further: from a text brief it builds a spec, an architecture, part selection, a schematic and a first-draft layout, then manufacturing files, a firmware scaffold and a development plan. Two rules govern the work. The agent does not touch KiCad files until a validated change proposal exists. And no edit counts as done until kicad-cli has run ERC and DRC: the agent reads the errors and fixes them. Every edit runs inside a git snapshot and rolls back if verification fails. Decisions with reasons go to the docs/DECISIONS.md log, and changing one value, a charge current for example, carries through every doc and schematic that mentions it. The copperhead check command (ERC, DRC and doc drift, CI-safe), init, doctor and export bom run without a model; the last one exports a bill of materials for ordering from JLCPCB, DigiKey or Mouser. Other commands need a model: an Anthropic or OpenAI key, or an already authenticated Codex CLI, Cursor Agent CLI or Claude Code. copperhead does not optimize routing; it delivers a draft that passes DRC.
Who it is for. For electronics developers who keep boards in KiCad under git and want to make changes in words without losing consistency between the schematic, the docs and the bill of materials.
Good fit when
- A schematic needs reverse-polarity protection on VIN: copperhead do proposes the change, edits the schematic and runs ERC and DRC
- A value changes, a charge current or a pin assignment for example, and must carry through every doc and the schematic
- You have a brief for a new board and need a first full package: spec, part selection, schematic and draft board
- ERC, DRC and doc drift must be checked in CI without calling a model: copperhead check does that
- You need a parts order file for JLCPCB, DigiKey or Mouser with spares and a board count: export bom reads docs/BOM.md
Not a fit when
- You need production-ready routing: the tool delivers a draft, and optimization is done by a person or other software
- The board lives outside KiCad, in Altium or EasyEDA for example: copperhead works with existing KiCad repositories
- The board is about to go to a fab: the agent loop is implemented, but its end-to-end acceptance tests with a live model have not been observed passing, so an engineer must review
- The machine has neither Node.js 20 or newer nor KiCad 8 with kicad-cli, and you cannot install them
Example request
Add reverse-polarity protection on VIN and run ERC and DRCLimitations
The status is early: phase one is implemented and the interface may change before 1.0. The init and check commands are deterministic and covered by tests on a real KiCad project. The agent loop (do, sync --resolve, create) is complete, but its acceptance tests with a live model have not been observed passing end to end, so expect rough edges.
Node.js 20 or newer and KiCad 8 or newer with kicad-cli are required. The MCP mode is experimental, and tool names and result shapes may change in any release. With a model through Codex CLI, copperhead instructs Codex not to use its own file tools, but the CLI can technically read .env, and Codex session logs sit in ~/.codex/sessions outside the boundary where copperhead redacts its transcripts.
How to disable. Remove the package with npm uninstall -g copperhead. Delete the docs/ directory and the pre-commit hook by hand if you created them. In Claude Code remove the copperhead block from .mcp.json and the skill folder from ~/.claude/skills.
FAQ
How do I install copperhead in Claude Code or Cursor?
Paste one line to the agent: Install copperhead for this repo using https://raw.githubusercontent.com/copperheadhq/copperhead/main/agent-install-prompt.md. The agent installs and configures the tool itself. By hand it is npm install -g copperhead or npx copperhead check. On macOS and Linux there is also an install.sh script with --yes and --check-only flags that never calls sudo.
Do I need an OpenAI or Anthropic key?
Not necessarily. The --model flag accepts codex, cursor and claude-code, and copperhead then uses the login already saved in Codex CLI, Cursor Agent CLI or Claude Code. For claude-code you need the CLAUDE_CODE_OAUTH_TOKEN token from claude setup-token. The check command never calls a model at all.
What does copperhead check verify?
ERC and DRC through kicad-cli, drift between the schematic and the docs, and spec validity. No model is called, so the command is safe to run in CI.
Can copperhead be connected to an agent over MCP?
Yes, with copperhead mcp, but the interface is experimental. The server exposes five tools: copperhead_check, copperhead_do, copperhead_sync, copperhead_init and copperhead_doctor. There is no direct file-edit tool, so the agent cannot bypass verification. For Claude Code a companion skill lies in integrations/claude-code/copperhead.
What if the agent breaks the schematic?
Every edit runs inside a git snapshot and rolls back if verification fails. Still work on a separate branch: the agent loop has not been proven on a live model yet.
Discussion
No questions or reviews yet.
Related
CLI toolsThe kct CLI and a Python library for agents: parse and edit KiCad schematics and PCBs with JSON output, run DRC and ERC without a running KiCad
An MCP server that lets an agent edit an open project in Altium Designer, KiCad or EasyEDA Pro: schematics, boards, libraries, checks
Skills for coding agents that analyze KiCad schematics and boards, catch design mistakes and prepare boards for fabrication
An MCP server for PCB design in KiCAD: the agent places components, routes connections, runs DRC and prepares manufacturing files
MCP server for PCB design in KiCAD 10: schematic, routing, checks and manufacturing prep through an agent
A skill, CLI and MCP server for EasyEDA Pro: the agent reads datasheets, draws schematics and boards and checks them with DRC
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| copperhead (this entry) | no | 667 | ||
| KiCAD MCP Server | no | not required | 3,005 | an MCP server where the agent places components and routes nets itself |
| kicad-happy | no | 1,528 | skills that analyze schematics and boards and look for design errors | |
| kicad-tools | no | 74 | the kct CLI and a Python library for parsing and editing boards with JSON output |
README in short
The description compares the tool to a code editor for circuit boards and warns about its early status up front. Next come installation, requirements, a quick start in an existing repository and ways to attach a model through a saved Codex, Cursor or Claude Code login. It then covers the six-step work loop, the command reference, the bill-of-materials export, the MCP mode and a section on the tool's limits. The end gives a maturity assessment, the Apache-2.0 license and the repository layout.