Esp32

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

To let the agent import LCSC/EasyEDA parts (symbol, footprint and 3D model) with easyeda2kicad, install the optional extra, which is AGPL-3.0 licensed: pip install "copper-pilot-cli[easyeda]" (or uv tool install "copper-pilot-cli[easyeda]"). Agent shell commands can run command-line tools installed alongside the CLI even when pipx or uv tool keeps them off your PATH.

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.

CopperPilot checks for feature updates once per day without delaying your work. When a release adds a feature, it prints one line with the feature and copper-pilot update. Use copper-pilot update --check to inspect the latest release, or copper-pilot update to run the owning package manager's update.

copper-pilot ./my-board
copper-pilot --resume
copper-pilot threads list
copper-pilot -n -m "Review this board" --json
copper-pilot -n -r          # resume the most recent thread's unfinished turn
copper-pilot --mode plan --effort intelligence -m "Survey and plan this board"

Long turns survive dropped connections, server restarts and LLM provider rate limits (the CLI shows "High demand — waiting to continue" and resumes on its own): the CLI keeps a journal of the turn on your machine and resumes it automatically. If a turn still does not finish (or the CLI was closed mid-turn), type /resume in the TUI, run copper-pilot -n -r, or send "continue"; the turn picks up where it left off without re-running finished tools. See Turn durability.

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. Shell commands that reach outside the workspace (find /, grep -r ~, other projects under the home directory, docker, sudo, ssh) ask in every mode, YOLO included, and are refused when nobody can approve them (headless, MCP). See docs/cli.md.

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.