CopperPilot in your terminal: a thin, open-source client for CopperPilot electronics design agent, the best AI for PCB Design.
Prerequisites
Install and run
pip install copper-pilot-cli
copper-pilot
The first interactive launch opens a browser for CopperPilot device login.
With no path argument, the current directory is the workspace and a new chat
starts immediately. Any existing directory is valid.
copper-pilot ./my-board
copper-pilot --resume
copper-pilot threads list
copper-pilot -n -m "Review this board" --json
copper-pilot --mode plan --effort intelligence -m "Survey and plan this board"
Both copper-pilot and copper-pilot-cli run the same program.
copper-pilot --help lists flags; docs/cli.md is the full
command reference.
Balanced effort is the default. Paid-plan users can select Intelligence with
--effort intelligence or interactive /effort; Intelligence runs on Gemini 4
Argon. Picking another model (--model <id>, /model) is turned off for now
(ENABLE_MODEL_SELECTOR in copper_models.py). Intelligence uses
server-owned survey subagents and shows their lifecycle through the existing
Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
Validate
copper-pilot validate ./my-board
Runs a stage-gated graph of read-only reviewers over the KiCad workspace:
kicad-cli checks (ERC, DRC, schematic parity, board rules, Gerbers) plus
hosted Agent-mode reviewers, each scoped to one concern, in the order a hardware
engineer reviews a board. It never edits design files. The verdict, a
REPORT.md, and next_actions.json (only the earliest failing stage, worst
first) land in .copperpilot/validate/latest/; --emit-fix-prompt prints a
ready message for copper-pilot --mode agent. Exit codes: 0 pass, 1 fail,
2 config error, 3 incomplete, 4 not logged in or usage limit. See
docs/validate.md.
Use from Claude Code, Cursor, or Codex
CopperPilot stays the electronics agent. Copy
skills/copper-pilot-review/SKILL.md into
your harness, or expose the same agent over MCP:
claude mcp add copper-pilot -- copper-pilot mcp
Claude Code can also install the in-repo plugin:
/plugin marketplace add CopperPilot/copper-pilot-cli
/plugin install copper-pilot
That plugin starts copper-pilot mcp (tools status, ask, plan, run,
resume, threads_list, validate) and adds @copper-pilot plus
/copper-pilot-review. Editors that speak the Agent Client Protocol, such as
Zed, can run copper-pilot acp after pip install "copper-pilot-cli[acp]".
Setup for Cursor, Codex, Zed, and approvals: docs/harness.md.
Configuration
- Production API:
https://copperpilot.ai
- Development override:
COPPER_PILOT_API_URL
- User state:
~/.copper-pilot/.state
- Project artifacts:
.copperpilot/
Credentials are stored in a private, atomically replaced auth.json; on POSIX
the parent directory is mode 0700 and the file is mode 0600.
LangChain
from copper_pilot_cli.copper_protocol import CopperEffort, CopperMode
from copper_pilot_cli.langchain import CopperPilotAgent
from helper import drc_violations, erc_errors, render_pcb, run
PLAN = CopperMode.PLAN
copper_pilot = CopperPilotAgent(
workspace="esp32",
effort=CopperEffort.INTELLIGENCE,
model="claude-opus-5-5", # optional; Intelligence defaults to Gemini 4 Argon
)
run(copper_pilot, "Build me an ESP32 dev board.", PLAN)
run(copper_pilot, "Let us build this plan.")
run(copper_pilot, "Inspect the PCB, check for any missing 3D models, and apply them accordingly.")
assert erc_errors() == 0
assert drc_violations() == 0
render_pcb("esp32.png")
CopperPilotAgent is a Runnable, not a chat model. It represents a complete
hosted agent run, including local tool requests. Use as_langgraph() for graph
composition or as_compiled_subagent() for explicit delegation from an outer
Deep Agent. The compatible deepagents runtime is installed and pinned by this
package.
That snippet is the runnable example in
examples/001_esp32. A phased CM5 camera carrier lives in
examples/002_cm5_camera.
Security boundary
The hosted agent may request local filesystem and shell tools. Reads and
searches run freely. Writes, edits, deletes, and shell commands are gated by
Manual approval by default. Auto permits only deterministic routine actions;
unknown actions still ask. YOLO must be selected explicitly.
Filesystem, search, edit, and shell execution use Deep Agents' native
FilesystemMiddleware tools and LocalShellBackend; CopperPilot's adapter only
normalizes hosted tool names, approval decisions, and result envelopes.
Computer use, model/provider selection, local model execution, LangSmith
tracing, content telemetry, MCP host/plugin-runtime controls, and server
implementation code are not part of this package. A thin MCP server
(copper-pilot mcp) and an ACP server (copper-pilot acp) that delegate
to the hosted agent are.
See UPSTREAM.md and NOTICE for the retained Textual
client attribution.
To report a vulnerability, see SECURITY.md.
Development
pip install -e ".[dev]"
make fmt
make lint
make test
make test runs pytest -m "not live". Live tests skip unless a CopperPilot
credential is stored. Release tagging is make release. Details:
docs/development.md.
Contributing
Bug reports, features, and pull requests are welcome. Please read
CONTRIBUTING.md and the
Code of Conduct. Use the
bug report form
so we can reproduce the problem.
License
MIT.
