Getting started

Quickstart

Install copperhead, choose a model backend, and run your first verified change.

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 with a single pasteable command:

Install copperhead for this repo using https://raw.githubusercontent.com/copperheadhq/copperhead/main/agent-install-prompt.md

Requirements

Node.js >= 20
KiCad >= 8, with kicad-cli on your PATH
One model backend: an authenticated local Codex CLI, a logged-in Claude Code (saved login, no API key), or an OpenAI/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

Install the CLI.
Terminal window
```
npm install -g copperhead
```
Choose a model backend.

To reuse your existing Codex login without a model API key:
Terminal window
```
npm install -g @openai/codex-sdk   # optional adapter, loaded only for Codex runs
codex login status
export COPPERHEAD_MODEL=codex
```
If codex is not on PATH, the SDK package includes a compatible launcher. For a global install:
Terminal window
```
export COPPERHEAD_CODEX_PATH="$(npm root -g)/@openai/codex/bin/codex.js"
```
To reuse a Claude subscription through your logged-in Claude Code, also without a model API key:
Terminal window
```
claude setup-token                     # while logged into Claude Code
export CLAUDE_CODE_OAUTH_TOKEN=...      # the token it prints
export COPPERHEAD_MODEL=claude-code
```
The Claude Agent SDK ships as an optional dependency, so a normal install includes it. See Saved login (Claude Code).

Or set a direct model API key. Keys are read from the environment only, never written to a config file, and redacted from transcripts.
Terminal window
```
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.
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.
Terminal window
```
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.

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