copper-pilot-cli 1.0.0

CopperPilot in your terminal: a thin, open-source client for CopperPilot electronics design agent, the best AI for PCB Design.

Prerequisites

• Python 3.11 or newer
• A CopperPilot account for login
• KiCad 10 on PATH only if you run examples/001_esp32 or examples/002_cm5_camera

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.