Getting started

This guide takes you from nothing installed to a board ready to order.

1. Install the tools

macOS, Windows 10/11 and Linux are supported, and everything after this step is identical on all of them. The plugin runs on KiCad's bundled Python, so nothing else is needed. On Linux, install KiCad from the official PPA or Flatpak so that python3 -c "import pcbnew" works.

2. Install the plugin

In Claude Code, run:

/plugin install pcb --marketplace virajrungta/viaduct

Confirm the marketplace and choose Install for you. A setup form asks for your usual manufacturer, how boards get built (assembled or hand-soldered), your default layer count, and whether kipcb may learn from your boards (locally). Change these later with /plugin configure viaduct@viaduct.

Turn on auto-update so weekly versions arrive automatically: /plugin → Marketplaces → pcb-claude-plugin → Enable auto-update.

Start a new session. The plugin welcomes you and checks your toolchain.

3. Check the toolchain

In a Claude Code session, ask Claude to "run kipcb doctor" (kipcb is available inside Claude Code sessions). You should see KiCad, pcbnew and Java reported as OK. If Freerouting shows as not installed, ask Claude to run kipcb setup-router: it downloads the Freerouting autorouter (~65 MB) from its official GitHub releases into kipcb's cache folder (~/.cache/kipcb on macOS, %LOCALAPPDATA%\kipcb\cache on Windows). When you use /viaduct:design, Claude asks before downloading it.

4. Design a board

In Claude Code, from the folder where you want the project:

/viaduct:design a USB-C powered ESP32-C3 board with an RGB status LED, reset and boot buttons, and a 4-pin I2C header

What happens next:

1. Questions. Claude asks a few quick questions: board size, power source and current, which connectors go on which edges, assembly vs hand soldering, and whether anything is noise-sensitive. Answer what you know; sensible defaults cover the rest.
2. Architecture and parts. Claude proposes a block diagram and power tree, then picks real parts from KiCad's libraries, checking every pin and following each chip's datasheet reference circuit.
3. Spec and validation. The circuit is written as a JSON design spec in hardware/<name>.json and validated. Every pin must be connected or explicitly marked unused.
4. Build and inspect. The schematic and a placed board are generated, checked, and rendered. Claude looks at the renders and adjusts placement.
5. Route. The board is autorouted, ground planes are poured, and DRC plus the noise checks run until clean.
6. Manufacturing files. Gerbers, BOM and pick-and-place files land in hardware/<name>/fab/.

Claude finishes with the run report: whether the board is ready to order, where the project is, board size and layers, which checks passed, the manufacturing files, and anything that deserves a human look, plus the assumptions it made. The same summary is saved in reports/REPORT.md inside the project, and kipcb report <project> prints it again any time.

hardware/<name>/
  <name>.kicad_pro / .kicad_sch / .kicad_pcb   open in KiCad
  fab/        Gerber zip, BOM, pick-and-place: send these to the manufacturer
  previews/   board and schematic images, printable PDFs
  reports/    REPORT.md and the check results

5. Open it in KiCad

open hardware/<name>/<name>.kicad_pro

(xdg-open on Linux.) It's a normal KiCad project: edit the schematic, nudge parts, or hand-route critical nets.

Spec vs hand edits. Claude edits the JSON spec and rebuilds, and a rebuild regenerates the KiCad files. Iterate with Claude first, then switch to KiCad for final polish. After that, /viaduct:review and /viaduct:fab work directly on your edited files.

6. Order boards

/viaduct:fab hardware/<name>

Upload fab/<name>-gerbers.zip to your fab (JLCPCB, PCBWay, OSH Park…). For assembly, also upload fab/<name>-bom.csv and fab/<name>-cpl.csv, and check part rotations in the fab's preview. Claude never places orders for you.

Questions and feedback

/viaduct:inquiry what pull-ups do I need for I2C at 400 kHz?
/viaduct:inquiry path/to/my_board/

Ask anything about circuits, parts, layout or manufacturing, or point it at a design (a KiCad project, a spec, a schematic image or PDF, a Gerber zip) for quick feedback. Boards are compared with real routed open-source designs.

Try the examples first

git clone https://github.com/virajrungta/viaduct

cd viaduct && bin/kipcb run examples/usb_blinker.json

Then open examples/usb_blinker/usb_blinker.kicad_pro in KiCad.