The problem

Perfboard is the quickest way to turn a breadboard prototype into something that lasts: an Arduino Nano, a couple of breakout modules, a few resistors and connectors. The hard part is the layout. Every wire has to fit between the holes, it can’t cross a pin you have already soldered, and the order you solder things in suddenly matters.

Most people plan it on squared paper or in a spreadsheet. PCB tools can do it, but they were made for something else and don’t understand a board where you solder every wire and bridge by hand.

The usual way

Sketch the layout on paper, count holes, rub out and redraw, and hope you didn't miss a connection before you pick up the soldering iron.

With Perfboard Designer

Place parts on a hole-accurate board, let the router suggest wire runs, and ask your coding agent to finish, check and tidy up the layout while you watch.

Built to be shared with an agent

The core idea is that a human and an AI agent are equal participants in the same design. Both go through the same Rust engine, the same validation and the same history, so there is one source of truth and nothing to import or export.

1. OpenStart the desktop app and open your design. It announces itself to local MCP clients and to nothing else.
2. AskIn Claude Code or Codex, describe what you want: "connect the RS-485 module to the Nano's serial pins and route the RJ45 jacks".
3. ReviewAgent edits appear on the board as they happen, marked in the history with the agent's reasons. You accept, undo or commit.

The solder side of an Arduino Nano RS-485 node with two RJ45 jacks, mirrored as you see it when you flip the board: the parts library on the left, the bridges and wires in the middle, and the inspector with Problems and History on the right.

The MCP server gives the agent the same tools you have, and no more:

Read the design

The full project, the board, the parts library with each part's documentation, the validation report, the assembly plan and a rendered picture of either side of the board.

Edit it

Place, move and rotate parts, create, rename and merge nets, draw wires, bridges, rails and saddles, all as grouped operations that land as one step in the history.

Route with the engine

Ask the deterministic router for suggested wire runs, or have it evaluate a route the agent drew itself before committing to it.

Keep a history

Commit named checkpoints with a description, compare any two revisions and restore an earlier one, just like the History tab.

You stay in charge

An agent is good at electronic common sense and tedious routing. It is not the one holding the soldering iron. So:

• Electrical changes need your approval. Connections an agent proposes show up under Needs your approval in the Nets panel and stay inactive until you accept them. Routing nets you have already approved is just layout and doesn’t ask again.
• No lost edits. Every write must quote the revision it was based on. If you changed the board in the meantime, the agent’s write is refused and it has to look again, so neither side overwrites the other.
• Agent steps are visible. They are marked in violet in the History tab, with the rationale the agent gave, and undo like any other step.
• A narrow door. The bridge listens only on the local loopback interface and authenticates every request with a token created for that launch. It offers no file or shell access.

House rules in plain English

Because the agent reads your instructions as well as the board, you can hand it the conventions you build by. These are the rules used for the Nano RS-485 example:

1. Run every wire from an empty perfboard hole to an empty perfboard hole.
2. To connect a wire to a component pin, end the wire in a neighbouring empty hole and bridge the gap after the other soldering is complete.
3. Route wires only horizontally or vertically, with 90-degree bends.
4. Don’t route a wire across a soldered component pin.

The engine checks the geometry; the agent applies the judgment.

Also a good editor on its own

Perfboard Designer is fully usable without an agent.

Hole-accurate board

Parts snap to the 2.54 mm grid. Switch between the component side and a mirrored solder side, exactly as the board looks when you flip it over.

Wires, bridges and rails

Draw wires pin to pin with bends where you click. Unrouted connections show as dashed lines; click one for a suggested route. Rails take their own colour and connection nodes, and saddles tie wire bundles down to the board.

Nets that stay tidy

Rename nets, remove unused ones, or merge two into one. A jumper can be left open or shunted, and a shunt can join two nets, as a selector jumper does.

Problems with advice

Overlaps, out-of-bounds parts and unrouted nets are listed with advice, and clicking a problem frames it on the board.

Your own parts

The Part designer edits body outlines, pins, keepouts and documentation. Parts are plain TOML and Markdown files you can keep in Git.

Ready for the bench

Step through the build in Assembly mode, print a build drawing with the wire list and a build-order checklist, and export true-scale wire guides (see below).

Local files

A design is a single human-readable JSON file. No account, no cloud.

From screen to solder

A layout is only useful once it is on the board, and on perfboard the order you build in matters: a wire that runs under a part has to go in first, a bridge can only be made once everything that ends in its holes is soldered, a rail before the wires soldered to it. Perfboard Designer works that order out for you.

A build plan, step by step

The app derives an assembly plan from the design: one step per part, wire, rail, bridge and saddle, followed by checks. Physical dependencies come first, each with the reason it was added. Within them, it follows the usual bench habits: flat wires and rails on the component side, then small parts, smallest first, then larger ones, then the solder side, bridges last. The same design always gives the same plan, and it updates as soon as you, or an agent, change the board.

Assembly mode

A third workspace next to the editor. The board shows only what is installed up to the current step, with the holes for this step ringed, and flips to the face you are working on. Press Enter to tick a step and move to the next one.

Everything for the step

Instructions, notes, the steps it comes after, and for wires and rails the colour, net, approximate cut length, bends and endpoints, plus a fitting jumper from your inventory when there is one.

Checks before power

The last steps ask for a look at the solder side, a continuity test per net and a short test between supply and ground. Pick a measurement and the board lights up its net and rings the pins to probe.

Progress that keeps up

Checkmarks are kept per project, outside the design file. If you change a step you already ticked, it is flagged, and a banner says what the edit added, changed or removed in the plan.

Assembly mode on the Nano RS-485 example, at step 24 of 83. The five wires that run under the Nano went in first, and the panel on the right lists them under Comes after, each with the reason. The solder-side wires (marked S) and the bridges come next.

Agents can read the same plan through MCP, so you can ask yours to explain the order or to suggest a layout change that makes the board easier to build. They read it; they don’t reorder it behind your back.

On paper

File → Print build drawing puts the plan on paper for the bench, or for handing the build to someone else: both faces of the board, the wire list in the order the wires go in, with estimated cut lengths and a tick box for each, and a build-order checklist with every step and a box for each continuity measurement. Steps you have already ticked in the app print as done.

Wires cut and bent to size

File → Export wire templates… turns every wire and rail in the design into a PDF you print and build from, at exactly 1:1:

Cut guide

Every wire laid out straight in its own column on a millimetre grid, in its insulation colour, with both cut lines, the strip marks and a triangle with the angle at each bend. Hold the wire against it as it comes off the spool, mark it, and cut. Rails also show where to strip the insulation for each connection point.

Bending templates

Each wire shape drawn full size over the board's hole grid, every run dimensioned in millimetres and in hole pitches. Lay the cut wire on its template and bend it to match. Wires with the same shape share one template.

From the Nano RS-485 example: the cut guide (left) and the bending template for wire W2 (right), both at actual size on paper.

It is a PDF rather than an ordinary print because true scale is surprisingly fragile: the app’s web view and many PDF viewers quietly resize printed pages. Print it with Page Scaling set to None (or Actual size), then check the 50 mm bar at the top of every page.

Where it stands

Perfboard Designer is in its first public development series (0.1). It has reached what I’d call a minimum usable product: you can design a real board from start to finish, by hand or with an agent, and then build it step by step from the screen or from paper. It is still very much in development, and file formats and tools may change.

• Platform: developed and tested on Linux. The code is written to be portable, but macOS and Windows haven’t been tried yet.
• Agents: Claude Code and Codex are configured in the repository. Other MCP clients that speak stdio should work, but haven’t been tested.
• Parts library: a small starter set (Arduino Nano, resistors, RS-485 breakouts, RJ45 jacks, Dupont pins and jumpers), plus the Part designer for your own.

Not there yet: a larger parts library, a place to keep parts of your own with each project, and creating parts through MCP, which agents can only read today. The build order is a heuristic: it follows the physical dependencies but doesn’t model whether the iron can reach a joint between tall parts, and where two wires cross on the same side without a recorded choice, it leaves their order to you. Assembly checkmarks are stored on the computer, so a build continued on another machine starts from the printed checklist. Passing validation means the geometry and connections are consistent. It is never a guarantee that a circuit is electrically correct or safe.

Get started

There are no prebuilt downloads yet: you build it from source. You need Rust 1.90 or newer, Node.js 22 or newer, the Tauri 2 system dependencies and the Tauri CLI.

1. Build and run

cargo install tauri-cli --version '^2' --locked
git clone https://github.com/arturormk/perfboard-designer-rust.git
cd perfboard-designer-rust
./quickstart.sh
./target/release/perfboard-designer

The app opens on an empty perfboard, ready for your own project. Pick parts from the library on the left and click a hole to place them, or use File → New board… to choose another size first.

2. Connect your agent

Keep the app running and start your agent from the repository folder. It picks up the checked-in MCP configuration and asks you to trust it on first use.

# Claude Code reads .mcp.json
claude mcp get perfboard-designer

# Codex reads .codex/config.toml
codex mcp list

The first start compiles the MCP server and can take a minute. Then ask away: “what’s on the board?”, “route the unrouted nets”, “check the design for problems and fix them”.

Learn more

• README: building, the editor, the Part designer and MCP setup in detail.
• Blueprint: the product scope, the design principles and what it deliberately isn’t.
• MCP session bridge: how the agent reaches the running app, and the security boundary.
• Issues: bug reports and ideas.

Perfboard Designer is licensed under MIT. It was built with AI coding agents: Codex designed and wrote the Rust engine, the MCP server and the first UI, and Claude Code reworked the UI into the editor you see above.