BrickForge 开源：用 Claude 把描述或照片转成可拼装的积木模型

Describe a model, or attach a photo, and BrickForge designs it in interlocking bricks that can really be built: every part sits on studs, nothing floats, and you get a 3D view, step-by-step instructions, a parts list and LDraw files for other brick-building software.

Claude (Anthropic's model) does the designing. BrickForge plans a large model as a tree of smaller sub-builds, reuses finished pieces from a growing component library, checks everything with its own validator, and sends the problems back to Claude until the model is valid.

BrickForge is an independent project. It isn't affiliated with, sponsored by or endorsed by the LEGO Group; LEGO® is a trademark of the LEGO Group.

Inspiration

This started from the Claude Opus 5.5 launch clip, which showed a model designed in connected bricks, with a full instruction manual, but not how it worked. From the footage I inferred a compile step and a connection checker, and the video's description later confirmed both. My first version missed that the designs were split into smaller, repeatable builds; spotting that led to sub-builds and the component library.

Screenshots

A park scene on its baseplate (High detail, $0.68)	A canal street built mostly from library components ($1.12)
A sports car from a photo, next to the photo	A clock tower sub-build

The renders above are the exported models opened in LeoCAD.

Getting started

Desktop app

Download BrickForge for your system from the Releases page:

Your API key. On first launch a welcome screen asks for an Anthropic API key. BrickForge checks it with a free API call and stores it only on your computer, in the app's data folder (on Linux and macOS the file is readable only by you). It's sent only to Anthropic. Change it any time with the gear button. No build of the app contains a key: the packaging script refuses to package anything that looks like one.

Unsigned builds. The app isn't code-signed, so your system warns you the first time you open it:

• Windows (SmartScreen): "Windows protected your PC" → More info → Run anyway.
• macOS (Gatekeeper): "BrickForge can't be opened because Apple cannot check it…". Open System Settings → Privacy & Security, scroll down and click Open Anyway. Alternatively, Control-click the app in Finder → Open → Open. If macOS says the app is "damaged", run xattr -dr com.apple.quarantine /Applications/BrickForge.app in Terminal.
• Linux: make the AppImage executable (chmod +x BrickForge-*.AppImage).

Spending cap. Each model has a cost (see below). The app caps every build at $5 by default, like the CLI; change it with the Cap menu under the chat box (including No cap). A run stops before any call that would go over the cap, and can be resumed with a higher one.

From source

You need Node.js 22 or later and an Anthropic API key.

git clone https://github.com/HariGuns/brickforge.git
cd brickforge
npm install
cp .env.example .env.local     # then put your key in ANTHROPIC_API_KEY (never commit .env.local)
npm run dev                    # http://localhost:3000

From the command line:

npm run gen "a red fire truck"                                   # Standard detail, single pass
npm run gen -- --detail high "a medieval castle"                  # sub-builds
npm run gen -- --detail very_high --budget 10 "a town square"     # sub-build trees, $10 cap
npm run gen -- --image photo.jpg "a sports car"                   # from a photo
npm run gen -- --simulate "a town square"                         # simulated Claude: no API calls, no cost

Budget cap: every CLI run is capped at $5 unless you pass --budget <USD>. When the cap would be crossed, the run stops before the next call, saves what's valid, writes stopped.json and prints the command to resume with a higher cap.

Results go to exports/ (.ldr and .mpd for LDraw software) and a debug folder per run in debug/ (every prompt, answer, validation result and its cost).

Build the desktop app yourself: npm run dist (this platform), or npm run dist:linux / dist:win / dist:mac. Release builds come from .github/workflows/release.yml, which tests, then builds all three platforms on a version tag (v0.1.0) and attaches them to a draft GitHub Release.

Optional extras:

• BrickLink part numbers: the wanted-list export uses Rebrickable's LDraw → BrickLink mapping. It isn't in the repo; fetch it with your own free Rebrickable API key: add REBRICKABLE_API_KEY=… to .env.local and run npm run fetch-bricklink. Without it, parts keep their LDraw numbers, which match BrickLink's for most parts.
• Rebuilding the part catalog (npm run build-catalog, npm run verify-ldraw) needs the LDraw parts library and the LDCad shadow library in ldraw-lib/; see docs/ENGINEERING.md.
• LeoCAD isn't needed for anything in the app. scripts/leocad-render.sh (Linux, Flatpak LeoCAD) renders exports for checking.
• Simulated app: BRICKFORGE_SIMULATE=1 makes the app (or npm run dev) build the scripted town square with no API calls, for trying it out or testing a build.

What a model costs

Real runs on Claude Opus 5.5, from the debug logs:

Reusing library components makes a model cheaper: the canal street reused 6 of its 8 sub-builds and cost $1.12 instead of about $2.80.

How it works

request / photo
   │
   ▼
photo analysis ──► real size → target size in studs (photo builds only)
   │
   ▼
planner ──► sub-builds: envelope, part budget, copies, scene or object
   │          ├─ reuse from the component library (optionally recoloured)
   │          └─ split large ones into child sub-builds (up to 3 levels)
   ▼
sub-builds designed in parallel ──► each validated on its own, repaired until valid
   │
   ▼
assembly, deepest level first ──► copies placed, glue parts added, repaired until valid
   │
   ▼
compiler ──► expands copies into one model, checks joins at every level
   │
   ▼
validator ──► buildability, structure, wheels, side studs, baseplates
   │
   ▼
3D view · instruction manual (PDF) · parts list · BrickLink list · LDraw .ldr/.mpd

• Planner (src/lib/claude/subbuilds.ts, tree.ts): splits the model into sub-builds: repeated features (houses, trees, windows) or distinct sections (a tower, a hull). Copies are the main way to get a large, detailed model cheaply. Mirror-image copies cover left/right pairs, and sideways panels can be mounted on side studs. Scenes (a town square, a park) are marked as such and stand on a baseplate.
• Sub-builds: each is designed once, inside its own size envelope, and checked on its own. Before it's accepted, it's also test-placed on a baseplate and on a plate, as the assembly will place it, so a post standing on a single stud is widened while it's designed.
• Component library (components/, src/lib/components/): every valid sub-build is saved as a reusable component, with its size, connection points, tags and what it cost. Planners are offered matching components and reuse them instead of paying to design them again. 109 components ship with the repo; see components/README.md.
• Compiler (src/lib/design/compile.ts): turns the tree of sub-builds and copies into one flat model (rotating and mirroring copies, up to 4 levels deep) and checks that every copy is attached, rests on something and doesn't interlock with a neighbour. About 60 ms for 4,600 parts.
• Validator (src/lib/validate/): the rules below. Its errors go back to Claude with a fix hint for each kind.
• Part catalog: 983 parts: 52 hand-made, 885 upright catalog parts, 41 side-stud parts and 5 baseplates. The catalog parts are generated from the LDraw parts library and the LDCad shadow library's connection data, and every one is checked against the real LDraw geometry (npm run verify-ldraw). The prompt lists a core menu of 150; Claude finds the rest with a search_parts tool.
• Cost controls: model and effort set per stage, a compact one-line-per-part answer format, repairs that return only the changes, prompt caching, and the per-model budget cap.

Validator rules

A model is valid when none of these errors remain:

Repair guard: a repair must fix, not delete. Each repair round is compared with the first answer, and it counts as a failed repair (FEATURE_REMOVED) if any of these happen:

• copies of a planned sub-build are gone;
• a part type is gone completely (a clock face swapped for a plain brick);
• a sub-build lost more than 3 parts or more than 10% of its parts, whichever is smaller.

Claude is told to put the parts back and fix the problem in place. Every removal, accepted or rejected, is listed in the run's summary.json.

Library gate: a component is only saved if it's valid on its own, has no structural warnings, and still holds when placed on a baseplate and on a plate.

Known limitations

• Clock faces and other panels on side studs: sideways mounting works, but in tests a repair once removed four sideways clock faces, and a later run built its clock faces flat into the wall. That case hasn't been re-tested since the repair guard was added.
• Structure is an estimate, not physics: weak joints and overhangs come from a mass-and-leverage estimate per joint. Balance, clutch strength and real loads aren't simulated.
• Baseplate sizing: a scene stands on the smallest baseplate that covers its whole footprint, so a few stray parts near the edge can make it pick a much bigger baseplate than the scene needs.
• Parts: no hinges, clips or pin-and-axle beams yet; slopes block their whole bounding box; parts can't hang from the underside of others.
• Desktop builds are unsigned (see above). The Windows portable .exe was tested under Wine (launch, key setup, a simulated build). The Windows installer and the macOS build haven't been tested yet: for Windows, use the portable .exe for now.

More detail on all of this, with measurements, is in docs/ENGINEERING.md. The live test reports are in docs/live-test-tree.md.

How it was built

BrickForge was built with Claude Code. I designed the system: the sub-build pipeline, the component library, the validator and repair rules, the testing approach and what to measure. Claude Code wrote the code under that direction, tested it against a simulated Claude first, and ran the live tests with a budget cap.

The whole project took $44.09 of API calls, from the run logs and including every test run. $41.57 of that was spent after sub-builds were introduced, developing and testing the sub-build system. On top of that, Claude Code ran on a $20 Claude Pro subscription, bringing the total to $64.09.

More about me and how I work: harithg.com

Licence

• Code: MIT; see LICENSE.
• Part data (src/lib/parts/catalog.json, public/parts/*.bin): derived from the LDraw parts library (CC BY 2.0 / CC BY 4.0) and the LDCad shadow library (CC BY-SA 4.0), and shared under CC BY-SA 4.0; see NOTICE.md.