English · 🇻🇳 Tiếng Việt

Atelier 📐

CI npm

An AI architect that plugs into any MCP client — Claude Code, Codex CLI, Gemini CLI, Claude Desktop, Cursor… From a spoken description to standards-compliant floor plans and a furnished 3D model, with a live browser editor you can edit by hand while the AI works.

Multi-typology, multi-region by design. Atelier started with the Vietnamese tube house (nhà ống) — TCVN drawing symbols, Vietnamese dimensional rules, Lỗ Ban feng-shui rulers — and now covers six house types on any lot: tube house, hip-roof villa on a sloping corner lot, single-storey house, garden house, apartment renovation, and a UK detached (validated against the UK Approved Documents pack). Building standards are pluggable rule packs (TCVN first, community packs welcome — see CONTRIBUTING); pitched roofs, per-edge frontages and sloping terrain are first-class schema. The editor UI is bilingual and auto-detects by country (the VI/EN button overrides).

Atelier /ˌætəlˈjeɪ/ — "design workshop".

Standards-compliant plan, 3-chain dims	First-person walkthrough (WASD)	A/B design comparison

50-second demo — empty lot to documented villa

▶ Watch the video (50s, webm) — one continuous take, no cuts: interview brief → ground floor grows batch-by-batch on the 2D plan → switch to 3D while the first floor and the 30° hip roof land on sloping terrain → orbit → furniture from the catalog → first-person walkthrough → sun study 8:00→17:00 → validator clean, 6-sheet documentation set exported. Reproduce it yourself: npx tsx packages/server/scripts/demo-video.ts.

Plan grows live (split view)	Hip roof on sloping corner lot	Walking the living room	Sun study 17:00

Core idea

One parametric model (JSON) is the single source of truth. Claude edits it through MCP tools; humans edit it directly in the web editor (drag, type exact numbers); both sync in real time over WebSocket. A deterministic renderer generates symbol-correct 2D drawings and the furnished 3D model from the same source — so 2D and 3D can never drift apart, and drawing symbols are always correct because the AI never draws them.

Claude Code ──MCP──► Server (model + validator + renderer) ◄──WebSocket──► Browser (live editor)

Install (30 seconds)

You don't clone anything — Atelier ships as an npm package (atelier-mcp), and it's a standard MCP server, so it is not tied to Claude: any MCP client can run it. The server is always the same one command — npx -y atelier-mcp — only the registration step differs per client.

Stand in your own house folder (one folder = one house) and run ONE command — it detects every MCP client on your machine and registers with each:

mkdir my-house && cd my-house
npx -y atelier-mcp setup          # finds Claude Code / Codex CLI / Gemini CLI /
                                  # Claude Desktop / Cursor and registers Atelier
npx playwright install chromium   # optional, once — PNG/PDF export

claude mcp add atelier -- npx -y atelier-mcp   # Claude Code
codex mcp add atelier -- npx -y atelier-mcp    # OpenAI Codex CLI
gemini mcp add atelier npx -y atelier-mcp      # Gemini CLI

{ "mcpServers": { "atelier": {
    "command": "npx", "args": ["-y", "atelier-mcp"],
    "env": { "ATELIER_DIR": "C:\\path\\to\\my-house" } } } }

Then start your agent and say "design me a 4×16m tube house". Works best with a model that reads Vietnamese well (tool descriptions and validator messages are Vietnamese-first) and a client that shows images from tool results — the agent inspects its own drawings.

From source (contributors)

pnpm install
npx playwright install chromium   # PNG/PDF rendering + demos
pnpm build:web
pnpm demo:p5                      # the 60-second demo: live build → drag a wall,
                                  # type 4200 → walk through the house in 3D

The repo ships a ready .mcp.json — open Claude Code in this folder and it registers the atelier server from source. pnpm build:cli builds the npm package (packages/cli, single-file bundle + web editor + fonts; verify with npx tsx packages/cli/smoke.mts <installed-pkg-path>).

What's the "60-second demo"?

The project's definition of success (doc 01), and it runs end-to-end (pnpm demo:p5):

Describe "4×16m tube house, 2 floors, 3 bedrooms, parking for 2 motorbikes" → a two-storey plan with correct symbols grows live in the browser → the user grabs a wall, types 4200 ⏎ → dims update, Claude notices the change and adapts the adjacent rooms → switch to 3D and walk (WASD) through the furnished house.

Status — roadmap complete

All six phases (P0–P5) plus the first three backlog items shipped:

Backlog shipped: rough cost estimate (estimate_cost + a KT-06 sheet: converted areas × an editable local price table, auto-checked against the interview budget) · view-only share links (/xem/<token>, server-enforced read-only — send it to your spouse) · A/B design comparison (variant_save/open/compare, two plans side by side with per-room m² and per-variant cost deltas) · local zoning rule pack (PLN-01…06: setbacks for any lot shape, density, floors, height, canopy overhang — checks only what the interview brief declares) · IFC4 export (export ifc, pure-TS STEP writer: walls with proper opening voids/fills, slabs with real holes, stairs, rooms as IfcSpace — concept-level handover, not construction documents) · photoreal path (export gltf → one GLB in true metres, one node per entity, plus scripts/render-photoreal.py for headless-Blender Cycles renders using the same sun model as the editor's sun study) · legacy plan import (underlay_import traces an old DXF or plan photo as a dim layer under the live plan — scale from DXF units or a 2-point calibration; underlay_trace proposes walls from parallel stroke pairs, always human-reviewed before applying).

Multi-typology & multi-region (P6–P9, doc 12) — shipped: rule packs as data (standards are pluggable JSON packs selected per project via config.region/typology; the geometry core always runs; write your own) · pitched roofs (gable/hip/shed entity, one geometry source feeding plan/elevation/section/3D/GLB/IfcRoof/estimate at true sloped m²) · per-edge frontages (corner lots, per-edge setbacks — PLN-07) · sloping terrain (per-vertex ground elevations: sloped ground lines in elevations/sections, 3D terrain mesh, height measured from street level) · 6-template library (tube house, villa, single-storey, garden house, apartment, UK detached — each a golden-tested fixture) · region layer (units + default packs + currency; UK Approved Documents is the first non-VN pack, honestly flagged ⚠ until each number is verified against the source; estimates never leak another region's currency).

Bilingual: English README + full English design docs (docs/en/) + bilingual editor UI auto-detected by country (VN → vi, elsewhere → en; asset catalog included). Out of scope by design: structure & MEP (this is a concept tool, not construction documents).

Design docs

The full spec lives in docs/en/ (English) with the Vietnamese originals in docs/ — each file cross-links its counterpart; the Vietnamese original is authoritative if they differ:

Stack

TypeScript monorepo — Node.js (MCP server + WebSocket), Three.js (3D), SVG (2D drawings), Vite (web editor), Vitest + Playwright (247 tests incl. real-browser e2e). Rationale in doc 03.

Dev environment

The repo integrates haido — a code-anchored memory layer that served as the project's own long-term memory while Atelier was being built:

• .mcp.json → haido serve MCP server (recall / remember / related / overview / stale / reanchor)
• .claude/settings.json → hooks that feed project knowledge into every Claude Code session
• Local DB in .haido/ (gitignored); shared knowledge ships as a memory pack in docs/memory-pack/

License & disclaimer

• Code: MIT. Font Be Vietnam Pro: SIL OFL 1.1 (OFL.txt next to the font files). Furniture catalog (parametric): CC0-1.0 (packages/core/assets/license-manifest.json).
• Standards data in rules/*.json cites TCVN/QCVN sources per rule; the price table rules/don-gia.json is reference-only — edit it for your region.
• ⚠ Atelier outputs are concept drawings — for thinking, discussing and working with an architect; they do not replace permit/construction documents signed by a licensed architect.

The 5 invariants

1. Claude never draws directly — it only edits the parametric model; the renderer draws.
2. Standard symbols live in the renderer — encoded once per TCVN, correct 100% of the time.
3. Every mutation goes through one gate (apply_ops) — transaction, validation, broadcast.
4. The user always wins — hand edits are never overwritten by the AI.
5. Claude must look before inviting the user to look — validate + render + capture after every significant change.