@chanmeng666/archlang

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.

Introduction

ArchLang is a tiny language for floor plans. You write a .arch source file that declares a plan — walls, rooms, doors, windows, dimensions — and the compiler renders it to a clean, professional SVG. Think of it as Typst/LaTeX for architecture: text in, a precise drawing out.

It is explicit and parametric. Every element has exact coordinates and sizes in millimetres, so the output is deterministic (the same source always produces the same drawing) and editable (changing one number changes exactly one thing). That makes it ideal both for humans and for AI agents that author or tweak plans and re-render — e.g. "make the bedroom 1 m wider" becomes a one-number diff, not a re-roll of a raster image.

The compiler is pure TypeScript with zero runtime dependencies and runs identically in Node and the browser — so the live 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.

Features

• Code → professional drawing. Poché-hatched walls (by material), door swing arcs, window glazing, computed room areas, dimension lines, layers, line weights/types, a north arrow, a scale bar, and a title block. Drawn fixture symbols for WC, basin, shower, bathtub, sink, counter, fridge and stove (with a lib/fixtures.arch component library), and dims auto to synthesize dimension strings for you.
• Architectural soundness, not just syntax. arch lint checks habitability and 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 bath/kitchen with no fixtures, a windowless bedroom, an unenterable room, a too-narrow door. All tunable via the ruleset.
• Four export formats. SVG and DXF with zero dependencies; PDF (vector, selectable text) and PNG (deterministic raster) via optional, lazily-loaded add-ons that the default install never pulls.
• Parametric + scriptable. Values, arithmetic, arrays, for/if/while, and pure functions — plus relational placement (right-of / below / …) resolved by deterministic topological arithmetic. All expand-time: no runtime, no clock, no I/O.
• Explicit + deterministic. Integer-millimetre coordinates with optional grid snapping; byte-for-byte stable output, so renders are cacheable and visually regression-tested.
• Zero-dependency core, isomorphic. Hand-written lexer + recursive-descent parser; the SVG path runs in Node and the browser with no native binaries.
• Errors as data. compile() returns diagnostics/errors/warnings with byte spans — it never throws on bad source — making a tight authoring or LLM self-correction loop trivial.
• AI-agent-native, CLI-first. arch spec teaches the whole language in one page; arch describe --json returns the plan as facts (rooms, areas, adjacency, what doors connect) so a text-only agent verifies without an image; arch lint --json flags unsound plans. Every command is --json with deterministic exit codes and fix-carrying diagnostics — no MCP, no server. See SKILL.md.
• IDE-grade tooling. A full LSP (hover, completion, go-to-definition, rename, signature help), an arch fmt formatter, an arch explain <CODE> error catalog, and a VS Code extension.
• Library + CLI + playground + docs. Use the compile() API, the arch CLI, the live editor, or the documentation site.

Getting Started

Prerequisites

• Node.js ≥ 18 to use the CLI or build from source. The library itself is dependency-free and also runs in any modern browser.

Install

npm install @chanmeng666/archlang

Build from source / develop

npm install        # install dev dependencies
npm run build      # build the library + CLI (dist/)
npm test           # run the test suite (vitest)
npm run cli -- compile examples/studio.arch -o studio.svg   # run the CLI from source

Usage

As a library:

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

const source = `
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
}`;

const { svg, errors, warnings } = compile(source);
if (errors.length) console.error(errors);
else writeFileSync("tiny.svg", svg); // a finished floor plan

As a CLI:

arch compile floorplan.arch -o floorplan.svg   # compile once (SVG, default)
arch compile floorplan.arch -f dxf             # also: dxf · pdf · png
arch compile floorplan.arch -w 1000            # set output width (px)
arch watch   floorplan.arch                     # recompile on save
arch fmt     floorplan.arch --write             # format source in place
arch explain E_LAYOUT_CYCLE                      # explain a diagnostic

Use it from an AI agent (CLI-native, no MCP)

ArchLang's agent interface is its CLI — token-cheap, runs in any harness, nothing to configure. Every command takes --json (structured result on stdout, messages on stderr) with deterministic exit codes (0 ok · 2 user-source error · 1 IO · 3 usage), and every diagnostic carries a fix, so the self-correction loop needs no docs lookup. (There is deliberately no MCP server: a CLI costs nothing in context until called, where an MCP schema sits in the window permanently.) Point your agent at SKILL.md, or:

npx @chanmeng666/archlang spec                 # the WHOLE language in one page (~2k tokens) — read first
npx @chanmeng666/archlang compile plan.arch -o out.svg --json   # render; JSON: { ok, diagnostics, summary }
echo '<source>' | npx @chanmeng666/archlang compile - -o - -f svg   # stdin → SVG on stdout
npx @chanmeng666/archlang describe plan.arch --json            # verify: rooms, areas, adjacency, door connections
npx @chanmeng666/archlang lint plan.arch --json                # architectural soundness warnings

The loop: spec → write .arch → compile --json → on ok:false fix via each diagnostics[].fix → describe --json to confirm intent (room count, areas, adjacency) without rendering an image.

A taste of the language (see examples/ and the Language Reference):

plan "One-bed" {
  units mm
  grid 50
  scale 1:50
  north up
  dims auto overall

  wall exterior  thickness 200 { (0,0) (6000,0) (6000,4000) (0,4000) close }
  wall partition thickness 100 { (4000,0) (4000,4000) }   # full-height: bath stays enclosed

  room id=r_living at (0,0)    size 4000x4000 label "Living / Kitchen"
  room id=r_bath   at (4000,0) size 2000x4000 label "Bath"

  door   id=d_main at (1000,4000) width 1000 wall exterior  hinge left swing in
  door   id=d_bath at (4000,1500) width 800  wall partition hinge left swing in
  window at (2000,0) width 1800 wall exterior

  furniture kitchen_sink at (300,300) size 800x600   # draws a real sink symbol
  furniture wc           at (5300,300) size 400x700  # …and a WC

  title { project "One-bed" drawn_by "ArchCanvas" date "2026" }
}

The full, lint-clean flagship example (enclosed bath off a central hall, fitted kitchen + bath, dimension strings) is examples/studio.arch.

Try it live

archlang-playground.vercel.app — a client-side Vite + CodeMirror 6 editor with syntax highlighting, inline lint (fed by the compiler's diagnostics), live SVG preview, example plans, and SVG / PNG / DXF / PDF download. Nothing is sent to a server.

To run it locally from the repo root (npm workspaces):

npm install            # bootstraps all workspaces
npm run playground:dev # builds the core, then opens the playground dev server

Editor support

Install the ArchLang VS Code extension (ext install ChanMeng.archlang) for syntax highlighting and full language support — live diagnostics, hover, completion, go-to-definition, rename, and signature help — on .arch files.

Documentation

• Docs site — the hosted guide, reference, error catalog, examples gallery, and ADRs.
• spec.llm.md — the whole language in one page (~2k tokens) for AI agents; also arch spec.
• SKILL.md — the agent Skill: how to author plans via the CLI (spec → compile → describe → lint).
• Language Reference — every statement, with syntax and defaults.
• Error catalog — every E_*/W_* code with a cause and a fix.
• Architecture Decision Records — the key design decisions and their trade-offs.
• Examples — studio, two-bed, parametric, themed, relational.
• AGENTS.md — orientation for AI agents working in this repo (current status + architecture).
• Build the docs site locally with npm run docs:build (VitePress, in docs-site/).

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.

---