Important

🤖 Read this with your AI agent — don't read it by hand.

This repo is written agent-first. Point Claude Code, GitHub Copilot, Cursor, or any agent at it: "Read the README and AGENTS.md, then help me run / extend this." Structure + AGENTS.md are optimized for agent comprehension.

Floor plans as code — like Typst/LaTeX, but for architecture.

Text in, a precise architectural drawing out. Deterministic, zero-dependency, and built so an AI agent can verify its own plan without ever looking at an image.

▶ Live Playground · 📖 Docs · ⌨ CLI reference · 📦 npm · 🧩 VS Code

👀 See it

Here is a whole program, and below it the actual drawing it compiles to — not a mock-up. Not one coordinate in it places a door, a window or a piece of furniture: every opening is pinned to a distance along a named wall, every fixture resolves against a room or a wall, and the bath and bedroom are laid out by a strip. site { street north } names the two facades the plan turns on — the front door faces the lane, the glazing faces the garden.

# A one-bedroom laneway cottage — 49 m² that reads as one program.
#
# Nothing here is positioned by hand. Every opening is pinned to a run distance along a
# named wall (`on <wall> at <pos>`), every fixture resolves against a room or a wall
# (`in <room> anchor …`, `against wall …`), and the bath/bedroom pair is laid out by
# `strip`. `site { street north }` names the two facades the plan turns on: the door
# faces the lane, the glass faces the garden.
plan "Laneway House" {
  units mm
  grid 50            # partitions are 100 thick, so a `flush` fixture lands on a …50
  north up
  dims auto all
  site { street north }

  wall id=w_lane   exterior  thickness 200 { (0,0) (7500,0) }
  wall id=w_east   exterior  thickness 200 { (7500,0) (7500,6500) }
  wall id=w_garden exterior  thickness 200 { (0,6500) (7500,6500) }
  wall id=w_west   exterior  thickness 200 { (0,0) (0,6500) }
  wall id=w_hall   partition thickness 100 { (4200,0) (4200,6500) }
  wall id=w_bath   partition thickness 100 { (4200,2500) (7500,2500) }

  room id=r_live at (0,0) size 4200x6500 label "Living / Kitchen" uses living kitchen
  strip down at (4200,0) gap 0 width 3300 {
    room id=r_bath size 2500 label "Bath"    uses bath
    room id=r_bed  size 4000 label "Bedroom" uses bedroom
  }

  door id=d_front  on w_lane at 2100 width 900 hinge near start swing into r_live
  door id=d_garden sliding on w_garden at 2700 width 1800 slide left
  door id=d_bed    on w_hall at 5600 width 800 hinge left swing into r_bed
  # `w_hall` is walked lane→garden, so `slide right` sends the panel down the solid wall
  # below the jamb; `slide left` would aim it at 500 mm and trip `W_POCKET_RUN`.
  door id=d_bath   pocket on w_hall at 900 width 800 slide right

  window on w_west   at 2400 width 1200
  window on w_garden at 700  width 1000
  window on w_garden at 5850 width 1600
  window on w_east   at 1500 width 600

  furniture fridge       against wall w_west offset 400  in r_live
  furniture stove        against wall w_west offset 1200 in r_live
  furniture kitchen_sink against wall w_west offset 2000 in r_live
  furniture table  in r_live centered size 1300x900 label "Table"
  furniture sofa   in r_live anchor bottom-left flush inset 250 size 900x2000  label "Sofa"
  furniture bed    in r_bed  anchor bottom-right flush inset 250 size 1500x2000 label "Bed"
  furniture robe   in r_bed  anchor top-left     flush inset 200 size 1800x600  label "Wardrobe"
  furniture shower in r_bath anchor top-right    flush size 900x900
  furniture wc     in r_bath anchor bottom-left  flush size 400x700
  furniture basin  in r_bath anchor bottom-right flush size 600x450

  title { project "Laneway House" drawn_by "ArchLang" date "2026-08-16" }
}

↑ arch compile laneway-house.arch — that program, rendered. The walls join and hatch themselves, the hinged doors draw their own swing arcs, the sliding and pocket leaves draw panels instead (a pocket door has no arc, because it has no swing), and dims auto all measures the building it was given.

▶ Click the drawing — it opens the live playground with this exact plan already loaded. Change a number and watch it redraw; the compiler runs in your browser, nothing is sent to a server.

Why a link and not a live embed? ArchLang does ship an embeddable viewer — but GitHub's markdown sanitizer strips <iframe> (it comes back as escaped text, exactly like <script>), so no README on GitHub can host one. The embed works everywhere GitHub isn't: see Embed a plan anywhere. Source: examples/laneway-house.arch.

🌟 Introduction

ArchLang is a small declarative language for floor plans. You declare a plan — walls, rooms, doors, windows, furniture — and the compiler renders a clean, professional SVG (also DXF, PDF, PNG, and a zero-dependency ASCII plan).

Coordinates are integer millimetres, so output is deterministic: the same source always produces byte-identical bytes, and changing one number changes exactly one thing. "Make the bedroom 1 m wider" is a one-number diff — not a re-roll of a raster image that silently redraws the kitchen too.

The compiler is pure TypeScript with zero runtime dependencies and is isomorphic — the same code runs in Node and in the browser, which is why the playground is fully client-side.

ArchLang is the floor-plan engine behind ArchCanvas, an AI design agent — but it stands alone and is useful in any app or script.

💡 Why it is different

Most "AI floor plan" tools generate a picture. A picture cannot be checked, diffed, or reasoned about — and neither the model nor you can tell whether the bathroom is actually reachable.

ArchLang generates a program, and then lets you interrogate it as facts:

	Raster image generation	ArchLang
Output	pixels	a .arch program → SVG / DXF / PDF / PNG / TXT
Edit "widen the bedroom"	re-roll the whole image	change one number
Same input twice	different image	byte-identical output
"Is the bath reachable?"	look at it and guess	arch describe --json → access graph
"Does it match the brief?"	eyeball it	arch validate --intent → exit code
Wrong syntax	—	errors returned as data, each carrying its own fix

That last row is the whole design: compile() never throws. It returns diagnostics with byte spans and a machine-applicable fix, which is what makes a tight self-correction loop possible.

🤖 The agent loop

An agent can author a plan, correct itself, and confirm the plan matches the brief without rendering an image at all — which is what makes ArchLang cheap to drive from a text-only model.

flowchart TD
    B([Brief]) --> S["<b>arch context</b> — the whole language, one call"]
    S --> W["Write <b>.arch</b>"]
    W --> C{"<b>arch compile --json</b>"}
    C -->|"ok: false"| F["<b>arch fix</b><br/><i>each diagnostic carries its own fix</i>"]
    F --> C
    C -->|"ok: true"| D["<b>arch describe --json</b><br/><i>rooms · areas · adjacency · access graph</i>"]
    D --> V{"<b>arch validate --intent</b><br/><i>does it meet the brief?</i>"}
    V -->|"no"| G["<b>arch suggest</b><br/><i>candidate door / window statements</i>"]
    G --> W
    V -->|"yes"| O([SVG · DXF · PDF · PNG])

    style B fill:#ede7f6,stroke:#6b3ae0,color:#1a1a1a
    style O fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style C fill:#fff8e1,stroke:#7a6000,color:#1a1a1a
    style V fill:#fff8e1,stroke:#7a6000,color:#1a1a1a
    style D fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style F fill:#fdecea,stroke:#b3261e,color:#1a1a1a
    style G fill:#fdecea,stroke:#b3261e,color:#1a1a1a

Loading

Cold start in one command. arch context prints the entire agent context — language spec, workflow skill, CLI reference and every diagnostic code — as one system-prompt-ready document (the same llms-full.txt the docs site serves).

npx @chanmeng666/archlang context                       # EVERYTHING: spec + skill + CLI + error catalog
npx @chanmeng666/archlang context --section errors      # …or one section of it (the catalog alone: 60 KB → 13 KB)
npx @chanmeng666/archlang spec                          # just the language, one page (~2k tokens)
npx @chanmeng666/archlang help describe                 # one command, with worked examples
npx @chanmeng666/archlang compile plan.arch --json      # render → { ok, diagnostics, summary }
npx @chanmeng666/archlang fix plan.arch --dry-run       # the exact unified diff it would write, applying nothing
npx @chanmeng666/archlang describe plan.arch --json     # VERIFY, without an image
npx @chanmeng666/archlang validate plan.arch --strict   # the ship gate

Every command takes --json (result on stdout, messages on stderr) with deterministic exit codes (0 ok · 2 user-source error · 1 IO · 3 usage) — and a typo earns that 3: arch lint --jsn exits 3 with did you mean --json? rather than quietly reading --jsn as a filename, and arch comple suggests compile.

One manifest, no drift. The per-command help (arch <cmd> --help), the flag parser, and the generated CLI reference are all rendered from the same manifest — which is why they cannot advertise a flag a command doesn't take. arch manifest --json is that manifest as data, and arch <cmd> --help is the cheap way to read one row of it.

Reads are bounded, so a big plan can't flood a context window: describe --select/--room, lint|validate --code/--severity, context --section. Filtering what you read never changes what gates — the exit code always weighs every diagnostic. And because arch fix rewrites your source, it prints the unified diff first and takes --backup.

See SKILL.md.

Machine-native artifacts — Plan JSON, a GBNF grammar, an intent schema, and an optional MCP server

Artifact	Use
/plan.schema.json	Emit structured JSON, compile it with arch compile --from-json
/archlang.gbnf	Constrain a local model to parseable output
/intent.schema.json	Write the brief down as a contract; gate on it with validate --intent
/llms-full.txt	The whole context bundle (arch context)

MCP server (optional). @chanmeng666/archlang-mcp is a stdio Model Context Protocol shim over the library, listed on the official registry as io.github.ChanMeng666/archlang-mcp:

claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp

Prefer the CLI when your agent has a shell — a CLI costs nothing in the context window until it is called, whereas an MCP tool schema sits there permanently. The server exists so MCP-native hosts can discover ArchLang. The core stays zero-dependency; the SDK lives only in that package (ADR 0012).

In CI: .github/actions/arch-render renders every ```arch fence in your Markdown to images in one step.

✨ Features

It draws like an architect, not like a plotter

Poché-hatched walls (by material), door swing arcs, window glazing, computed room areas, dimension lines, layers, line weights, a north arrow, a scale bar and a title block. Real drawn symbols for every catalogued furniture kind — 129 words across 83 families, the bathroom and kitchen fixtures, the room furniture and the garden beside them, each with the detail that makes it readable at plan scale (see Furniture & Fixtures, or the furnished-flat and garden-house examples) — plus the two drawing-only annotations a plan needs above and below the cut: roof overhang 600 puts a dashed eaves line around the building (an exact mitred offset of the wall ring, at any angle), and void puts a stair well or an atrium on the floor plate. And dims auto synthesizes the dimension strings for you.

It checks architectural soundness, not just syntax

arch lint encodes tacit professional knowledge: a bathroom reachable only through a bedroom, a wet room that isn't fully walled in, a door whose swing hits furniture or another door, a windowless bedroom, an unenterable room, a too-narrow door, a bath/kitchen with no fixtures, and a room whose use was merely inferred from an indirect label (W_ALIAS_MATCH — with a fix that pins the explicit uses). All tunable via the ruleset.

It models how a person actually walks the plan

arch describe runs a clearance-eroded nav grid: per-room walk distance, the narrowest pinch on the way in, and how circuitous the route is — with advisory lint for a too-tight (W_PATH_TOO_NARROW) or roundabout (W_CIRCUITOUS_PATH) walk, and an opt-in arch compile --overlay circulation that draws the routes on top of the plan.

Facts and advice — never an invisible auto-arranger (ADR 0005). arch repair is the one explicit corrector: it pushes furniture out of walls, doorways and swing arcs, and emits a change log you review.

Errors are data, and many carry a machine-applicable fix

compile() never throws on bad source — it returns diagnostics with byte spans, a catalogued E_*/W_* code, and a fix. Where the edit is mechanical, the diagnostic also carries applicable fixes that arch fix applies for you. --error-svg even turns a plan that won't compile into a self-describing error card an agent can look at.

Parametric, scriptable, and still deterministic

Values, arithmetic, arrays, for/if/while and pure functions — plus relational placement (right-of / below / …) and room strips, resolved by deterministic topological arithmetic, not an optimizer. All of it expands at compile time: no runtime, no clock, no I/O. Optional metric unit suffixes (4m / 40cm / 20mm) fold exactly to millimetres at lex time.

Five output formats · accessible SVG · IDE-grade tooling

SVG, DXF and a TXT ASCII plan with zero dependencies; PDF (vector, selectable text) and PNG (deterministic raster) via optional, lazily-loaded add-ons the default install never pulls. arch compile --accessible stamps the SVG with <title>/<desc> + role="img".

A full LSP (hover, completion, go-to-definition, rename, signature help), an arch fmt formatter, an arch explain <CODE> catalog, a self-documenting CLI (arch <cmd> --help, rendered from the manifest, worked examples included), and a VS Code extension.

🚀 Quick start

npx @chanmeng666/archlang new -o plan.arch          # scaffold a starter plan
npx @chanmeng666/archlang compile plan.arch -o plan.svg

Or install it:

npm install @chanmeng666/archlang

As a library (zero dependencies, runs in Node and the browser):

import { compile } from "@chanmeng666/archlang";

const { svg, diagnostics } = compile(`
plan "Tiny" {
  units mm
  grid 50
  wall exterior thickness 200 { (0,0) (4000,0) (4000,3000) (0,3000) close }
  room id=r at (0,0) size 4000x3000 label "Studio"
  door at (2000,3000) width 900 wall exterior hinge left swing in
  window at (0,1500) width 1200 wall exterior
}`);

// compile() never throws — errors come back as data, each with a span and a fix.
if (diagnostics.some((d) => d.severity === "error")) console.error(diagnostics);
else writeFileSync("tiny.svg", svg);

Also exported, all pure: describe() (facts), lint() (soundness), validateIntent() + projectSubscores() (does it match the brief?), repair(), applyFixes(), suggestTopology(), renderAscii(), toDxf(), and the LSP core (completion, hover, …).

Develop this repo

npm install          # one install bootstraps every workspace
npm run build        # build the library + CLI into dist/
npm run check        # typecheck + lint + the full test suite
npm run check:drift  # every generated artifact must match its source
npm run playground:dev   # build the core, then open the playground

🖼️ Gallery

Every one of these is a real, compiled example from examples/ — and every drawing on this page is generated from its source by npm run gen:example-svgs, so a picture here can never drift from the compiler that made it. Click a drawing to open it in the playground, or the name for the source.

The showpiece — the whole language on one sheet: site orientation, a polygon reading nook and an L-shaped master suite, a bowed arc bay, all five door kinds, a shared stair shaft, a void over the double-height living room, a roof overhang, and a mirrored pair of ensuite bathrooms composed from one component. Every room is reachable, every doorway clears, and the three warnings arch lint still raises are left in on purpose and explained in the source.

hillside-villa

The site plan — the same language pointed at everything OUTSIDE the wall line: a surveyed lot boundary, nine outdoor ground materials from lawn to swimming pool, a posted fence round the water, a garage with the sixth door kind, and fifteen outdoor fixture families from the bins to the trampoline. The ground is drawn and measured but is emphatically not floor area.

garden-house

studio The flagship: fitted kitchen and bath, an enclosed bath off a central hall. Lint-clean, and import-free.	two-bed A larger dwelling: central corridor, five rooms, windows on three exterior walls.	attached No hand-computed coordinates at all: strips, on-wall openings, anchors.
bungalow The door vocabulary: sliding, pocket and bifold leaves — panels, not arcs.	hexagon-pavilion Six polygon rooms round a circular rotunda: room … polygon meets room circle.	terrace-row One component, placed four times — mirrored in pairs, widths from a let array.
library A public building on a real sheet: A2 at 1:200, axes, schedule and legend.	transit-hall A concourse: paid and unpaid sides, a generated run of gates and kiosks.	aquarium True arcs, a circular room, and exact πR² areas — never faceted at any zoom.
museum The largest sheet in the corpus: A1 at 1:200, galleries, reception and cafe.	gallery-l The polygon-room flagship, furnished and tried against `theme presentation`.	materials Per-element `style` overrides — wall materials and hatch fills, furnished.

And one that is here for its furniture — the drawn symbol catalogue in a single plan, from the WC's seat ring to the wardrobe's hanger scallops. Twenty-six kinds; not one of them carries a label, and most carry no size either:

furnished-flat

Two more, drawn on a smaller sheet — the same language, laid out to a fixed scale inside a titled A3 border rather than sized to its own drawing:

courtyard-house A ring of rooms round an open court — the case where a window's outward face is not the side its bounding box suggests.	townhouse Three storeys in one file (ground floor shown) — level blocks, one stair shaft, one drawing per page.
two-storey A void over the ground-floor gallery, and eaves on the storey above.	tiny-house Barn and bifold doors on a 7.2 x 3 m shell, now with eaves — roof overhang.

Also in examples/ — the whole corpus, by what it is there to show:

• Showpiece — hillside-villa (the whole language on one sheet).
• Start here — one-room (the smallest plan that draws anything), studio (the lint-clean flagship), attached (nothing positioned by hand).
• Homes — laneway-house, tiny-house, garden-loft, two-bed, bungalow, furnished-flat (the furniture flagship), courtyard-house, townhouse (three storeys), terrace-row (one component, placed four times), two-storey, accessible (accTitle/accDescr).
• Public buildings — library, transit-hall, clinic, museum (A1 at 1:200), hexagon-pavilion.
• Geometry & experiments — gallery-l (polygon rooms), aquarium (arcs and circles).
• Scripting & composition — parametric (a for loop that generates units), relational (right-of / below), imports, museum-wing + museum-wings (one wing, imported and placed twice).
• Style — themed (a custom theme + brick hatch), materials (per-element style overrides and wall materials).

The docs gallery renders all of them live and editable in the browser.

🎬 Showcase

The examples above teach the language. The Showcase is what happens when you point it at real buildings and famous fictional ones — the West Wing (whose Oval Office is a true arc, not a faceted polygon), Palladio's Villa La Rotonda (one quarter, placed four times), Bag End, de_dust2, The Skeld, 742 Evergreen Terrace, the Dunder Mifflin annex. Every one is a few dozen lines of source you can open in the playground and recompile.

They are worth a look for what the compiler says about them as much as for the drawings: arch lint reports a real W_NO_ENTRANCE on de_dust2 — a quarter century of continuous occupancy, achieved entirely by spawning — and it reviews a $2,950-a-month railroad apartment in twelve warnings across nine codes.

archlang.uk/showcase for the curated set · ChanMeng666/archlang-showcase for every plan's source and the story behind it.

🏗️ How it works

ArchLang is a compiler pipeline. Source text becomes a backend-neutral Scene IR, and every backend is a pure serializer of that scene — which is why adding a format never touches the language.

flowchart TD
    SRC["<b>.arch</b> source"] --> LEX["<b>lexer</b><br/><i>hand-written → tokens with byte spans</i>"]
    LEX --> PAR["<b>parser</b><br/><i>recursive descent → AST · recovers, never throws</i>"]
    PAR --> IR["<b>resolve()</b><br/><i>expand scripting · grid-snap<br/>relational placement · host openings</i>"]

    IR -->|"render"| SCN["<b>toScene()</b><br/><i>wall union · hatches · page</i>"]
    IR -->|"read back"| DESC["<b>describe() · lint() · validateIntent()</b><br/><i>the SAME resolved plan, as FACTS —<br/>no rendering required</i>"]

    SCN --> SVG["<b>SVG</b><br/><sub>zero-dep</sub>"]
    SCN --> DXF["<b>DXF</b><br/><sub>zero-dep</sub>"]
    SCN --> TXT["<b>TXT</b><br/><sub>zero-dep</sub>"]
    SCN --> PDF["<b>PDF</b><br/><sub>optional</sub>"]
    SCN --> PNG["<b>PNG</b><br/><sub>optional</sub>"]

    DESC --> FACTS(["rooms · areas · adjacency<br/>access graph · intent score"])

    style SRC fill:#ede7f6,stroke:#6b3ae0,color:#1a1a1a
    style IR fill:#eceef2,stroke:#464d59,color:#1a1a1a
    style SCN fill:#eceef2,stroke:#464d59,color:#1a1a1a
    style DESC fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style FACTS fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style SVG fill:#fbfbfc,stroke:#464d59,color:#1a1a1a
    style DXF fill:#fbfbfc,stroke:#464d59,color:#1a1a1a
    style TXT fill:#fbfbfc,stroke:#464d59,color:#1a1a1a
    style PDF fill:#fbfbfc,stroke:#8a8f98,color:#1a1a1a
    style PNG fill:#fbfbfc,stroke:#8a8f98,color:#1a1a1a

Loading

The dotted branch is the point: describe, lint and the intent check read the same resolved plan the renderer does — so what an agent verifies is exactly what gets drawn, and it costs no pixels to check.

compile() is pure, synchronous and deterministic — no I/O, no Date.now(), no Math.random(). The only place Node APIs are allowed is the CLI; everything else gets its environment through a World seam. See AGENTS.md and the ADRs.

📦 Ecosystem

Package / surface	What it is
@chanmeng666/archlang	The core: compiler, CLI, analysis. Zero runtime deps, isomorphic.
@chanmeng666/archlang-mcp	Optional stdio MCP server (the SDK is quarantined here).
VS Code extension	Syntax + live diagnostics, hover, completion, rename.
Playground	Client-side editor: preview, describe, lint, intent scoring, apply-fix, embed.
Docs site	Guide, reference, CLI reference, ADRs, live examples.
🤗 Dataset	Synthetic, self-verifying repair trajectories + authoring pairs. CC0.
GitHub Action	Render ```arch fences in any repo's Markdown.

Embed a plan anywhere

A live, editable plan in any blog, wiki or docs page — one <iframe>, no build step, nothing sent to a server (the source rides in the compressed #z= hash, so the page is self-contained):

<iframe src="https://playground.archlang.uk/embed.html#z=…" width="720" height="480"></iframe>

The playground's Embed button generates the snippet. Optional params: editable=1 (show a compact editor that re-renders as you type) and theme=blueprint|dark|mono|presentation.

Not on GitHub, though. GitHub's markdown sanitizer strips <iframe> — it renders as escaped text, the same way <script> does — so a README (here or anywhere on github.com) cannot host a live embed, no matter how it's written. The honest substitutes GitHub does allow are what this README uses: a static SVG the compiler really produced, linked to a playground permalink that opens the same plan live. On the docs site, where the sanitizer doesn't apply, every plan is live and editable in place.

📚 Documentation

• 📖 Docs site — guide, reference, error catalog, ADRs, and a live, editable examples gallery. Every ```arch fence on a docs page is itself an editable plan.
• ⌨ CLI reference — every command, flag and exit code (generated from the manifest, so it can't fall behind).
• spec.llm.md — the whole language in one page (~2k tokens) for AI agents; also arch spec.
• SKILL.md — the agent Skill: the spec → compile → fix → describe → validate loop.
• Language Reference · Error catalog · The intent contract · ADRs
• AGENTS.md — orientation for AI agents working in this repo.

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide and our Code of Conduct. Use the issue and pull-request templates when you open one.

❤️ Support & Sponsor

• Questions? Open a Discussion or see SUPPORT.md.
• Found a security issue? Follow SECURITY.md.
• If this project helps you, consider sponsoring ☕.

📄 License

Released under the MIT license.

---

Chan Meng
Need a custom app like this one? I build them — let's talk.