# copperhead: an agent that designs and validates circuit boards

> copperhead applies the coding agent idea to hardware. It reads and edits real KiCad schematic and layout files, keeps the design decisions in markdown documents it treats as its memory, propagates a change across every artefact that mentions it, and then runs the electrical and design rule checks until they pass. The interesting design decisions are the ones about what the agent is allowed to touch and when.

**copperheadhq/copperhead** — Hardware as fast as software.

- Repository: https://github.com/copperheadhq/copperhead
- Website: https://copperhead.sh
- Stars: 627 · Forks: 135
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/copperheadhq-copperhead

## Cursor for circuit boards

The tagline on the project site is hardware as fast as software, and the readme's own description is cursor for circuit boards: an AI agent that designs, documents, and validates real boards from a prompt, working directly on existing KiCad repositories.

The analogy is exact in a way that is worth spelling out, because it is the whole design. A coding agent reads a codebase, proposes a change, edits real files, and runs the tests until they pass. Copperhead reads a board, proposes a change, edits real schematic and layout files, and runs the electrical and design rule checks until they pass. The structure of the problem is the same, because a board is a set of files that reference each other.

And that reference structure is where the difficulty lives. A code change usually touches a few files. A hardware change touches a part selection, a symbol, a footprint, a net, a schematic sheet, a layout placement, a bill of materials, and every document that mentions any of them. Change a charge current and it has to carry across all of them. Change a pin and the firmware has to follow. The readme calls propagation the boring, easy to get wrong step, and the one the agent is best at.

The project states its status plainly, and the honesty is welcome. It is early. Phase one is implemented and the command line runs. The technical specification is the source of truth, and the surface is expected to move before version one.

What it actually is, in the readme's words, is an AI product development agent for hardware: from a product brief to manufacturable files, firmware, and a build plan. So the deliverable is not a schematic. It is the set of files a manufacturing process and a firmware developer need, and that is a much larger claim than drawing a circuit.

There are two commands, and they cover the two ways you arrive at a board. The create command runs the whole pipeline from a natural language brief: the specification, the architecture, the part selection, the schematic, a first draft of the layout, and then the manufacturing outputs, a firmware scaffold, and a development plan. The do command operates on an existing repository the way a coding agent operates on a codebase, taking a description of a change as its argument.

The agent reads and edits the actual schematic and layout files, which are text in a parenthesised syntax, and it maintains markdown design documents as its memory.

## The loop

The how it works section opens with the sentence that explains the whole approach: it is a loop, and it looks a lot like pair programming, except the codebase is a circuit board.

There are six steps.

The first is to start from the documents. Every decision lives in the design docs, so the agent reads those first and knows the whole design, not just the part in front of it. That is a deliberate departure from how a coding agent usually works, where the code in front of the agent is the context. Here the context is a set of documents written for humans, and the board is derived from them.

The second is to talk through the change. You describe what you want, for example adding an external key jack or cutting the sleep current, and the agent proposes the parts and the circuit, and you push back until the reasoning holds up. So the loop has a human in it by design, and the human's job is to argue about the design rather than to type the design.

The third step is where the edits happen: the agent writes changes straight into the schematic and the design documents, using the same part names and net names everywhere so nothing drifts. The fourth is propagation, where a change to one value carries across every document and schematic that references it.

The fifth is checking the work, which is the step that makes the rest credible. The agent runs the electrical and design rule checks, reads the errors back, and fixes them, and the readme is emphatic that nothing is done until the tools agree. That is a stronger statement than a human reading a diff, because a human cannot read a board the way a tool can.

The sixth is writing down why. Every real decision gets a one-line reason next to it, so that the next change does not quietly undo it. That is the step that turns the documents from a description of the board into a record of the reasoning, and it is what makes step one work later.

Then there are the invariants, and the readme says two make this trustworthy. The first is that nothing starts without a specification: the agent cannot touch a KiCad file until a validated change proposal exists, and the edit tools are structurally unavailable until it does. Every edit is traceable to a document.

That is the single most important sentence in the readme. It is not a prompt instruction that the model might ignore; it is a structural property of the tool. The agent cannot begin by editing a schematic because the code that would let it do so is not reachable until the proposal has been validated, and the change is therefore always traceable to a document that a person can read.

## The two commands, and where the model comes from

The command line surface is small, and the readme's quick start lists what matters.

```bash
export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY; optional: with no key, `copperhead` offers a model picker
copperhead init                # scaffold docs/ from the schematic; idempotent
copperhead                     # interactive agent shell (Claude Code–style REPL)
copperhead demo --tour          # what the agent does (no LLM)
copperhead demo --model cursor # full USB-C breakout create pipeline
# or one-shot:
copperhead do "add reverse-polarity protection on VIN"
copperhead check               # ERC + DRC + doc drift; no LLM, CI-safe
```

Three of those are worth calling out. The init command scaffolds the documents directory from the schematic, and it is idempotent, so it is safe to run on a repository that already has documents. The demo commands exist so that you can see what the agent does without a model, and the tour one is explicitly model-free, which makes it the right thing for somebody evaluating the tool on a machine with no key. And the check command runs the electrical checks, the design rule checks, and a drift check between the documents and the design, with no model involved at all, which is what makes it safe to put in a continuous integration job.

That last one is a nice piece of design. The verification half of the agent's job is model-independent, so it is separated into a command that can run in a pipeline, and the model is only needed for the part that proposes changes.

The model backends are the second thing worth understanding, and they come in two flavours. The first is an API key, either the Anthropic one or the OpenAI one, with the note that with no key at all the tool offers a model picker. The second is a saved login to a coding assistant you already use: a locally installed and authenticated Codex command line tool, a logged in Cursor agent, or a logged in Claude Code.

The saved login path is the interesting one, because it means a subscription can be used without an API key, and the readme gives the exact recipe: install the optional adapter, check the login status, and then pass the model flag.

The routing is by prefix, matched from the top down, and the environment file spells out the whole table.

```
#   cursor            Cursor Agent CLI, saved login (`agent login`, no API key)
#   cursor:<id>       the same, on a specific model id
#   claude-code       Claude Code, saved login (no API key; uses the token above)
#   claude-code:<id>  the same, on a specific model id
#   claude            the Anthropic API provider on its default model
#   claude-<id>       any Anthropic API model id, passed through as-is
#   codex             local Codex CLI using its saved ChatGPT login (no API key)
#   codex:<id>        local Codex CLI with an explicit model id
#   gpt-5             the OpenAI provider on its default model
#   <anything>        sent to OpenAI as a model id, e.g. gpt-5-mini
```

And the comment explains the ordering rule, which is the kind of detail that causes bugs when it is wrong: the longer prefix is checked before the shorter one, so the saved login variant is never shadowed by the API variant that shares its name.

## Installing it, and a script that refuses to be clever

There are three installation routes, and the readme starts by telling most people not to use them.

If you are working inside an AI coding assistant, the advice is to paste a single line that installs and configures the tool for your repository automatically, pointing at an install prompt document in the repository. That is an unusual instruction, and it is a sign of where the project thinks its users are: people who are already talking to an assistant about their work.

The manual route is a package manager install, or a one-off run of the check command.

```bash
npm install -g copperhead   # or: npx copperhead check
```

And the third route is a bootstrap script for macOS and Linux, which checks the prerequisites, installs the tool globally through the package manager, or builds it from source when it is run inside a checkout, and then verifies the result with a doctor command.

```bash
./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 three modes are a good interface: do it interactively, do it without asking, or just tell me what is wrong. And then there is the paragraph that explains the design, which is the part of the readme I would point a reader at.

The script is conservative by design. It never runs privilege escalation and it never edits your shell configuration. Whenever it cannot act safely on its own, it prints the exact command for you to run instead. And rerunning it is safe: on a ready machine it installs nothing and exits successfully.

That is a small, well-judged piece of engineering. An installer that edits your shell profile is an installer that can break your shell, and an installer that runs with elevated privileges is an installer that can do damage. This one does neither, and it tells you what to run instead, which is what you want from a script you did not write.

The prerequisites are the other half of the picture. A recent Node.js. KiCad 8 or later with the command line tool on the path, with a note that on Windows and macOS the tool also searches the standard installation directories and that the path can be overridden with an environment variable. And a model backend, in one of the forms described earlier. The check command never calls a model, which means you can verify the installation before you have decided which provider to use.

## Credentials, and the honest limits of a sandbox

The environment example file is the most revealing document in the repository, because it is where the project has to be honest about what a model can and cannot be trusted with.

The first rule is simple: the API keys are read from the environment only, and a real environment file is never to be committed. The file is loaded from the directory you run the tool in, and a variable already set in your shell always wins over the file, which is the correct precedence for a developer who has exported something in their session.

Then there is the saved login path for the Claude Code provider, and the comment is careful in a way that matters. The token drives Claude Code through the agent SDK and reuses your saved login, so a subscription runs the tool with no API key at all. You mint it with the setup command while logged in. The SDK ships as an optional dependency, so a normal install includes it. And then the sentence that matters: the tool never reads or logs this credential, the command line tool owns authentication.

That is the right division of labour, and it is also the safe one. A credential that the tool never touches cannot leak through the tool, and the tool that owns the credential is the one that already has a model of how to keep it.

Then there is the paragraph about the Codex path, and it is the most valuable security note in the project, because it describes a limitation rather than a feature.

The read-only sandbox of that tool prevents native writes but does not confine native reads. The project instructs the agent not to use its own file system tools, but the command line tool can technically read files such as the environment file. And the session logs that tool keeps under a directory in the home folder are outside the transcript redaction boundary of this project, and should be protected according to your own data retention policy.

That is exactly the kind of statement a project makes when it has thought about the failure mode. The mitigation is an instruction rather than a mechanism, and the readme says so instead of implying the sandbox covers it. And the session logs point out a leak that has nothing to do with the agent at all: a tool that keeps transcripts on disk is a tool that has created a second copy of your data.

So the practical guidance is to pick the provider whose authentication you already trust, and to read the boundary notes before you point it at a repository with secrets in it.

## The repository, and the specification first

The top level of the repository tells you that this is a project with a process, and one directory on the list is the one that matters most.

There is a directory of specifications, holding the technical specification that the readme calls the source of truth, with the surface expected to move before version one. That is a deliberate choice: when the behaviour is not settled, the document that describes it is authoritative, and the code is an implementation of it. A project at version zero point twelve with a written specification is a project that intends to have a stable interface eventually, and that expects the details to churn until it does.

There is a roadmap file, a contribution guide, a notice file alongside the licence, and two instruction files for coding agents, one of which is a general agent instruction file and the other specific to one assistant. A project that asks an agent to work on it has to tell the agent what the rules are, and having those rules in the repository is how a contributor or an agent finds them.

Then there are the working directories. There is a source directory and a test directory, with a test runner configured separately, and a directory of manual tests, which is the interesting one: in a project that drives an external application, some of the checks cannot be automated, and a directory for them is the honest way to record what a human still has to do.

There is a directory of integrations, one for the assistant installers, and a directory of pipeline run logs, which is a nice touch for a project whose whole purpose is producing signed records of what a pipeline did.

And there is the examples directory, with the subdirectories for difficulty: a simple one, a medium one, a hard one, and an images directory. The readme explains what they are for, and the explanation is the most useful sentence in the quick start for a new user. They are ready-made product briefs sorted by difficulty, and there is a note on which one is designed to fail.

A brief that is designed to fail is a remarkable thing to ship, and it tells you a lot about how the project is being developed. It means the author is testing the agent against a case where the right outcome is a refusal or an error, and it means a user can see the failure mode rather than only the happy path.

The package manifest is the last piece. The build compiles the TypeScript and then runs a post-build step that makes the compiled command line file executable, which is a small detail that a package with a binary entry point always needs. The publish configuration enables public access and provenance, so the published package carries a link back to the source it was built from. And the markdown lint script is worth noting for its exclude list, which is long and specific, because it names every directory in the repository whose generated content must not be linted.

## Conclusion

copperhead fits a hardware engineer who wants a first draft of a board quickly, or who wants a change propagated across a schematic, a layout and a set of documents without doing it by hand. It does not fit a production release process, because the project says plainly that it is early and that the surface will move before version one, and it does not fit a team that does not already have KiCad and a model backend set up. Verify first which model provider you will use and how its authentication works, since the saved login paths and the API key paths have different security properties, and that the design rule checks in your own project are as strict as the ones the agent runs, since the agent will only stop when the checks it knows about pass.

## FAQ

### What is the copperhead project?

It is an AI product development agent for hardware, described as cursor for circuit boards. It takes a product brief and produces a specification, an architecture, a part selection, a schematic, a first draft layout, the manufacturing outputs, a firmware scaffold and a development plan, and it can also operate on an existing KiCad repository the way a coding agent operates on a codebase.

### How does copperhead make sure its work is correct?

It runs the electrical and design rule checks through the KiCad command line tool, reads the errors back, and fixes them, and nothing is considered done until the tools agree. That verification is also available as a separate check command that uses no model at all, so it is safe to run in continuous integration.

### What stops the copperhead agent from editing files arbitrarily?

The first of two invariants. Nothing starts without a specification: the agent cannot touch a KiCad file until a validated change proposal exists, and the edit tools are structurally unavailable until it does, so every edit is traceable to a document. The second invariant concerns the documentation of the reasoning behind each decision.

### Which AI backends does copperhead support?

An API key for Anthropic or OpenAI, or a saved login to a coding assistant you already use: a local Codex command line tool, the Cursor agent, or Claude Code. The routing is by prefix matched from the top down, so the saved login variants are checked before the API variants that share their names, and a saved Claude Code login lets a subscription run the tool with no API key at all.

### What are the limits of the Codex integration in copperhead?

The readme is explicit that the read-only sandbox of that tool prevents native writes but does not confine native reads, so the project instructs the agent not to use its own file system tools while the tool can technically read files such as the environment file. The session logs it keeps under a directory in the home folder are also outside the project's transcript redaction boundary and should be protected under your own retention policy.

## Sources

- [copperheadhq/copperhead on GitHub](https://github.com/copperheadhq/copperhead)
- [License: Apache-2.0](https://github.com/copperheadhq/copperhead/blob/main/LICENSE)
- [Project website](https://copperhead.sh)
- [README](https://github.com/copperheadhq/copperhead/blob/main/README.md)
- [Releases](https://github.com/copperheadhq/copperhead/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/copperheadhq-copperhead