boardwright

Author, render & ERC-check hand-wired board layouts from a single JSON file. Headless, browser-free, and built to be driven by AI coding agents (Claude Code, Codex, Cursor) as much as by humans.

You describe a board once — a grid of holes, components placed at hole coordinates, and nets that say what connects to what — and boardwright:

• 🔀 auto-routes the nets across the board with a maze router,
• ✅ runs a mini ERC (electrical-rule check): every pin wired, no shorts, nothing floating,
• 🖼️ renders a two-sided, self-documenting HTML layout (component side + solder side, tinted pads, hover tooltips),
• 🤖 verifies headlessly — a text netlist and PNG snapshots, no browser needed — so an agent can check its own work.

The JSON is the schematic. The render is derived from it, so the picture can never drift from the netlist.

$ boardwright build  pwm_driver.json -o layout.html
wrote layout.html  (24x10, 20 components)
ERC: 0 errors, 0 warnings

$ boardwright verify pwm_driver.json --netlist
# Perfboard Layout — 2-Channel PWM Driver
# 24x10 holes, 20 components, 11 nets
...
ERC
  ✓ clean -- every pin wired into its net, no shorts/floating/broken

$ boardwright verify pwm_driver.json --png ./layout
wrote ./layout_front.png  (via rsvg-convert)
wrote ./layout_back.png   (via rsvg-convert)

Example output

The bundled example (examples/pwm_driver.json) — a 2-channel low-side PWM driver — renders to this. Component side (parts seat on top):

Solder side (the board flipped down over its bottom edge; jumper wires go here — each hole sits directly under its front counterpart):

The real build output is a single self-documenting HTML page with both sides, a net legend, the ERC verdict, and hover/tap tooltips on every component.

---

Why it exists

Hand-wiring a perfboard from a schematic is fiddly and error-prone, and the "layout" usually lives only in your head or on a napkin. CAD tools (KiCad & co.) are heavy for a 30-hole proto and don't fit an agent loop. boardwright sits in the gap: a plain-text, version-controllable board description that an LLM can write and verify, producing a build sheet a human can solder from.

Install

pip install boardwright              # core (stdlib only)
pip install 'boardwright[png]'       # + cairosvg, for PNG export without librsvg

Or run without installing:

uvx boardwright build my_board.json          # uv
pipx run boardwright build my_board.json     # pipx
python -m boardwright build my_board.json    # after `pip install -e .` in a checkout

PNG export uses rsvg-convert if it's on your PATH (fast, zero Python deps — brew install librsvg / apt install librsvg2-bin), otherwise falls back to the cairosvg extra. HTML/SVG rendering and ERC need nothing beyond the Python standard library.

Usage

boardwright build  <board.json> [-o out.html]
boardwright verify <board.json> [--png [PREFIX]] [--netlist]

Command	What it does
build	Render the two-sided HTML layout (default <name>.html).
verify … --netlist	Print the netlist + ERC verdict. The authoritative what-connects-to-what. (Default if no flag.)
verify … --png PREFIX	Rasterise PREFIX_front.png / PREFIX_back.png to eyeball placement.

Both build and verify --netlist exit non-zero if ERC finds an error, so they slot straight into CI or an agent's check loop.

As a library

import json
from boardwright import render

spec = json.load(open("my_board.json"))
html, errors, warnings = render(spec)
open("layout.html", "w").write(html)

The board format

A board is one JSON object. The essentials:

{
  "title": "My Board", "subtitle": "what it is",
  "name": "my-board", "cols": 31, "rows": 7, "pitch": 26,
  "components": [
    { "ref": "Q1", "kind": "mosfet", "label": "IRLZ44N",
      "tip": "mosfet.nch", "pins": { "G": [10, 4], "D": [12, 3], "S": [14, 4] } }
  ],
  "nets": [
    { "name": "+12V", "pins": [["F1", "2"], ["JV1", "+"]] },
    { "name": "GND",  "pins": [["Q1", "S"], ["J1", "-"]], "external": true }
  ],
  "route": ["+12V", "GND"]
}

• Pins are absolute hole coordinates [col, row] — the engine never guesses geometry, so you place parts exactly where they'll sit.

• nets is the netlist: the source of truth. route lists which nets the auto-router should wire.

• kind picks the drawn glyph. Built-in glyphs: mosfet, diode, led, res, ccap, ecap, fuse, term.

• tip keys into the component-description library for hover tooltips.

• Footprints are real. One hole = 2.54 mm (0.1"). Leads sit the same number of holes apart as the physical part — note screw terminals are 0.2" pitch (two holes apart, three-hole footprint), not adjacent.

Full reference: docs/board-format.md. A complete worked example: examples/pwm_driver.json.

Start from a real board size

Blank templates sized to off-the-shelf perfboards live in boards/<brand>/<size>.json — copy one so your grid matches the board in your hand. Bundled: Elegoo 2×8 / 3×7 / 4×6 / 5×7 / 7×9 cm. Hole counts are brand-specific, so they're organised by brand — see boards/README.md to contribute your own.

Using it with AI agents

boardwright is designed so an agent can both write a board and prove it works. You can literally tell your agent: "install the boardwright skill/plugin and lay out my circuit."

Claude Code — install as a plugin (recommended)

This repo is a Claude Code plugin and a one-plugin marketplace. Add it once, install, and the boardwright skill auto-loads:

/plugin marketplace add naam/boardwright
/plugin install boardwright@boardwright

(or non-interactively: claude plugin marketplace add naam/boardwright then claude plugin install boardwright@boardwright.) The skill carries the engine with it, so it works offline immediately — no pip step required.

Or drop it in as a bare skill: copy skills/boardwright/ into ~/.claude/skills/ (personal) or .claude/skills/ (project).

Codex, Gemini CLI, Cursor & other agents

These read an AGENTS.md at the repo root — already included. Clone the repo (or pip install boardwright and point the agent at it); the agent picks up the commands and the iterate-and-verify workflow automatically. Nothing Claude-specific is required.

Why a skill, not an MCP server?

For a stateless file-in/file-out tool like this, a skill that shells out to the CLI is lighter and cheaper than a long-running MCP server — no per-session tool-schema tokens, no process to manage, and it works across every agent that can run a command. If you specifically want typed MCP tools, wrapping build/verify is a thin shim around the library API; see Roadmap.

The agent loop in one line: edit the JSON → verify --netlist (ERC) → verify --png (placement) → build (deliverable).

Roadmap

• More board substrates: stripboard / veroboard (track cuts) and solderless breadboard (power rails + tie-point columns).
• More brand/size templates under boards/ (contributions welcome).
• More glyphs (ICs/DIP, connectors, inductors, potentiometers).
• Optional MCP server exposing build/verify as typed tools.
• BOM export from the netlist.

License

MIT © 2026 Nahim El Atmani.