bricky

A compiler for LEGO® models, built for AI agents.

An AI agent writes a LEGO® model as a Python build script, and bricky builds it the way a compiler builds code. Each build places every part in exact geometry, reports each mistake with the script line behind it, and renders four views with rulers.

The documentation explains every concept and lists every command.

🚀 Quick start

The quick start needs uv, which installs Python if needed. A uv project holds your build scripts, and uv add installs bricky into it from PyPI. The project pins Python 3.14, the version bricky recommends: on 3.15, installing compiles the solver HiGHS, which needs a C++ compiler.

uv init --bare --pin-python --python 3.14 my-models  # a project for your build scripts
cd my-models
uv add bricky                                        # bricky and every dependency, from PyPI
uv run playwright install chromium                   # the browser bricky renders in, once per machine

Download an example and build it, which checks the model and renders it beside the script:

curl -O https://raw.githubusercontent.com/maxencefaldor/bricky/main/examples/japanese_garden.py
uv run bricky build japanese_garden.py

With pip on Python 3.12 to 3.14, run pip install bricky and then playwright install chromium. On Linux, playwright install --with-deps chromium also installs the browser's system libraries. To install bricky as a tool, run uv tool install --python 3.14 bricky --with-executables-from playwright, then playwright install chromium. The command is then bricky, without uv run. A clone of the repository runs every example and the benchmark: Get started shows how.

🤖 Use it with an agent

An agent reaches bricky through one of three front ends:

• The command line, for any harness that runs shell commands: the agent runs uv run bricky build and reads the report and the images.
• The MCP server, for any harness that speaks the Model Context Protocol: claude mcp add bricky -- uvx --python 3.14 bricky-mcp adds it to Claude Code.
• The skill, which teaches the agent the build loop: Connect an agent shows how to install it.

🧱 How it works

A build script places parts by their BrickLink id, in studs and plates. The four lines below come from examples/broken.py, which makes three mistakes: an overlap, a brick half a stud off and a floating plate.

builder.place("3001", at=(0, 0, 0), color="Red", id="base")  # Brick 2 x 4
builder.place("3001", at=(1, 0, 0), color="Blue", id="overlap")  # shares space
builder.place("3003", at=(0.5, 0, 3), color="White", id="offset")  # half a stud off
builder.place("3022", at=(4, 2, 9), color="Tan", id="floating")  # touches nothing

The report reads like compiler output, and every element it names points back at the script:

error[overlap]: base and overlap occupy the same space
  --> x 1..2  y 0..4  z 0..3
   = base: Brick 2 x 4 (3001), Red, examples/broken.py:15 in build()
   = overlap: Brick 2 x 4 (3001), Blue, examples/broken.py:16 in build()

The image marks the same elements in red, so the agent sees where they are:

ℹ️ Disclaimer

LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project.