Monarch is a house model that a coding agent can edit precisely. Walls, openings, slabs,
stairs, roofs, furniture and products are plain JSON files in metres. One command compiles
them into an IFC4 file that any BIM tool opens, tessellates it once, exports glTF and
serves a hot-reloading browser viewer. A query tool answers geometric questions from the
built geometry, so the agent never guesses a distance. Declarative rules fail the build when
a walkway is blocked. Every object carries its provenance.
It was born while an engineer modelled his own family's house, then under construction,
together with Claude Code over hundreds of commits. An architect who saw the result said he
knew no software as good. This repository is that engine, with the private house replaced by
Casa Monarch, a fictional two-storey home whose ground-floor gallery is the tutorial.
60-second quickstart
You need uv and a browser.
git clone https://github.com/bersling/monarch-oss && cd monarch-oss
uv sync
./open.sh
./open.sh builds the house and opens the viewer. Edit anything under data/ and save: the
server rebuilds and the open tab swaps the model in place, keeping your camera. The IFC is at
generated/casa_monarch.ifc.
Without a browser, ./build.sh is the whole pipeline. On this machine it takes about two
seconds, checks included:
$ ./build.sh
Wrote generated/casa_monarch.ifc (Casa Monarch) — GF Ground floor: 9 walls, 9 windows; UF Upper floor: 12 walls, 8 windows; Site: 32 terrain tris, 1 boundary lines, 2 site slabs, 5 site objects
geometry cache: 216 elements (0 re-meshed, 216 reused), 62276 verts, 77443 tris, 0.5s
model.glb: 216 nodes, 2.9 MB, 0.0s
ok 0.0s variant.py check
ok 0.0s products.py check
ok 0.1s check_model.py
ok 0.0s rules.py
4/4 checks passed in 0.1s
Optional: Blender to convert downloaded meshes
(src/convert_asset.py), Google Chrome for headless screenshots (src/snap_web.py). Both
paths are macOS constants at the top of those two files; other platforms change one line.
Casa Monarch builds without either.
Talk to your house
Open the repository in Claude Code (or any coding agent that reads CLAUDE.md /
AGENTS.md) and type a sentence. These three are printed on plaques in the gallery, and
each one works here.
| You say | What the agent does |
|---|
| Switch the gallery centre to the sculpture variant | Runs src/variant.py load gallery_centre sculpture, which swaps the GAL_CENTRE_* entries in data/ground_floor.json and rebuilds. The bench becomes a terracotta sphere stack; the viewer tab updates. |
| Add a clear rule that keeps 90 cm in front of the bedroom wardrobe free | Asks ./q show BED_WARDROBE for the real bounds, writes a clear rule into data/rules/bedroom.json, runs ./build.sh. From now on anything placed in that strip fails the build. |
| Find a CC0 plant on Poly Haven and put it on the empty plinth in the gallery | src/find_asset.py "plant" lists candidates with licence and real size, src/convert_asset.py turns the glTF into a metre-scaled OBJ, the agent places it with mesh/at on GAL_PLINTH_EMPTY, copies MeshSource/MeshLicense/MeshURL/MeshAuthor into the props, builds, and renders a screenshot to check its own work. |
The loop the agent follows is five steps, written down in CLAUDE.md: measure
with ./q, edit JSON, ./build.sh, verify the numbers with ./q, look at a render.
Why JSON + IFC
Revit, ArchiCAD, SketchUp and Blender are superb tools for people. For an agent they are
opaque: binary files, GUI-driven edits, no diff, no way to ask "how far is the sofa from the
wall" from a shell. Monarch keeps the authoring layer in text and the deliverable in the
open standard:
- Diffable. A moved wardrobe is a two-line change in a pull request.
- Measurable.
./q at 2.5,6.0 --storey GF answers from the built geometry, not from a
sketch.
- Verifiable. Rules run on the actual IFC on every build; a 5 mm penetration is a failed
check, not a surprise on site.
- Portable. The output is IFC4 (
FILE_SCHEMA(('IFC4'))), written with
IfcOpenShell 0.8.5. Open it in BlenderBIM, Solibri, Revit, or
the hosted viewer below.
The house is the tutorial
Room GF.06 of Casa Monarch is a gallery with one exhibit per way of getting an object into
the model. Each exhibit carries a Pset_Gallery property set (Title, Provenance, License,
HowTo, Prompt), so any IFC viewer shows the lesson on click, and a plaque on the wall
repeats it. All texts live in data/gallery.json.
以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗
