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.

Those cheap checks read the description, not the result, so mechanical documents
also get verify_geometry: it builds the part in a headless FreeCAD and
reports, per node, what the kernel actually made — solids, volume, validity. It
catches the whole class of features that fail silently (an impossible fillet
radius, a shell with no opening, a boolean whose operands miss) and names the
node that produced nothing. Pair it with preview_render, which now works
on mechanical documents: FreeCAD tessellates the built solids and the part is
drawn as iso/front/right/top engineering views, so critique_render can judge
it against the original request. verify_geometry says whether the part exists;
the render says whether it is the right part.

Mechanical parts also export to STEP — the ISO 10303 format every other CAD
package reads — and STL for slicers. These need FreeCAD installed, as does
verification and mechanical preview; .FCStd export does not, because it writes
the parametric recipe and lets FreeCAD build it on open. generation_status
reports whether the kernel is available.

Three helpers return ready-to-paste sketch geometry so profiles are not derived
by hand: calculate_rounded_rect (four lines plus four corner arcs that must
meet exactly, or the profile will not close), calculate_bolt_circle, and
calculate_slot.

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), 40 MCP tools, and 927 tests green. Shipped: the IR, validator, compiler pipeline, and REST API; three round-trips (KiCad, glTF, FreeCAD) plus OBJ/STL import, STEP/STL export, and a Blender script export that renders a finished product shot; geometry verification and preview for mechanical parts against a real FreeCAD kernel; 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.