English · Türkçe
Design circuits on perfboard the way you would on a PCB — then get a soldering guide you can actually build from.
Status: pre-alpha, and end to end. A netlist goes in and a soldering guide comes out: 2D editor, 3D view, placement optimiser, autorouter, DRC, LVS, the build guide, an exact 1:1 PDF export and an MCP server. What is missing is the dogfood test — nobody has yet built a real board by following a generated guide, and PLAN.md §11 says M5 does not close until somebody has. Everything else runs: v0.4.0 ships an installer for each of the three desktop platforms, none of them code-signed.
Take a schematic netlist, lay it out on pad-per-hole perfboard, let the router work out the connections, prove the result matches the schematic, and export a step-by-step build guide with measurement checkpoints.
Three things make it different from the tools that already exist:
- A soldering guide with verification steps. Not just "solder R1 here", but "block 2 complete → U1 pin 4 to C3(−) must show continuity" and "before power-on: GND to V+ must read above 10 kΩ". Derived from the netlist, so it is exact rather than generic advice.
- Perfboard LVS. The board's real connectivity is extracted and compared against the schematic. Opens, shorts and floating conductors are reported before you pick up the iron.
- Agent-native. An MCP server, a headless CLI and a git-diffable project file, all driving the same command bus as the GUI — so undo works across a session where a human and a model both edit the board.
Most tools model a perfboard connection as "a wire". Perfboard has six physically distinct ways to join two points, each with its own cost, limits and failure modes — and modelling that difference is what lets the router produce a layout that is pleasant to actually solder:
| what it is | notes | |
|---|---|---|
| lead bend | a component leg bent to a nearby hole | effectively free, 3–4 holes |
| solder trace | adjacent pads joined with solder alone | orthogonal only; ~0.6 mm to the next pad |
| solder trace, wired | the same, over a tinned-wire spine | ~10× lower resistance, no length limit |
| bare wire | tinned wire on the solder side | cannot cross another bare conductor |
| insulated wire | may cross freely | costs preparation time |
| top jumper | insulated jumper over the component side | visible, occupies body space |
The 0.6 mm gap to the neighbouring pad is why solder traces are both so useful and so easy to get wrong. PerfStudio scores that risk into the router's cost function, and turns every flagged spot into a measurement step in the build guide.
The solder side is where the copper is, so it is a first-class view rather than a mirror mode — and copper on the face you are not looking at is hatched, because a board is opaque and a trace drawn solid says this is in front of you.
The 3D view is a checking tool, not a picture. Three rules exist that a top-down view cannot see at all: a part too tall for the case, a jumper trapped under a body that will be soldered down on top of it, and a heat-sensitive part sitting too close to a hot one.
Parts go in shortest first — a tall part fitted early stops the board lying flat on the bench while the short ones are soldered. Then the board is turned over and the copper goes on, and ICs are last for heat and ESD. A jumper that would end up trapped under a part body is moved to the first phase, because by the time that part is down it is too late.
The animation turns the board over halfway through for the same reason you would: a perfboard is opaque, and fourteen of this build's twenty-two steps happen on the face you cannot see from above. It is generated by playing the guide back through the same function the 3D panel's assembly slider calls, so it cannot show an order the guide does not actually give you.
Requires Python 3.12+. The desktop app is PySide6 (Qt 6) with a VTK viewport.
git clone https://github.com/medinstech/perfstudio.git
cd perfstudio
pip install -e .
perfstudio # launch on a blank board
perfstudio some/board.perf # ...or open a document
perfstudio --versionOr install it: the releases page carries a Windows installer, a Linux AppImage and a macOS disk image, each built and smoke-tested by the tag itself. None of them is code-signed, so each warns on first run and the release notes say how to get past it — a Windows EV certificate is ~$300/year and Apple notarization $99/year. Running from source avoids the warning entirely. See docs/RELEASING.md.
The interface speaks English and Turkish (--lang tr, or follow the system locale).
In the app: File → Import KiCad Netlist on examples/ne555-astable.net, accept the
offered placement, Place → Auto-place Board (Ctrl+Shift+A), Ctrl+R to route,
then File → Export Build Guide (Ctrl+B). That is the exact sequence the screenshots
above come out of — see tools/screenshots.py.
You do not need KiCad: nets can be built by hand in the app or over MCP.
Four examples ship as both the netlist and the finished board:
perfstudio examples/lm317-supply.perf| what it is there to show | |
|---|---|
ne555-astable |
the starting point — a 555 flashing an LED |
lm317-supply |
a TO-220 regulator, so the heat rule has something to measure |
lpb1-booster |
built on FR-2, the phenolic board whose pads lift |
arduino-io-shield |
two headers, which is what a shield mostly is |
All four route to completion, match their schematics under LVS and carry no DRC error —
tests/test_examples.py asserts it on every commit.
The MCP server drives the identical command bus, so undo works across both:
pip install -e ".[mcp]"
claude mcp add perfstudio -- python -m perfstudio.mcpForty-four tools, every hole addressed the way people talk about perfboard (A1, C7,
AC12) and never as raw coordinates. See docs/MCP.md for the tool list,
the JSON config other clients want, and the rest of the setup.
Renders 2D/3D/PDF to files, runs DRC and LVS and prints timings, with no display. It is how the visual output is exercised in CI, and the fastest way to check that a rendering change did not crash:
python -m perfstudio.ui.main --headless tools/diffcheck/golden/dense.perfThe document is immutable and every mutation is a command dispatched through one
bus — which is what makes undo work across a mixed human/agent session. The engine is
pure: no clock, no RNG, no filesystem, no Qt or VTK below ui/. The placer's
annealing is seeded, so the same document and the same seed give the same board.
That purity is load-bearing rather than decorative. This Python engine is a port of the
TypeScript one still in packages/, and its acceptance criterion was never "the tests
pass" but "it produces byte-identical results to the implementation it replaces" —
golden fixtures in tools/diffcheck/, down to the last IEEE-754 double.
src/perfstudio/ the engine: document model, command bus, connectivity,
router, autorouter, placer, DRC, LVS, persistence
src/perfstudio/guide.py the soldering guide, and guide_export.py for HTML/CSV/JSON
src/perfstudio/stripboard.py the board whose copper arrives joined, and striproute.py
for the cuts-and-links planner that designs on one
src/perfstudio/parsers/ KiCad netlist importer
src/perfstudio/ui/ Qt application: 2D editor, VTK 3D view, 1:1 PDF export,
and headless.py, the no-display run CI checks the output with
src/perfstudio/mcp/ the MCP server (docs/MCP.md)
examples/ a netlist to import
tests/ 1363 tests; the engine is mypy --strict clean
packages/ the original TypeScript engine, kept as the reference the
Python port is proved against
The 61 THT footprints are generated from numeric parameters, not shipped as assets — no mesh library, no share-alike licence to inherit. The same spec that draws a part in 2D extrudes its body in 3D, so the two cannot disagree.
Done: the editor, the library, connectivity and LVS, DRC, the router and the placement
optimiser, the build guide with rendered step images and assembly playback, the 1:1 PDF
export, the MCP server, TR/EN localisation, and the three-platform packaging that a v*
tag runs.
Next, in the order PLAN.md §11 puts them:
- The dogfood build (M5). Somebody has to solder a real board from a generated guide. Until that has happened, every claim on this page is a claim about software rather than about a working circuit. It is also the one thing on this list that a stranger can do for the project — there is an issue template for it.
- Automatic updates. PLAN.md §14 asks for them and the installers do not have them: today an update means downloading the next release by hand.
- Code signing. A Windows EV certificate is ~$300/year and Apple notarization $99/year, so until then the installers warn on first run and the release notes say how to get past it.
Issues and pull requests are welcome. Please read CONTRIBUTING.md first — it covers how to run the suite, which checks are gates and which are not, and one licence boundary that matters more here than in most projects: do not read or port code from the GPL-licensed tools in this space. PerfStudio is clean-room with respect to them, and that has to stay true. The record is in docs/prior-art.md.