chouhanindustries/copperhead

<p align="center" <a href="https://copperhead.sh"<img src="https://raw.githubusercontent.com/chouhanindustries/copperhead/main/docs/branding/lockup-transparent.png" alt="copperhead" width="440"</a </p

<p align="center" <a href="https://www.npmjs.com/package/copperhead"<img src="https://img.shields.io/npm/v/copperhead?color=b87333" alt="npm"</a <a href="https://github.com/chouhanindustries/copperhead/actions/workflows/ci.yml"<img src="https://github.com/chouhanindustries/copperhead/actions/workflows/ci.yml/badge.svg" alt="CI"</a <a href="LICENSE"<img src="https://img.shields.io/npm/l/copperhead?color=15181c" alt="license"</a </p

Cursor for circuit boards. An AI agent that designs, documents, and validates real PCBs from a prompt, working directly on existing KiCad repositories.

<p align="center" <img src="https://raw.githubusercontent.com/chouhanindustries/copperhead/main/assets/copperhead.gif" alt="copperhead agent shell demo" width="720" </p

Status: early. Phase 1 is implemented and the CLI runs. The technical specification is the source of truth; expect the surface to move before 1.0.

Full documentation lives at docs.copperhead.sh.

What it is

An AI product-development agent for hardware: from a product brief to manufacturable files, firmware, and a build plan.

• copperhead create: full pipeline from a natural-language brief: spec, architecture, part selection, schematic, first-draft layout, then gerbers, firmware scaffold, and dev plan.
• copperhead do "<change": operates on an existing KiCad repo the way a coding agent operates on a codebase.

It reads and edits real .kicadsch / .kicadpcb files (s-expression text), maintains markdown design docs as memory, propagates every change across all artifacts that reference it, and verifies its own work by running kicad-cli ERC/DRC until the checks pass.

Install

[!TIP] Most users should not install copperhead by hand. If you are working inside an AI coding assistant (like Claude Code, Cursor, or Codex), you can install and configure copperhead automatically for your repository by pasting this single line: text Install copperhead for this repo using https://raw.githubusercontent.com/chouhanindustries/copperhead/main/agent-install-prompt.md

If you prefer to install manually:

npm install -g copperhead   # or: npx copperhead check

Bootstrap script (macOS and Linux)

Prefer a one-command setup? install.sh checks the prerequisites below, installs copperhead (globally via npm, or built from source when run inside a checkout), and verifies the result with copperhead doctor:

./install.sh                # interactive: asks before installing anything
./install.sh --yes          # assume yes to the install prompts
./install.sh --check-only   # report what is missing, install nothing

The script is conservative by design: it never runs sudo and never edits shell config; whenever it cannot act safely on its own it prints the exact command for you to run instead. Rerunning is safe: on a ready machine it installs nothing and exits 0.