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.

Install in 30 seconds

Claude Code

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

That's it. Ask Claude Code to design anything.

Hermes Agent

Paste this prompt:

Install ForgeLab on this machine by running curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install.sh | bash. Then start the MCP server with ~/.forgelab/venv/bin/forgelab-mcp --transport streamable-http --port 8001 and confirm the tools are available by calling list_domains over that transport. Then tell me what domains are supported.

OpenClaw

Paste this prompt:

Install ForgeLab on this machine by running curl -fsSL https://raw.githubusercontent.com/andresparraarze/ForgeLab/main/scripts/install.sh | bash. Then add the stdio MCP server to your MCP configuration with the command ~/.forgelab/venv/bin/forgelab-mcp --transport stdio, verify by calling list_domains, and confirm what design domains are available.

Codex CLI

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

That's it. Ask Codex to design anything. Run /mcp inside a Codex session to confirm ForgeLab's tools are listed.

Updating

forgelab update

Updates the installed ForgeLab package in ~/.forgelab/venv to the latest version from GitHub. No client-specific re-registration is needed: Claude Code, Codex, Hermes, and OpenClaw all point at the same venv, so a single forgelab update refreshes ForgeLab for all of them at once.

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

✅ 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 genuinely through-hole (the bundled Arduino Uno keeps its SMD crystal and reset button on their real SMD footprints).
• Footprints are synthesized, not copied from the KiCad libraries. A ForgeLab footprint carries the pads, drills and reference designator that matter electrically, but not the courtyard, fabrication outline, silkscreen body or 3D model of the library part it names. KiCad therefore reports a lib_footprint_mismatch warning per part (24 on the Arduino Uno example) when it compares the board against the installed libraries. The board fabricates correctly; running "Update Footprints from Library" in KiCad replaces the synthesized bodies with the full library ones.

The mechanical domain covers both of FreeCAD's modelling styles. Use PartDesign (sketch/pad/pocket) for prismatic engineering parts — brackets, mounts, plates, enclosures — built by extruding and cutting closed 2D profiles. Sketch geometry is line, circle or arc. An arc is an open segment of a circle — center, radius, start_angle, end_angle in degrees counter-clockwise from +X, sweeping counter-clockwise (FreeCAD's own Sketcher convention) — whose two endpoints join adjacent lines the way two lines join each other, so a profile can be traced through a mix of both. That is what makes rounded rectangles, slots and filleted 2D outlines expressible directly instead of approximated with a circular cut: a rounded rectangle is 4 straight edges plus 4 corner arcs (see examples/mechanical/rounded_rect_plate.forge.json). Use the Part workbench (loft/sweep/fillet/shell/revolve) for organic or curved shapes — grips, handles, knobs, ergonomic surfaces — where the exported file carries only the feature description and FreeCAD's own OpenCASCADE kernel computes the real NURBS geometry on recompute. Choose loft for asymmetric shapes whose cross-section changes along a path (see examples/mechanical/organic_grip.forge.json); choose revolve for axially-symmetric round shapes — knobs, caps, bottle-like grips — where one closed profile spun around an axis is easier to specify correctly than stacked loft sections (see examples/mechanical/rounded_knob.forge.json).

Both of those toolkits build geometry inside a single body's feature chain, which is why neither can express an assembly: a pad cannot reach into another body, and a pocket only cuts material its own body already built. A boolean node is the one feature that spans bodies — union, cut or common between solids modelled entirely independently. Reach for it when the shapes have separate identities: a base plate and a mounting boss, a housing and a lug, a part and a cutting tool that is itself a modelled solid rather than a sketch profile. Model each piece in its own body, then combine (see examples/mechanical/bracket_with_boss.forge.json). Keep using pocket for an ordinary hole or recess in one body — a boolean is the wrong tool for that, and heavier. union and common accept several tools in one operation; cut takes exactly one, because FreeCAD provides Part::MultiFuse and Part::MultiCommon but no multi-tool cut. One caution the validator helps with: FreeCAD reports no error for a boolean that produces nothing — an empty intersection or a cut that misses recomputes to a valid, up-to-date result holding zero solids — so check_mechanical warns when a cut's tool cannot reach its base.

Threed materials can carry image textures — the surface detail (wood grain, brushed metal, woven fabric) that a flat PBR colour cannot express. A material takes an optional base_color_texture, a path to an image resolved relative to the document's directory, and the image is embedded in the exported .gltf as a base64 data URI, so the file stays as self-contained as it already was for geometry. Colour and texture multiply rather than replace — that is glTF's own rule (baseColorFactor is defined as a "linear multiplier for the sampled texels") — so a white base_color shows the image unchanged and a coloured one tints it.

A texture needs somewhere to land, so every primitive that uses a textured material must carry uvs: a flat [u, v] array with one pair per position, packed the same way positions are. UV origin is glTF's — top-left, V increasing downwards; the blender_script exporter flips V on the way out, exactly as Blender's own glTF importer does, so both exports place the image identically. A textured material on a mesh with no UVs is a validation error, named at validate_document time rather than left to render wrongly. Omitting uvs changes nothing for untextured documents, whose exports are byte-for-byte unchanged. For a box, use cube projection — each of the 6 faces gets its own 4 corners (24 vertices, not 8) so each can span the full image; see examples/threed/textured_crate.forge.json. One limitation: the glTF importer reads UVs back but not texture references, since the original file path is not recoverable from an embedded image.

In the threed domain, objects can carry a Blender modifier stack — an ordered modifiers list of subsurf, bevel, boolean and solidify entries that the Blender script exporter compiles to native obj.modifiers.new(...) calls (boolean targets are created first via a dependency sort and hidden from render). Blender's own modifier evaluation computes the real smooth geometry when the script runs, so agents describe organic shapes as primitives + modifiers instead of hand-computing triangles: cube (or cylinder) + subsurf + bevel is the go-to pattern for a smooth rounded shape, and a boolean difference carves indents and cutouts (see examples/threed/organic_handle.forge.json).

Render-critique loop for iterative refinement

Agents can now see what they built and fix it without Blender installed or a human checking screenshots. preview_render (the preview extra: matplotlib + numpy, pure pip) renders a document's triangle meshes flat-shaded from three angles into one PNG; critique_render sends that PNG — plus an optional reference image — to the vision model with the design intent and returns structured feedback. ForgeLab provides the primitives; the calling agent drives the loop:

preview_render("car.forge.json", "car.png")
critique_render("car.png", "a low-slung sports car with a long hood")
  -> {"matches_intent": false, "score": 6,
      "issues": [{"severity": "critical",
                  "description": "only three wheels are visible",
                  "likely_cause": "missing rear-left wheel object"}],
      "suggested_changes": ["add a fourth wheel at the rear-left"]}
patch_document(...)          # apply the suggested changes
preview_render(...)          # re-render
critique_render(...)         # re-judge; repeat until the score is acceptable

Previews draw the baked triangle geometry (modifier stacks are evaluated by Blender, so they show the base meshes). Check generation_status first: preview_render needs pip install "forgelab[preview]", and critique_render needs ANTHROPIC_API_KEY plus the agent extra.

MCP tools

Thirty-six tools, same for every client. Over stdio all are local; over HTTP each needs its scope on the bearer token.

Read

Edit

Project

A .forge.project file ties multiple domain documents together with a shared dimension table (one source of truth) and informational cross-domain constraints.

Calculate

Export

Generate

Token optimization

• Work by file path. validate_document and export_document take a document_path; agents write a document once and process it by path — no large JSON in context.
• Edit by patch. patch_document applies an RFC 6902 JSON Patch, so changing one component is a few hundred bytes, not a full re-emission.
• Project what you need. Pass projection (metadata/topology/geometry/full) to receive only the relevant slice; stripping happens server-side.
• Compute, don't guess. The five calculate_* tools handle geometry and electrical math deterministically instead of inline.
• Project files. Tie board, enclosure, and render documents together with shared dimensions as a single source of truth; export all formats in one call via export_project.

Project status

Pre-alpha (library v0.1, spec v0.5.0). Three working domains (hardware, mechanical, 3D), 36 MCP tools, and 692 tests green. Shipped: the IR, validator, compiler pipeline, and REST API; three round-trips (KiCad, glTF, FreeCAD) plus OBJ/STL import and a Blender script export that renders a finished product shot; the project concept (shared dimensions across board + enclosure + render, exported in one call); a component library of 32 pre-built parts with datasheet pad geometry; the AI SDK, the OAuth 2.0 module, and the MCP server. The one remaining tool integration is Gerber import (a scaffolded stub). Altium and Fusion 360 are not planned (closed proprietary format / cloud-only with mandatory account — see Tool support), and Unreal Engine needs no integration: it natively imports the glTF that ForgeLab already exports. APIs may change before 1.0.

Roadmap

• Core IR, validator, registry, compiler pipeline; AI SDK + REST service
• KiCad .kicad_pcb, glTF .gltf (Blender), and FreeCAD .FCStd round-trips
• OAuth 2.0 auth + MCP server (stdio + Streamable HTTP)
• Multi-tool workflows + zero-friction agent setup (installer, forgelab init, bootstrap prompts)
• Publish to PyPI so pip install forgelab works without cloning
• Hardware: Gerber import · 3D: glTF textures/animations, .glb (Unreal Engine already works today via glTF export — no dedicated exporter needed; Altium and Fusion 360 are not planned, see Tool support)
• Transform passes (design-rule checks, layer remaps) over the IR; HTTP /import endpoint

Planned domains — new vocabularies and compile targets beyond the current hardware/mechanical/3D trio:

• Robotics domain — URDF/ROS output: link/joint/sensor vocabulary compiling to URDF files for robot kinematic simulation in ROS alongside FreeCAD mechanical models
• Microfluidics domain — lab-on-a-chip design: treat mixers/reservoirs as components and fluid channels as traces, compiling to Gerber files for photomask lithography (natural extension of the hardware domain)
• BIM domain — building information modeling: wall/floor/door/window/room vocabulary compiling to IFC for architectural floor plans, structural framing, and MEP system routing

Contributing

See CONTRIBUTING.md. The highest-leverage start is an importer/exporter for one tool against the Importer/Exporter base classes — the KiCad pair is a complete worked example.

ruff check . && ruff format --check . && pyright && pytest

License

Apache 2.0.