# copperheadhq/copperhead architecture

> Architecture diagram of the GitHub repository copperheadhq/copperhead, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/copperheadhq/copperhead
- Repository: https://github.com/copperheadhq/copperhead

## Overview

Copperhead is an AI hardware-design agent for existing KiCad repositories and a staged brief-to-board creation pipeline. The main workflow enters through the CLI or interactive shell, runs an agent loop with spec-gated tools, edits KiCad and design-document artifacts, and verifies changes with ERC/DRC and drift checks. Separate branches provide scaffold/sync, manufacturing export, skills, and MCP access. The source excerpts establish several dispatch and library relationships; broader product-stage links are supported by the README, while unsampled implementation details are not expanded.

Main entry points: [`src/agent/loop.ts`](https://github.com/copperheadhq/copperhead/blob/main/src/agent/loop.ts) (Agent loop), [`src/cli.ts`](https://github.com/copperheadhq/copperhead/blob/main/src/cli.ts) (CLI router), [`src/mcp/server.ts`](https://github.com/copperheadhq/copperhead/blob/main/src/mcp/server.ts) (MCP server), [`src/commands/check.ts`](https://github.com/copperheadhq/copperhead/blob/main/src/commands/check.ts) (ERC/DRC checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry surfaces"]
  node_cli["CLI router<br/>[cli.ts]"]
  node_repl["Interactive shell<br/>[repl.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_config["Project config<br/>[config.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_loop["Agent loop<br/>[loop.ts]"]
  node_providers["Model providers"]
  node_tool_dispatch["Tool dispatch<br/>[tools.ts]"]
  node_capabilities["Design tools<br/>[handlers.ts]"]
  node_transcript["Run transcript<br/>[transcript.ts]"]
end

subgraph group_design["PCB design"]
  node_create["Brief pipeline<br/>[create.ts]"]
  node_draft["Schematic drafting<br/>[engine.ts]"]
  node_populate["Board population<br/>[populate.ts]"]
  node_kicad_files["KiCad artifacts"]
end

subgraph group_state["Design state"]
  node_memory["Design docs<br/>[scaffold.ts]"]
  node_constraints["Design constraints<br/>[constraints.ts]"]
  node_drift["Drift tracking<br/>[drift.ts]"]
end

subgraph group_verification["Verification and access"]
  node_check["ERC/DRC checks<br/>[check.ts]"]
  node_kicad_cli["KiCad CLI<br/>[cli.ts]"]
  node_openspec["Spec validation<br/>[cli.ts]"]
  node_export["Fabrication export<br/>[fab.ts]"]
  node_skills["Skills registry<br/>[index.ts]"]
  node_sync["Sync workflow<br/>[sync.ts]"]
end

node_user(("Engineer"))

node_user -->|"runs command"| node_cli
node_cli -->|"opens shell"| node_repl
node_cli -->|"starts creation"| node_create
node_cli -->|"runs checks"| node_check
node_cli -->|"exports BOM"| node_export
node_cli -->|"runs sync"| node_sync
node_user -->|"uses MCP host"| node_mcp
node_repl -->|"starts agent"| node_loop
node_mcp -->|"runs agent"| node_loop
node_mcp -->|"runs checks"| node_check
node_mcp -->|"runs sync"| node_sync
node_mcp -->|"loads config"| node_config
node_loop -->|"requests model"| node_providers
node_loop -->|"dispatches calls"| node_tool_dispatch
node_tool_dispatch -.->|"routes tools"| node_capabilities
node_loop -.->|"records run"| node_transcript
node_create -->|"runs design stages"| node_loop
node_create -->|"drafts schematic"| node_draft
node_create -->|"populates board"| node_populate
node_draft -->|"writes schematic"| node_kicad_files
node_populate -->|"writes board"| node_kicad_files
node_loop -->|"edits artifacts"| node_kicad_files
node_loop -->|"updates design docs"| node_memory
node_loop -->|"checks proposal"| node_constraints
node_check -->|"runs ERC/DRC"| node_kicad_cli
node_check -->|"checks doc drift"| node_drift
node_check -->|"validates spec"| node_openspec
node_sync -->|"resolves drift"| node_drift
node_export -->|"reads design"| node_kicad_files
node_cli -->|"runs skill"| node_skills
node_skills -->|"registers handlers"| node_capabilities
node_cli -->|"loads settings"| node_config

click node_cli "https://github.com/copperheadhq/copperhead/blob/main/src/cli.ts"
click node_repl "https://github.com/copperheadhq/copperhead/blob/main/src/commands/repl.ts"
click node_mcp "https://github.com/copperheadhq/copperhead/blob/main/src/mcp/server.ts"
click node_config "https://github.com/copperheadhq/copperhead/blob/main/src/config.ts"
click node_loop "https://github.com/copperheadhq/copperhead/blob/main/src/agent/loop.ts"
click node_providers "https://github.com/copperheadhq/copperhead/tree/main/src/agent/providers"
click node_tool_dispatch "https://github.com/copperheadhq/copperhead/blob/main/src/agent/tools.ts"
click node_capabilities "https://github.com/copperheadhq/copperhead/blob/main/src/capabilities/handlers.ts"
click node_transcript "https://github.com/copperheadhq/copperhead/blob/main/src/agent/transcript.ts"
click node_create "https://github.com/copperheadhq/copperhead/blob/main/src/commands/create.ts"
click node_draft "https://github.com/copperheadhq/copperhead/blob/main/src/kicad/draft/engine.ts"
click node_populate "https://github.com/copperheadhq/copperhead/blob/main/src/kicad/populate.ts"
click node_memory "https://github.com/copperheadhq/copperhead/blob/main/src/memory/scaffold.ts"
click node_constraints "https://github.com/copperheadhq/copperhead/blob/main/src/memory/constraints.ts"
click node_drift "https://github.com/copperheadhq/copperhead/blob/main/src/memory/drift.ts"
click node_check "https://github.com/copperheadhq/copperhead/blob/main/src/commands/check.ts"
click node_kicad_cli "https://github.com/copperheadhq/copperhead/blob/main/src/kicad/cli.ts"
click node_openspec "https://github.com/copperheadhq/copperhead/blob/main/src/openspec/cli.ts"
click node_export "https://github.com/copperheadhq/copperhead/blob/main/src/kicad/fab.ts"
click node_skills "https://github.com/copperheadhq/copperhead/blob/main/src/capabilities/index.ts"
click node_sync "https://github.com/copperheadhq/copperhead/blob/main/src/commands/sync.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_repl,node_mcp,node_config toneBlue
class node_loop,node_providers,node_tool_dispatch,node_capabilities,node_transcript toneAmber
class node_create,node_draft,node_populate,node_kicad_files toneMint
class node_memory,node_constraints,node_drift toneRose
class node_check,node_kicad_cli,node_openspec,node_export,node_skills,node_sync,node_user toneIndigo
```

## Components

### Entry surfaces

- [CLI router](https://github.com/copperheadhq/copperhead/blob/main/src/cli.ts): `src/cli.ts`
- [Interactive shell](https://github.com/copperheadhq/copperhead/blob/main/src/commands/repl.ts): `src/commands/repl.ts`
- [MCP server](https://github.com/copperheadhq/copperhead/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Project config](https://github.com/copperheadhq/copperhead/blob/main/src/config.ts): `src/config.ts`

### Agent runtime

- [Agent loop](https://github.com/copperheadhq/copperhead/blob/main/src/agent/loop.ts): `src/agent/loop.ts`
- [Model providers](https://github.com/copperheadhq/copperhead/tree/main/src/agent/providers): `src/agent/providers`
- [Tool dispatch](https://github.com/copperheadhq/copperhead/blob/main/src/agent/tools.ts): `src/agent/tools.ts`
- [Design tools](https://github.com/copperheadhq/copperhead/blob/main/src/capabilities/handlers.ts): `src/capabilities/handlers.ts`
- [Run transcript](https://github.com/copperheadhq/copperhead/blob/main/src/agent/transcript.ts): `src/agent/transcript.ts`

### PCB design

- [Brief pipeline](https://github.com/copperheadhq/copperhead/blob/main/src/commands/create.ts): `src/commands/create.ts`
- [Schematic drafting](https://github.com/copperheadhq/copperhead/blob/main/src/kicad/draft/engine.ts): `src/kicad/draft/engine.ts`
- [Board population](https://github.com/copperheadhq/copperhead/blob/main/src/kicad/populate.ts): `src/kicad/populate.ts`
- **KiCad artifacts**

### Design state

- [Design docs](https://github.com/copperheadhq/copperhead/blob/main/src/memory/scaffold.ts): `src/memory/scaffold.ts`
- [Design constraints](https://github.com/copperheadhq/copperhead/blob/main/src/memory/constraints.ts): `src/memory/constraints.ts`
- [Drift tracking](https://github.com/copperheadhq/copperhead/blob/main/src/memory/drift.ts): `src/memory/drift.ts`

### Verification and access

- [ERC/DRC checks](https://github.com/copperheadhq/copperhead/blob/main/src/commands/check.ts): `src/commands/check.ts`
- [KiCad CLI](https://github.com/copperheadhq/copperhead/blob/main/src/kicad/cli.ts): `src/kicad/cli.ts`
- [Spec validation](https://github.com/copperheadhq/copperhead/blob/main/src/openspec/cli.ts): `src/openspec/cli.ts`
- [Fabrication export](https://github.com/copperheadhq/copperhead/blob/main/src/kicad/fab.ts): `src/kicad/fab.ts`
- [Skills registry](https://github.com/copperheadhq/copperhead/blob/main/src/capabilities/index.ts): `src/capabilities/index.ts`
- [Sync workflow](https://github.com/copperheadhq/copperhead/blob/main/src/commands/sync.ts): `src/commands/sync.ts`

### Other components

- **Engineer**

## Connections

- Engineer → CLI router: runs command (evidence: `README.md`)
- CLI router → Interactive shell: opens shell (evidence: `src/cli.ts`)
- CLI router → Brief pipeline: starts creation (evidence: `src/cli.ts`)
- CLI router → ERC/DRC checks: runs checks (evidence: `src/cli.ts`)
- CLI router → Fabrication export: exports BOM (evidence: `src/cli.ts`)
- CLI router → Sync workflow: runs sync (evidence: `src/cli.ts`)
- Engineer → MCP server: uses MCP host (evidence: `README.md`)
- Interactive shell → Agent loop: starts agent (evidence: `src/commands/repl.ts`)
- MCP server → Agent loop: runs agent (evidence: `src/mcp/server.ts`)
- MCP server → ERC/DRC checks: runs checks (evidence: `src/mcp/server.ts`)
- MCP server → Sync workflow: runs sync (evidence: `src/mcp/server.ts`)
- MCP server → Project config: loads config (evidence: `src/mcp/server.ts`)
- Agent loop → Model providers: requests model (evidence: `src/agent/loop.ts`)
- Agent loop → Tool dispatch: dispatches calls (evidence: `src/agent/loop.ts`)
- Tool dispatch → Design tools: routes tools
- Agent loop → Run transcript: records run (evidence: `src/agent/loop.ts`)
- Brief pipeline → Agent loop: runs design stages (evidence: `README.md`)
- Brief pipeline → Schematic drafting: drafts schematic (evidence: `src/commands/create.ts`)
- Brief pipeline → Board population: populates board (evidence: `src/commands/create.ts`)
- Schematic drafting → KiCad artifacts: writes schematic (evidence: `README.md`)
- Board population → KiCad artifacts: writes board (evidence: `src/kicad/populate.ts`)
- Agent loop → KiCad artifacts: edits artifacts (evidence: `README.md`)
- Agent loop → Design docs: updates design docs (evidence: `README.md`)
- Agent loop → Design constraints: checks proposal (evidence: `src/agent/loop.ts`)
- ERC/DRC checks → KiCad CLI: runs ERC/DRC (evidence: `src/commands/check.ts`)
- ERC/DRC checks → Drift tracking: checks doc drift (evidence: `src/commands/check.ts`)
- ERC/DRC checks → Spec validation: validates spec (evidence: `src/commands/check.ts`)
- Sync workflow → Drift tracking: resolves drift (evidence: `README.md`)
- Fabrication export → KiCad artifacts: reads design (evidence: `README.md`)
- CLI router → Skills registry: runs skill (evidence: `src/cli.ts`)
- Skills registry → Design tools: registers handlers (evidence: `src/capabilities/index.ts`)
- CLI router → Project config: loads settings (evidence: `src/cli.ts`)
