How copperheadhq/copperhead works
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: loop.ts Agent loop · cli.ts CLI router · server.ts MCP server · check.ts ERC/DRC checks
Components 23
Entry surfaces
- CLI router
src/cli.ts - Interactive shell
src/commands/repl.ts - MCP server
src/mcp/server.ts - Project config
src/config.ts
Agent runtime
- Agent loop
src/agent/loop.ts - Model providers
src/agent/providers - Tool dispatch
src/agent/tools.ts - Design tools
src/capabilities/handlers.ts - Run transcript
src/agent/transcript.ts
PCB design
- Brief pipeline
src/commands/create.ts - Schematic drafting
src/kicad/draft/engine.ts - Board population
src/kicad/populate.ts - KiCad artifacts
Design state
- Design docs
src/memory/scaffold.ts - Design constraints
src/memory/constraints.ts - Drift tracking
src/memory/drift.ts
Verification and access
- ERC/DRC checks
src/commands/check.ts - KiCad CLI
src/kicad/cli.ts - Spec validation
src/openspec/cli.ts - Fabrication export
src/kicad/fab.ts - Skills registry
src/capabilities/index.ts - Sync workflow
src/commands/sync.ts
Other components
- Engineer
Connections 32
- Engineer → CLI router: runs command
README.md - CLI router → Interactive shell: opens shell
src/cli.ts - CLI router → Brief pipeline: starts creation
src/cli.ts - CLI router → ERC/DRC checks: runs checks
src/cli.ts - CLI router → Fabrication export: exports BOM
src/cli.ts - CLI router → Sync workflow: runs sync
src/cli.ts - Engineer → MCP server: uses MCP host
README.md - Interactive shell → Agent loop: starts agent
src/commands/repl.ts - MCP server → Agent loop: runs agent
src/mcp/server.ts - MCP server → ERC/DRC checks: runs checks
src/mcp/server.ts - MCP server → Sync workflow: runs sync
src/mcp/server.ts - MCP server → Project config: loads config
src/mcp/server.ts - Agent loop → Model providers: requests model
src/agent/loop.ts - Agent loop → Tool dispatch: dispatches calls
src/agent/loop.ts - Tool dispatch → Design tools: routes tools
- Agent loop → Run transcript: records run
src/agent/loop.ts - Brief pipeline → Agent loop: runs design stages
README.md - Brief pipeline → Schematic drafting: drafts schematic
src/commands/create.ts - Brief pipeline → Board population: populates board
src/commands/create.ts - Schematic drafting → KiCad artifacts: writes schematic
README.md - Board population → KiCad artifacts: writes board
src/kicad/populate.ts - Agent loop → KiCad artifacts: edits artifacts
README.md - Agent loop → Design docs: updates design docs
README.md - Agent loop → Design constraints: checks proposal
src/agent/loop.ts - ERC/DRC checks → KiCad CLI: runs ERC/DRC
src/commands/check.ts - ERC/DRC checks → Drift tracking: checks doc drift
src/commands/check.ts - ERC/DRC checks → Spec validation: validates spec
src/commands/check.ts - Sync workflow → Drift tracking: resolves drift
README.md - Fabrication export → KiCad artifacts: reads design
README.md - CLI router → Skills registry: runs skill
src/cli.ts - Skills registry → Design tools: registers handlers
src/capabilities/index.ts - CLI router → Project config: loads settings
src/cli.ts