ForgeLab

ForgeLab lets AI agents design hardware, mechanical parts, and 3D models — and export them to real tool files — without ever touching a proprietary format.

The LLVM of design. One JSON intermediate representation; every tool imports and exports it.

| Domain | Tool | | -------------- | ---------------- | | Hardware | KiCad | | Mechanical CAD | FreeCAD | | 3D / Game | Blender / glTF |

Install in 30 seconds

One line per agent. Each installs ForgeLab into ~/.forgelab/venv and registers the MCP server with that agent over stdio. They are interchangeable and safe to combine: all four point at the same install, so running two of them on one machine gives you one ForgeLab, not two.

Claude Code

curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install-claude-code.sh | bash

Codex CLI

curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install-codex.sh | bash

Hermes Agent

curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install-hermes.sh | bash

OpenClaw

curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install-openclaw.sh | bash

That's it. Restart the agent and ask it to design anything. To confirm the connection, ask it to call list_domains — it should answer hardware, mechanical, threed.

Any other agent

curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install.sh | bash
forgelab init

forgelab init registers with whichever agent you pick, and prints an mcpServers config block for agents with no CLI of their own.

Updating

forgelab update

Upgrades ~/.forgelab/venv to the latest commit and tells you what it moved between:

✔ ForgeLab updated — 0.1.1.dev288+gaaaaaaa → 0.1.1.dev292+gbbbbbbb.

No client-specific re-registration is needed: Claude Code, Codex, Hermes and OpenClaw all point at the same venv, so one forgelab update refreshes ForgeLab for all of them at once. Re-running any install one-liner does the same thing — the installers upgrade rather than reuse.

forgelab --version reports the build you are on and the document spec it implements.

What you can do

Just tell your agent what you want:

• "Design a wireless temperature sensor with ESP32, DHT22, USB-C power, and a 3D-printable enclosure"

ForgeLab produces a complete project: KiCad PCB + FreeCAD enclosure sized to fit the board + Blender product render script + BOM — all from one prompt, all dimensionally coherent via a shared project file.

How it works

native file ──import──▶ ForgeLab IR ──transform──▶ ForgeLab IR ──export──▶ native file
                          ▲                                        │
                          └──────────── AI agents ─────────────────┘
                                   (pure JSON, no proprietary formats)

Every tool imports its native files into one JSON IR and exports the IR back. Agents work entirely in ForgeLab JSON — no proprietary formats, no special training.

Tool support

| Domain | Tool | Import | Export | Notes | | -------------- | ------------- | :----: | :----: | -------------------------------------------- | | Hardware | KiCad | ✅ | ✅ | .kicad_pcb round-trip (components/nets/board), routed track/via export, copper-pour zones (KiCad fills them) | | Hardware | Altium | ❌ | ❌ | not planned — Altium's native format is closed/proprietary with no public spec; supporting it would mean depending on a paid SDK, which ForgeLab won't do | | Hardware | Gerber | 🚧 | ✅ | export RS-274X layer set + Excellon drill, zipped (F/B copper, mask, silk, outline) | | Mechanical CAD | FreeCAD | ✅ | ✅ | .FCStd round-trip (parts/bodies/features/sketches, loft/sweep/fillet/shell/revolve); STEP/STL export, geometry verification and preview with FreeCAD installed | | Mechanical CAD | Fusion 360 | ❌ | ❌ | not planned — Fusion 360 is cloud-only and requires an Autodesk account, which conflicts with ForgeLab's no-login, self-contained design | | 3D / Game | glTF | ✅ | ✅ | .gltf round-trip (meshes/materials/scene); translucent materials (base-color alpha < 1) export alphaMode: "BLEND" | | 3D / Game | OBJ | ✅ | | import .obj (+ companion .mtl); fan-triangulated, per-object meshes | | 3D / Game | STL | ✅ | | import ASCII or binary .stl (single mesh, default material) | | 3D / Game | Blender script| | ✅ | export tool='blender_script' → runnable .py product render (native objects + modifier stack, daylight-sky world, CYCLES/EEVEE PREVIEW toggle, 85mm 3/4 camera, ground plane, auto-render to PNG) | | 3D / Game | Blender | ✅ | ✅ | via glTF interchange; native .blend 🚧 | | 3D / Game | Unreal Engine | | ✅ | via glTF interchange — Unreal natively imports glTF, so export_document(tool='gltf') then drag the .gltf into the Content Browser; no dedicated exporter needed |

✅ implemented · 🚧 stub (base classes in place, awaiting implementation) · ❌ not planned

In the hardware domain, agents don't have to hand-guess XY coordinates: build the document with components and nets but rough (or no) positions, then call auto_place before validate_document/export_document. A shelf-packing algorithm sizes each component from its real pad geometry (plus a keepout margin) and packs everything inside the board outline — guaranteed zero overlap and zero components off the board. Large parts (QFPs/QFNs/modules, by footprint area) are kept away from the board edges (large_component_inset, default 5mm) so the autorouter keeps escape channels on all their sides — tuned empirically, this lifted the Arduino Uno example from 22 to 25 routed nets. Mark a manually positioned component "locked": true (e.g. an edge connector) and the rest packs around it; the returned board_utilization percentage signals when the board needs to grow. validate_document backs this up with a hard board-outline containment check: a component whose pad footprint extends outside the outline fails validation at document time — not after opening KiCad — and the error message points at auto_place as the fix.

Coordinate convention (hardware domain): the IR is Y-up — millimetres, origin at the board outline's lower-left corner, +X right, +Y up, rotation in degrees counterclockwise — the way a person naturally reasons about parts on a board. Format tools translate at the boundary, never inside the IR: Gerber output is natively Y-up and passes coordinates through unchanged, while KiCad files are Y-down, so the KiCad exporter/importer mirror Y about the outline's vertical centre (and negate pad-local offsets) on the way out and in — round trips stay exact. A dedicated test pins specific coordinates on both sides so a frame regression fails CI immediately.

The pipeline ends fab-ready: export_document(tool='gerber', output_path='board_gerbers.zip') writes a zip a fab house can accept — front/back copper (routed tracks, via annulars, flashed pad apertures), soldermask openings, silkscreen reference designators, board outline, and an Excellon drill file with a hole per via and per through-hole pad (round holes flashed, oval drills as routed slots) — validated against a real Gerber parser (gerbonara reads back every layer and recognizes the full stack). Run check_gerber_completeness first: it re-checks the fab rules on the routed geometry and warns if the board has no tracks yet. The full workflow: build → auto_place → route_board → check_fabrication → export_document(tool='gerber') → upload to JLCPCB/PCBWay/OSH Park.

After placement, route_board turns the netlist into real copper: a 2-layer grid-based maze router (Lee's algorithm) connects every net with track and via nodes that the KiCad exporter emits as actual (segment ...)/(via ...) S-expressions, and turns high-fanout power/ground nets it can't trace into filled copper planes (zone nodes → real (zone ...) pours that KiCad fills). Copper is modelled physically: pads obstruct the copper the exporters actually render (their explicit size, or a shared pitch-aware default for size-less pads), and vias are placed only where their real via_diameter barrel keeps clearance to every other net's pads, tracks and vias — a net with no legal path fails cleanly instead of getting shorted copper. check_fabrication then validates the routed geometry — not just the declared design rules — with real geometric clearance checks between every copper pair (track-track, via-pad, via-via, pad-pad, track-pad, track-via), the same collisions KiCad's DRC reports. The full hardware workflow is: build (or generate) the document → auto_place → route_board → validate_document → export_document(tool='kicad'). Set expectations correctly: this is a basic router for simple-to-moderate boards (the Arduino Uno / ESP32 dev-board range), not a replacement for a commercial autorouter on dense designs. Nets the maze search cannot connect come back in nets_failed for manual routing instead of failing the run — with one deliberate exception: a genuinely pour-shaped power or ground net (many pads fanned across the board, the signature of a plane, not a signal that merely lost to congestion) is turned into a filled copper plane instead, the way every real 2-layer board carries power and ground. On the packed Arduino Uno example, ~21 of 32 multi-pad signal nets route at the default 0.15mm grid, and the two highest-fanout nets — GND and +5V — are auto-poured as planes (GND on F.Cu, +5V on B.Cu, connecting straight to the headers' through-hole pads) and reported in nets_poured rather than landing in nets_failed. The router keeps tracks a board-edge clearance inside the outline and treats a through-hole pad as copper on both layers, so the export is DRC-error-clean — at the honest cost of a few edge-header nets that need manual routing. Reference designators are placed clear of every pad's solder-mask opening (and Value on F.Fab), and no via is drilled where a same-net through-hole pad's plated barrel already joins the layers. On that board kicad-cli pcb drc with the zones refilled reports zero errors and zero copper, silkscreen or drill warnings — verified in CI-skippable integration tests when kicad-cli is installed. The only violations left are 24 lib_footprint_* warnings, noted under known limitations below.

Known limitations (hardware domain):

• PCB layout only — no schematic. ForgeLab never produces a .kicad_sch schematic file. Nets and the ratsnest are embedded correctly in the exported board, but there is no schematic to view in KiCad's schematic editor.
• A pad is SMD unless you give it a drill. The Pad model has an optional drill ({diameter} for a round hole or {oval: [w, h]} for a slot, plated true by default) — set it and the pad exports as a real through-hole pad (thru_hole, copper on every layer, drilled in both the KiCad and Gerber/Excellon output); omit it and the pad is SMD exactly as before. The bundled library's genuinely through-hole parts (pin headers, the ICSP header, the JST connector) carry real drill diameters taken from their KiCad footprints, so a board built from the library needs no manual fix-up. Parts you author yourself default to SMD until you add a drill — and a through-hole pad only helps if its footprint is genu