circuit-viewer: the Claude Code mod

The circuit viewer inside Claude Code: a pane beside the conversation that shows a PCB project the way the circuit-skills pipeline builds it, kept live while the board changes, plus tools the model calls. It is the Claude counterpart of the Codex plugin in ../../plugin/circuit-skills, built on the same backend (../../mcp).

What you get

• A pane with the routed KiCad board drawn from its own geometry: front and back copper, pads, vias, holes, the outline, and every blocking DRC marker (open nets in orange with a line between the two ends, shorts in red). In the terminal it is a colour picture made of half-block cells (any terminal); in the desktop app and the editor, an SVG.
  • The gates' verdict, routing metrics (track, vias, and how much plane/pour-net copper is travelling as track), and the router's progress when a route_dsn.py run is writing it.
  • Buttons (hotkeys while the pane has focus): n next issue (selects it in white and names it), z zoom to it, s front / back / both, c run the gates, r reload.
  • Live: it stats the board, its rules, the design and the router's progress file every two seconds and redraws on a save (re-running the gates if they had run). A toast says so.
• /board <path> opens a project (folder, .kicad_pcb or .circuit.tsx); /board check runs the gates; /board reopens the pane.
• Tools for the model: open_board, check_board, get_netlist (as mcp__circuit-viewer__<name>), the same verdicts the Codex plugin and the pipeline use.

Install

Needs Node.js 18+, KiCad 9+ (kicad-cli on PATH), Python 3 (the gates), and the netlist needs tscircuit installed in the project (npm install there). Nothing to build.

From the plugin marketplace (terminal or the desktop app's Code tab):

/plugin marketplace add punkfab/circuit-skills
/plugin install circuit-viewer@circuit-skills

In the desktop app's plugin browser, add punkfab/circuit-skills as a marketplace, then install circuit-viewer from it. A local checkout works as a marketplace too: add its folder path instead.

Or load it straight from a checkout:

# one session
claude --plugin-dir /path/to/circuit-skills/claude/circuit-viewer

# every session: in ~/.claude/settings.json
#   "env": { "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/circuit-skills/claude/circuit-viewer" }

Then /board ~/my-project/pcb, or ask Claude to open a board.

The skills themselves (pcb-layout and the rest) are separate: link them into ~/.claude/skills/ as before.

How it works

The mod runs in Claude Code's plugin environment (no Node, no files of its own), so the work is done by the viewer's CLI (../../mcp/src/cli.ts): one 31 kB bundle, embedded here as hooks/cli-source.ts and run with node --input-type=module - with the source on stdin, so the mod needs no install path. It carries pcb-layout's gate scripts and unpacks them to the temp folder when no checkout is nearby.

| File | | |---|---| | hooks/register.tsx | the hooks: pane, /board, tools, live refresh | | hooks/picture.ts | the board as Raster cells and as SVG, from the geometry | | hooks/cli-source.ts | generated by mcp/build.mjs; do not edit | | types/index.d.ts | the mod's $.state contract |

After changing anything in mcp/src, run npm run build in mcp/ to regenerate cli-source.ts (npm test fails if it is stale). claude plugin validate claude/circuit-viewer checks the mod.