Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 12 min read

Boardwright: letting Claude design a circuit board, and not trusting it

You have probably caught an AI model being confidently wrong about code. With code, the damage is a failing test. With a circuit board, it arrives weeks later in the post: boards that cannot work because a pin was wired

Boardwright: letting Claude design a circuit board, and not trusting it

You have probably caught an AI model being confidently wrong about code. With code, the damage is a failing test. With a circuit board, it arrives weeks later in the post: boards that cannot work because a pin was wired to the wrong place. On a board that plugs into the wall, a mistake can hurt someone.

Boardwright is my answer to that. It is a free, open-source plugin for Claude Code, plus a small add-on for KiCad, the free circuit-board design program. You describe the board you want. Claude chooses the parts, draws the circuit, lays out the board and makes the files a factory needs. At every step, Boardwright checks the work, and if a check fails, the work stops until the problem is fixed.

This post explains how it works, using a real board that went through it, problems included.

The problem: AI can draw a board, but you can't take its word for it

A language model can read a datasheet (the manufacturer's document listing a part's pins and limits), pick a regulator and place components. What it cannot do reliably is know when it is wrong. It may misread a pin from a badly extracted PDF table, guess a value it never saw, or quietly relax a rule to make an error go away.

So the design of Boardwright starts from one rule: the AI is never the one who decides that the work is correct.

The idea: Claude designs, Python checks

The whole system fits in four sentences from the plugin's README:

Claude does the design work. Small Python programs check it. A stage only counts as done when its checks pass. If a check fails, Claude goes back, fixes the cause and runs the check again.

And one more that matters most: it never switches a check off to make it pass.

The design, check, fix loop: Claude does the work, a Python check runs, on a pass the stage is done, on a fail Claude stops, shows the report, fixes the cause and reruns the same check

The skill file that instructs Claude has a short list of "rules that never bend". The main ones: never invent a part number, pin or datasheet value (write "unverified" and cite the file and page instead); never disable, filter or loosen a check, but list a proposed waiver that only the user can approve in chat; when a check (a gate) fails, stop and show the report; never order, upload or publish anything; and never describe a check that did not run as passed.

Each check is an ordinary Python script you can run by hand from the project folder. It prints a short result, writes the details to reports/, and ends with an exit code: 0 passed, 1 a check failed, 2 something is missing in the setup.

Eight stages, each ending in a gate

The work is split into eight stages. Each one ends in a gate: a check that must pass before the next stage starts.

The eight stages in two rows: Spec, Parts, Power, Schematic, then Layout, EMC, BOM, Release. Each box shows its gate. Dashed red arrows show that a failed BOM gate goes back to choosing parts, and a failed EMC gate goes back to routing the critical tracks

Under the hood the stages are a graph of 62 small steps in pipeline.json, each marked as work for the model, a script, a helper, the user, or a gate. A planner script (plan.py) prints what is ready now, what waits on you, which gates failed and where to go back to. If you edit the board after a stage passed, the steps that depended on it are marked "reopened", because their evidence is now older than the design.

Guided mode asks plain-language questions and stops after each stage to explain; Express mode stops only when a check fails or a decision is yours. Both run the same checks. Routine jobs go to helper agents on cheaper models (reading a datasheet, looking up stock, drawing tracks Claude already planned), and a gate-reviewer helper on the strongest model gives a second opinion before a stage counts. Design decisions are never handed to a helper.

What gets checked

KiCad already has two built-in checks: ERC (electrical rule check: unconnected pins, outputs wired together) and DRC (design rule check: tracks too close, missing connections). Boardwright runs both at every stage, and adds its own checks on top. A few examples.

Mains safety, measured two independent ways

A board that plugs into the wall has a dangerous side (connected to the mains socket) and a safe side (the part you can touch), separated by an isolation barrier. Two distances across that barrier must be big enough: clearance, the shortest path through the air, and creepage, the shortest path along the board's surface, where dirt and moisture can let current creep across.

Mains safety spacing: boardwright.json feeds spacing.py, which computes the required distances. Check A writes them as KiCad rules and lets KiCad's DRC enforce them. Check B, barrier_check.py, measures the shortest copper distance across the barrier itself. creepage_rules.py fails if either finds a problem or if the two disagree

Here is how Boardwright handles it:

  1. You describe the board's safety situation in boardwright.json: mains voltage, pollution degree, altitude, board material, which nets are dangerous, and where the barriers are. (A net is one electrical connection: everything wired together.)
  2. spacing.py works out the required clearance and creepage using the IEC 60664-1 method. KiCad has its own calculator; Boardwright studied it rather than copying it, and makes one deliberate difference: creepage always takes the next table row up, instead of interpolating.
  3. Check A: creepage_rules.py --write adds those distances as rules at the end of KiCad's rules file, so KiCad's own DRC enforces them.
  4. Check B: barrier_check.py ignores KiCad's rules and measures the shortest copper-to-copper distance from the dangerous side to the safe side on every layer, itself.
  5. creepage_rules.py then fails if a rule is missing or weak, if the DRC result is older than the board, if KiCad is older than 10.0.6 (earlier versions had creepage geometry bugs), if DRC found a violation, or if the two checks disagree.

Why measure twice? Because a wrong rule fails quietly: a rule aimed at nets that don't exist gives a perfectly clean DRC. (A separate "rule guard" also checks that every net class matches real nets.) mains_check.py checks the circuit too: fuse first on the line input, safety-rated "X" and "Y" capacitors in the right places, and a fast enough discharge after you unplug.

Radio interference (EMC)

EMC (electromagnetic compatibility) is whether a board gives off too much radio noise. Only a lab can measure it, so this stage is a risk estimate from geometry. emc_rules.py, modelled on the rule lists commercial checkers publish (no code taken), flags fast tracks over gaps in the ground copper, layer changes through a via (a small plated hole) with no ground via nearby, cable connectors wired straight to a chip with no protection part, and fast tracks near the board edge. emc_harmonics.py lists which clock frequencies to test first.

Fast signals such as USB

USB sends data over a pair of wires that must arrive in step; the length difference is called skew. hs_rules.py writes KiCad rules for skew and length, then, because KiCad's skew rule groups nets oddly on some versions, measures each pair itself: length including via barrels, skew in mm and picoseconds, and matching via counts. impedance_check.py estimates each fast track's impedance; USB expects about 90 ohms between its two wires.

Power: enough capacitors near the chips

Small decoupling capacitors next to each chip's power pin supply quick bursts of current. pdn_check.py works out each rail's target impedance (voltage Γ— ripple Γ· current step) and checks that its capacitors stay under it from 100 kHz up, and it says what it doesn't model (mounting inductance, planes, the regulator itself).

The KiCad chat button

You can drive everything from Claude Code in a terminal with commands such as /boardwright:pcb-new guided and /boardwright:pcb-run. But there is also a speech-bubble button on KiCad's PCB Editor toolbar that opens a chat window next to the board you have open.

Architecture: the KiCad button opens a separate chat window, which talks to the user's own Claude Code over stdin and stdout using the stream-json protocol. Claude Code loads the Boardwright plugin, whose MCP servers edit the board through KiCad's IPC API and run DRC, ERC and exports through kicad-cli. Claude Code runs the Python checks in the project folder, which write to reports/

How the pieces connect:

  • The button runs launch.py, which finds the open board's folder and opens the chat window. The window is a separate program, so a slow answer can never freeze the editor.
  • The chat window starts your own Claude Code as one long-lived process per chat and talks to it over the stream-json protocol, the same one the Claude Agent SDK and the VS Code extension use. Streamed text, a short line for each tool call, and permission requests all come back through it. When Claude wants to change something, Allow, Always allow and Deny buttons appear.
  • Sign-in is always Claude Code's own browser flow. The add-on never asks for, reads or stores a password, API key or token. Every message uses your own Claude plan.
  • The plugin gives Claude the stage graph, the helpers and two MCP servers (MCP is the protocol Claude Code uses to call external tools). kicad-live edits the open board through KiCad's IPC API, so every edit lands as a normal undo step, and runs DRC, ERC and exports through kicad-cli, KiCad's headless command-line tool. kicad-schematic works on the schematic.
  • No extra Python packages. KiCad installs add-on packages with pip, which can hang forever in KiCad 10.0.8 when the Documents folder has a non-English name. So the add-on finds the open board from the window title and KiCad's recent-files list instead.

A worked example: a USB temperature and humidity sensor

The repository includes a complete example: a small board, about 30 Γ— 40 mm, powered and read over USB-C. A 3.3 V regulator powers an STM32 microcontroller, which reads an I2C temperature and humidity sensor and reports the readings to a computer as a serial port. It is meant for outdoor or humid places. Every stage report is in the example folder.

3-D view of the finished example board, rendered by KiCad: STM32 microcontroller in the middle, USB-C connector on the bottom edge, headers on the top and right edges, four mounting holes

The render shows the bare board and footprints, without 3-D part models.

The front copper layer of the example board as exported by kicad-cli

The schematic of the example board: USB-C connector, ESD protection, fuse, 3.3 V regulator, STM32F042 microcontroller, AHT20 sensor, buttons, LEDs and headers

Here is where each gate ended up at release:

Gate results for the example board: Spec, Power, Schematic, Layout and EMC passed; Parts and BOM did not pass and stayed open by the user's decision; Release made the files plus a checklist

It did not go perfectly, and that is the useful part. Some of the things the checks and reports caught:

Two parts that could not be bought. Between stage 2 (14 November) and stage 7 (15 November), stock changed under the design. The microcontroller, U1, fell from 16 to 3 pieces in LCSC's own stock, against 5 needed. R3, a plain 10 k resistor that pulls the boot pin low, went from 8,400 in stock to zero. The BOM gate failed and the run stopped. The report lists the options (wait for a restock, pick a substitute that goes back through stage 2, or check JLCPCB's own assembly library) and proposes no substitute, because the one candidate it checked was also out of stock. I chose to go on to release with the gate open, and the release report says so in its first lines: "Do not order from these files until the checklist below is worked through."

The regulator's schematic symbol is not quite the regulator. In stage 2, the regulator U2 (an AP2112K-3.3) had its pin table checked against its datasheet and against KiCad's AP2112K-3.3 symbol: a match. But the schematic tool cannot place KiCad's "derived" symbols, so the schematic uses the base symbol they are derived from, which is named AP2204K-1.5. The same thing happened for U1 and the ESD part U4. The real part names are in the Value and part-number fields, and the pins are shared, but a symbol named after a different regulator is exactly what a person should look at. It is on the release checklist as an item to confirm against the datasheets, not hidden. Separately, sch_check.py warned that U1's and U2's datasheet files are matched by family name, not exact part name.

Unverified things stay unverified. The stage 2 gate stayed open on three items (the boot pin's polarity was read online, not from a file on disk; the sensor footprint was drawn from a package drawing; a 10 Β΅F capacitor was not in the catalogue on file). Each went into the release checklist instead of disappearing.

The second-opinion helper refused at first. The gate-reviewer helper's first verdict on the release report was "gate must not count yet". Two stage 2 items were missing from the checklist, and a power-up step referred to a test point that does not exist on the board. Those were fixed and folded in.

EMC findings, with severities. The geometry check measured 16 rows with nothing CRITICAL. One MEDIUM finding: one of the connector's Dβˆ’ pads reaches the ESD protection part through two vias, where the guide says no via before the ESD part. Fixing it needs a different ESD part or connector footprint, which is a schematic change and the user's decision, so it was listed rather than quietly "fixed". The USB pair itself was measured at 10.9 mm on each wire. The report also notes that a 90-ohm pair can't be made with 0.25 mm tracks on a 1.6 mm two-layer board, and that full-speed USB (12 Mbit/s) over 11 mm does not need it.

Honest about who decided what. Stages 5 to 8 ran unattended under a standing instruction. Every decision Claude made in that run (board outline, connector positions, via size, placement) is recorded in PROJECT.md as "decided by Claude … NOT reviewed by the user", and repeated at the top of the release checklist for review.

A retrospective then proposed improvements to the plugin itself. For example, the layout gate ran three times before passing because copper pours made through KiCad's API got different thermal settings from pours made another way, so a check for that is now proposed.

Honest limits

Straight from the roadmap and README:

  • Boardwright does not make a board safe or certified. Its reports help a qualified person check the design. They are not a safety certificate or a lab test. Mains boards can kill; a qualified person must check them before they are switched on.
  • The safety distances are not yet checked against the official standards. They come from published summaries of IEC 60664-1 and IEC 62368-1, and the reports mark them "secondary source" until someone checks them against the purchased standards.
  • No tester has designed a new board from scratch yet. Two real boards have been through the pipeline (a mains power supply and this USB sensor). Each check has tests, and a full review runs end to end through Claude.
  • Interference and many safety properties can only be measured on a built board. The EMC stage is a risk estimate.
  • Not covered yet: built-in simulation (you can export for tools like HyperLynx and CST), 3-D clearance over part bodies, coated boards, inner-layer safety rules, and 4+ layer boards with controlled impedance. Stock checks are automatic for LCSC only. Mac is untested; it is tested on Windows 11 and Ubuntu 24.04 with KiCad 10.0.8.

Try it, and help test it

You need KiCad 9 or 10, Claude Code with a paid Claude plan or an Anthropic API account, and Windows 11 or Linux.

On Windows (PowerShell):

irm https://raw.githubusercontent.com/Pratham7767/Boardwright/main/install/install.ps1 | iex

On Linux:

curl -fsSL https://raw.githubusercontent.com/Pratham7767/Boardwright/main/install/install.sh | bash

The installer asks one question, installs whatever is missing and asks you to sign in to Claude. The last step is in KiCad: Plugin and Content Manager β†’ Install from File..., then pick the file the installer shows you.

Then make an empty folder, open it in Claude Code, and type:

/boardwright:pcb-doctor
/boardwright:pcb-new guided

Describe your board in a sentence or two and answer the questions. If you already have a board, /boardwright:pcb-review runs the checks and writes a report without changing anything, and /boardwright:pcb-gates runs every check and changes nothing.

I'm looking for testers. The top item on the roadmap is someone designing a first board from scratch and reporting what went wrong. If you try it, please open an issue with the Tester feedback form on GitHub: github.com/Pratham7767/Boardwright. It's MIT licensed, and it will never order, upload or publish anything for you.

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.