Quickstart

Requirements

• Node.js >= 20
• KiCad >= 8, with kicad-cli on your PATH
• An OpenAI or Anthropic API key, supplied through the environment
• A git repository (copperhead snapshots before it edits, and rolls back if verification fails)

Check that KiCad’s CLI is visible, since every command probes it before doing anything:

kicad-cli version

Setup

1. Install the CLI.

   npm install -g copperhead

2. Set a key.

   Keys are read from the environment only, and are never written to a config file. Transcripts redact anything shaped like a key at write time.

   export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY

   Model selection resolves in this order: the --model flag, then COPPERHEAD_MODEL, then model in .copperhead/config.json, then whichever API key is present. See Configuration.

3. Adopt an existing project.

   Run init from the root of a repo that already contains a KiCad project. It reads the schematic, scaffolds the design docs, writes .copperhead/config.json, and installs a pre-commit hook.

   cd my-board
   copperhead init

   It is idempotent: rerunning it leaves your edits alone. If you have hand-edited a generated doc, init refuses to overwrite it and exits non-zero, telling you which files it skipped. Pass --force if you actually want them regenerated.

Make a change

copperhead do "add an external key jack on a spare GPIO"

The agent reads the docs, proposes the change as a validated spec, edits the schematic and the docs together, then runs ERC and DRC until they pass. To see the proposal before anything is written:

copperhead do "..." --dry-run
copperhead do "..." --interactive   # pause for approval once the proposal validates

Verify

check is contractually free of LLM calls and network access, so it is safe in CI and in a pre-commit hook. It runs ERC, DRC, doc-drift detection, constraint checks, and spec validation.

copperhead check     # alias: copperhead verify

It exits 0 when everything agrees and 1 when it does not.

Next

• Simple demo: the full create pipeline, one command
• The agent loop: what one run actually does
• Docs as memory: what lives in docs/ and why
• CLI reference: every command and flag