Use when the user wants to create, edit, or inspect an architectural floor plan / building layout as code — e.g. "draw a 2-bedroom apartment", "add a bathroom to this plan", "make the bedroom 1 m wider", "lay out an office floor". ArchLang is a tiny text language that compiles a .arch file to a professional floor-plan drawing (SVG/PNG/PDF/DXF). Drive it entirely through the archlang CLI; do not hand-render.
ArchLang — author floor plans as code
ArchLang turns a small .arch text file into a professional floor-plan drawing. It is built for
agents: deterministic, self-correcting (errors carry a machine code, a prose fix, and often a
machine-applicable fix archlang fix can apply), and verifiable without ever looking at an image
(archlang describe).
Before you write or edit
- Ask the units, and whether each size is nominal (to wall centrelines), outside or clear (net),
before the first room. Plan numbers are millimetres on centrelines: one room
size 10000x8000withwalls from rooms exterior 200 partition 100is 10,200 x 8,200 outside and 9,800 x 7,800 clear, so 10 x 8 m clear is10200x8200and 10 x 8 m outside is9800x7800. That one-thickness rule holds for a room ringed by the shell; a room beside a partition loses half of each wall it stands on.archlang describe plan.arch --json --select bbox,bbox_outergives the centreline and outside sizes,net_area_m2the clear floor, andkeep min clear <room> <mm>checks a room's narrower clear span (a broken one quotes both spans). - Edit in place, never redraw. Change the fewest statements the request needs, and lock the
authored ids (
id=) it does not name.archlang impact plan.arch --set W=3600 --lock bedroompreviews a change to aletand writes nothing;archlang impact new.arch --against plan.arch --lock bedroomchecks an edited copy. Exit2isE_LOCKED_ELEMENT_CHANGED(change the edit, not the lock) orE_LOCK_UNNAMED(the lock names no authored id, or one only above the lowest storey, which locks do not compare yet). Put sizes a brief may change inlets insideplan, so a resize is one--set, not a coordinate hunt. - A number the brief fixes is a
keep(keep min clear living 3800): it moves nothing, and a broken one isW_KEEP_VIOLATEDwith a signed residual, failingvalidate --strict. - A straight
stairis entered at one end: withdir upthe end of its long axis with the larger coordinate (the bottom of a portrait footprint, the right of a landscape one), withdir downthe other. Keep a landing clear there (W_STAIR_NO_LANDING); to enter from the other end,placeit mirrored (archlang spec,stair).
What ArchLang can do
- Compile
.archto SVG, DXF, TXT, PDF, PNG or Plan JSON; it never reads images, so a plan from a photo is written by you. validate --strictandlintcheck soundness (doors on walls, reachability, clearances) and give a fix per finding.describereports rooms, areas and adjacency;takeoffreports quantities as csv or md.fix,repairandfinishrewrite the source; each takes--dry-runto preview first.--expected-hash <source_hash>on those refuses a stale file (exit 4).impact --against old.arch --lock <ids>exits 2 when a locked element moved: edit in place, never redraw.impact --set NAME=valueshows what one top-levelletwould move.keeplines in the plan hold a relation through every edit and report a residual.levelblocks give storeys;axesgives one grid;keep stackedaligns shafts.validate --intentchecks a plan against a brief;scoremeasures it.- Plan JSON in (
compile --from-json) and out (-f json). linkprints a playground URL;previewrenders a PNG.
Setup (zero-install)
The CLI runs straight from npm — no clone, no build:
npx -y @chanmeng666/archlang --help
Or npm i -g @chanmeng666/archlang for a global archlang command. Every call below is written
archlang <cmd>; without the global install, write npx -y @chanmeng666/archlang <cmd>. Never run
a bare arch: the package installs it as an alias, but on Linux, macOS and Git Bash coreutils
owns that name, so the shell runs the wrong program.
The loop (always follow this)
- Learn the language first. Run
archlang specand read it — the entire language in one page. (archlang contextprints everything: spec + this workflow + CLI reference + error catalog; a small model starts witharchlang context --level starter, one screen.) Do this before writing any.arch. - Write the plan to a
.archfile (or pipe via stdin with-), preferring the placement sugar below so you never hand-compute a coordinate. - Render it:
archlang compile plan.arch -o plan.svg --json. The JSON is{ ok, diagnostics, summary }. - Auto-fix the mechanical faults: if
okis false, runarchlang fix plan.arch --dry-run --jsonto preview the machine-applicable edits (off-wall opening → attachment form, out-of-range position clamped, …), then re-run without--dry-runto apply. Anythingfixcan't resolve stays indiagnostics[].fixfor you to edit by hand. Exit code2means a deterministic user error — fix it, don't blindly retry (1= IO/internal,3= bad usage). - See the plan without an image:
archlang compile plan.arch -f txt(orarchlang preview plan.arch --ascii) prints a zero-dependency ASCII floor plan you can read straight from stdout. - Verify intent:
archlang describe plan.arch --jsonreturns the rooms (areas, adjacency), what each door connects, and totals. Confirm the room count, labels, and areas match what was asked. Each room reports two areas:area_m2on wall centrelines andnet_area_m2, the floor no wall stands on (the room less every wall band inside it, computed exactly, or absent when it cannot be, and then so is the net total);totalssums both. Quotenet_area_m2as floor area, and name which figure you report. - Gate on soundness — don't ship a flagged plan.
archlang validate plan.arch --strict --json(parse + resolve + lint).--strictmakes every advisory warning fail (exit2) — the gate a generation pipeline runs before it ships. Add--graph g.jsonto also assert the intended room-to-room adjacency ({ "living": ["kitchen","hall"], … }); a mismatch fails. Read eachdiagnostics[].fix, edit, and re-run until it passes — or, if a warning is deliberate, say so. The author's loop is compile →validate --json(fix itsnextfirst) → lint → repair, one stage at a time: the rooms (with stairs and outdoor surfaces), thenarchlang validate plan.arch --stage rooms --jsonuntilat_stage.cleanis true; then the walls (walls from rooms) and--stage walls; then doors and windows,--stage openings; then fixtures and furniture,--stage fixtures; then the sheet and the fullvalidate --strict. Advance when the stage is clean, or when every remaining finding is one you accept and say so: a later stage's findings are held back (thesummarycounts them), because they mean nothing until the earlier decisions stand; errors always show. Clean is not permanent: a later stage can add or re-raise an earlier stage's finding (walls narrow a room to its clear width, a bed makes a double, furniture pinches a walk), and each later stage shows the earlier stages' codes again. Read thesummary(first key oflint|validate --json, first line of the text report) before anything else: it counts the warnings and the distinct codes and leads with the commonest, so a truncated read still tells you how much is hidden. The order inside the loop is the stage list,brief → rooms → walls → openings → fixtures → drafting, and within a stage: columns, then the exterior walls, then the other walls, then fences; doors, then windows, then plain openings; catalogued fixtures, then loose furniture; dimensions, labels and the sheet last. Rooms (with stairs, voids and outdoor surfaces) come first because they fix the program and the walls can be derived from them; the exterior goes before the interior; an opening is cut into a wall that must already exist; drafting reads everything else. This is authoring order only: the order shapes are painted in the SVG is a separate thing and does not change. Review, once that loop is clean: the reviewer (not the author) runsarchlang score plan.arch --taste generic --jsonand reads the advice: a sourced 0–1 score (privacy gradient, daylight, proportion, corner doors, …) whosecriteria[].adviceA_*codes name what to improve. It never gates, the author does not iterate on it, and a score capped at 0.5 means a validity lint warning still stands. The reviewer then looks atarchlang preview plan.arch --review -o review.png: every warned element ringed and numbered on the plan, a legend, and close-ups of flagged openings and pieces. On a lint-clean plan it still shows the access graph (which rooms each door joins, which rooms the entrance reaches) and which door is the main entrance or that the choice is a tie: check those against the brief. If no one reviews for you, run both once after the loop is clean and report the score and itsA_*advice; do not iterate on it. Editing a plan that already exists starts differently, before the steps above:archlang validate plan.arch --jsonto record the starting state, then choose the ids the request does not name and lock them.archlang impact plan.arch --set NAME=value --lock <ids>is the pre-edit check (it writes nothing);archlang impact new.arch --against plan.arch --lock <ids>is the post-edit check on an edited copy. Exit2(E_LOCKED_ELEMENT_CHANGED) means the edit moves something it should not: change the edit, not the lock. Then make the edit and run steps 3 to 7 on the result. - Check the plan against the brief. Write the user's brief as an
intent.json— its checkable expectations as data (room count, per-room concepts with area/window bands, total area, optional adjacency/reachability). A stated size binds: "about 70 m²" →grossInternalAreaM2(inside the shell's inner faces); a room's stated width/depth/W × H →roomDimensions. Two disciplines keep it brief-grounded: assert an area band only where the brief gives a number ("about/~N" → ±10%; "at least N" →minonly; qualitative words → nothing), and assert the top-level roomcountonly when the brief enumerates the rooms. Gate witharchlang validate plan.arch --intent intent.json --feedback --json: a gating miss (room count/existence/area/total-area/window/size) fails (exit2) with a per-violation correction prompt — iterate on the feedback and re-run. Adjacency/reachability are advisory (reported, never fail the gate). Usearchlang score plan.arch --brief intent.json --jsonas a continuous satisfaction meter (always exit0) to watch the plan approach the brief across edits. See/intent.schema.json. A number or relation the brief fixes and every edit must keep (a 3.6 m clear living room, a partition on axis 2, a bathroom over a bathroom) goes in the source as akeep(keep min clear living 3600); it moves and draws nothing, a broken hard keep (the default) isW_KEEP_VIOLATEDwith a signed residual and fails--strict, andarchlang impact --setlists which keeps a change breaks, holds or heals, each with its residual before and after. - Fix furniture geometry:
archlang repair plan.arch -o fixed.archpushes furniture out of walls/doorways/swing arcs (the geometric corrector; distinct fromfix). It rewrites a piece in the form you wrote it (anatpoint, or theinsetof anin <room> anchor …placement) — and always readunresolved: a piece it may not rewrite (onefor/component statement drawing several pieces, expression coordinates, anagainst wallanchor) is reported there with the fault and why, never silently skipped.changed: falsewith a non-emptyunresolvedmeans you edit the source. - Finish the drawing: once lint is clean, run
archlang finish plan.arch --dry-run --json, then without--dry-runto apply. It first furnishes each rectangular or L-shaped room that holds no furniture, by the room's use (on every storey; a furnished room is never touched — a partly furnished one is named inunresolvedwith the categories it lacks, not topped up), then adds the sheet statements the plan lacks —paper,scale,dims auto,title,schedule rooms,legend— on the smallest sheet the drawing fits. It fills only what is missing and deletes nothing. Readunresolved: a room it left empty or a statement it left out is named there with the reason. A room it has no pieces for (a hall, a store, a room of no known use) is named too, withscope: "outside-table"; that note asks nothing of you unless the room should hold furniture, sochanged: falsewith only such notes means the plan is finished (--only furnish/--only sheetruns one step;--reissuelets it replace apaper/scalethe drawing does not fit). - Show the user:
archlang preview plan.arch -o plan.pngrenders a PNG (--installfetches the optional renderer if missing). To hand the user the plan itself, rendered and with nothing to install, runarchlang link plan.arch(ornpx -y @chanmeng666/archlang link plan.arch): it prints a playground URL that opens the plan;--jsonadds the embed URL.
Write it right the first time (placement sugar — the preferred path)
A geometry-blind generator that emits absolute coordinates produces plans that render but are physically wrong (openings off their wall, furniture through walls). Author by relation instead — the compiler computes the coordinate, and fails loudly if the reference is ambiguous.
Start from the rooms. Write the rooms (a corridor is a room), let walls from rooms derive
every wall, and host each opening by the rooms it joins. This plan compiles and lints clean:
plan "Room graph" {
units mm
grid 100
room id=living at (0,0) size 4000x4000 uses living
room id=hall right-of living size 1500x4000 uses hall
room id=bedroom right-of hall size 3000x4000 uses bedroom
walls from rooms exterior 200 partition 100 { open between living and hall }
door on hall.bottom at center width 900 swing into hall
door between hall and bedroom at 800 from start width 800 swing into bedroom
window on living.left width 1500
window on bedroom.right width 1200
furniture bed in bedroom anchor bottom-right flush size 1500x2000
}
- Let the rooms make the walls. When the rooms are rectangles, or polygons with only horizontal and
vertical edges, that tile the floor (write a corridor as a room),
walls from rooms exterior 200 partition 100derives the shell on their outline and a partition on every shared edge, so no wall can go missing. Host openings by the rooms:door between living and bed at 800 from end width 800(a door must say where:center,<mm> from start|end|<room>.<edge>,axis <n>, offsets to the centre),window on bed.top width 1500(centred by default). A jamb too near a meeting wall is refused (E_OPENING_NIBnames the legal spot), never slid.{ except <room> }leaves a room out. For an open-plan join writeopen between living and kitchenin the body (an opening across the whole shared edge, orwidth <mm>centred; never a door on that edge), andbetween a and b thickness 150for one thicker partition. Refusals name the rooms (E_ROOMS_OVERLAP,E_ROOMS_NOT_TILING,E_PARTITION_TOO_SHORT,E_ROOM_NOT_RECTANGLE,E_WALL_BETWEEN_NOT_ADJACENT). - Or name one wall by its rooms. For a plan that derives some walls and types others,
wall id=p partition thickness 100 between hall and bedstands on the two rooms' shared edge andwall id=shell exterior thickness 200 around [hall bed bath]is one ring on their outline (no hole). They keep your id, thickness and material, host doors like any wall, and replace the derived span besidewalls from rooms. - Read wall points off the rooms. A rectangular room
rexposesr.top,r.bottom,r.left,r.right,r.cx,r.cy, sowall partition thickness 100 { (hall.right, hall.top) (hall.right, hall.bottom) }follows the room when it grows. Use them in walls, openings, furniture and dims, not in aletor a room's ownat/size(E_DATUM_BEFORE_ROOMS). - Attach openings to a wall by position, not
at (x,y).door on <wall> at <pos> …/window on <wall> at <pos> …/opening on <wall> at <pos> …, where<pos>is millimetres along the wall or a percentage (50%).swing into <room>picks the swing direction toward a named room,swing inward|outwardtowards/away from the building's floor (in|outfollow the wall's drawn direction:in= right of travel on the page, so they flip on a wall drawn the other way);hinge near start|endhinges at the segment end nearer a wall end. (Off-wall/ambiguous →E_ATTACH_WALL_REF; past the wall →E_ATTACH_POS_RANGE.) - Lay rooms with
strip.strip right at (0,0) gap 0 height 4000 { room … room … }places a row (or column, withdown/up+width) of rooms end to end — no per-roomat. - Place furniture by anchor.
furniture <kind> in <room> anchor <9-point anchor> [flush] [inset <mm>] …snaps a piece to a room corner or edge — the anchor is one oftop-left,top,top-right,left,center,right,bottom-left,bottom,bottom-right;against wall <id>backs plumbing/kitchen fixtures onto a real wall face. Both are closed-form and never float or penetrate. - Say what a piece faces, not its
rotate.furniture chair at (…) size 450x450 facing tturns the chair to tablet(and a sofa to its TV);against <room>.<edge>backs a piece onto a derived wall;clear front 600asks lint to keep that depth free. Lint flags a chair facing away from its table (W_SEAT_FACING_AWAY). - Add
flushand never compute half a wall thickness. A room's rectangle runs along wall centerlines, so a bareanchor bottomleaves the piece's back inside the solid (W_FURNITURE_WALL_COLLISION).anchor bottom flushmeasures from the backing wall's inner face instead, andflush inset 50from 50 mm off it — so writefurniture wc in r_bath anchor bottom flush size 400x700, not aninset 100you worked out from a thickness you never named. (flushneeds an anchored edge: oncentered/anchor centerit isE_FURN_FLUSH.) - Every room still needs a way in — put a
dooror casedopeningon a wall of every room (an open-plan space still needs a modeled opening), and keep furniture out of the doorway approach (≥300 mm) and the leaf's swing. - Absolute
at (x,y)is the fallback, not the default — reach for it only when no attachment expresses what you mean.
See examples/two-bed.arch for a furnished two-bedroom flat authored this way, and archlang spec for the grammar.
Author a repeating piece ONCE, then place it (v1.22)
When a building repeats — two wings, six wards, a floor of identical units — do not copy the
statements and re-add an offset to every coordinate. That is how a plan gets 40 hand-edited numbers
that drift apart the first time the brief changes. Author the piece in its own coordinates from
(0,0) and place it:
component wing() {
wall id=shell exterior thickness 300 { (0,0) (18000,0) (18000,12000) (0,12000) close }
room id=main at (0,0) size 18000x9000 label "Gallery" uses living
room id=corr at (0,9000) size 18000x3000 label "Corridor" uses circulation
}
place wing() as west at (0,0)
place wing() as east at (42000,0) mirror x
asnames the instance,atplaces it; both are required. Ids inside becomewest.main/east.main, and you address them by that dotted name everywhere a reference is taken:wall west.shell,in west.main,archlang describe --room west.main. (A dotted name in a declaration isE_DOTTED_DECL— the namespace belongs to theplace.)rotate 0|90|180|270andmirror x|yare exact, and a mirror is real physics: door swings, fire exits and fixture facings all come out mirror-image. Prefermirror xoverrotate 180for a symmetrical pair — a 180° turn also swaps which side the corridor is on.- A whole FILE can be the component:
import "wing.arch" as wingbinds that file's top-level drawable statements as a zero-argument component (its plan settings are ignored — the root plan owns the sheet). One file, one room or wing, exactly as you would organise components in code. - A
placed instance is also a zone, sodescribe().zones,archlang describe --zone westand the groupedschedule roomstable work with no extra declaration. - The bare call
wing()is the OLD inline macro — caller's coordinates, caller's id counters, no namespace. Keep it for a small parameterised motif; useplacefor a piece of building. - A component is a closed world going out: the plan can reach into it (
wall west.shell), but the component cannot reach out. Let the parent draw the connecting doors — that is the whole composition contract. Verify witharchlang describe --json→instances[].
See examples/museum-wing.arch + examples/museum-wings.arch.
Self-correct with data, not guesswork
archlang compile --json returns every problem as a Diagnostic with a byte span, line/col, a
catalogued E_*/W_* code, and a prose fix. Where the correction is a mechanical text edit, the
diagnostic also carries machine-applicable fixes:
archlang fixapplies them in a bounded, self-checking fixpoint — onlymachine-applicableby default (--unsafealso appliesmaybe-incorrect;--dry-runpreviews;--forcekeeps a pass that would otherwise roll back). Use it to clear the syntactic faults before you touch anything by hand.archlang fixis syntactic;archlang repairis geometric.fixrewrites text where the right text is known (e.g. an off-wall door → the attachment form);repairmoves furniture to a position no text edit could express. They compose — fix first, then repair.archlang fixalso applies fix-carrying lint advisories, not only compile-stage faults — e.g.W_ALIAS_MATCH(a room's use inferred from an indirect label alias) fixes by inserting the explicituses …it inferred. Before editing,archlang describe --json'sfreedomblock tells you which element positions were hand-authored (absolute) vs derived by the resolver (relational/strip/attached/anchored/against-wall), so you know which numbers are safe to nudge.
Fix the topology: add doors & windows the room graph needs
fix/repair never add a door or a window — where to put one is a design choice the compiler must
not make. When lint reports W_ROOM_UNREACHABLE, W_ROOM_DISCONNECTED, W_NO_ENTRANCE,
W_BATH_VIA_BEDROOM, or W_BEDROOM_NO_WINDOW, ask ArchLang for candidates:
archlang suggest plan.arch --jsonreturns ready-to-pastedoor/windowstatements (furniture-aware — a door candidate never opens onto a wardrobe; each references its wall by a stable ref — an authored id or a unique category — or absolute coordinates, never a re-bindable positional id) plus a rationale for each — for a room with no path back (W_ROOM_UNREACHABLE), a building with no way in (W_NO_ENTRANCE), a bath reachable only through a bedroom (W_BATH_VIA_BEDROOM), or a windowless bedroom (W_BEDROOM_NO_WINDOW). Choose one and insert it, then re-run the loop. This replaces hand-computing coordinates.- Manual fallback (if
suggestoffers nothing that fits): fromdescribe().access, connect each unreachable room in priority — (1) a new exterior entrancedoor on <exterior wall> at <pos>into a living/kitchen/hall with an exterior edge (avoids routing through a bedroom); else (2) adoor on <shared wall> at <pos>to an adjacent reachable, non-bedroom room; and give a windowless bedroom awindow on <its exterior wall> at <pos> width 1200. Never make a bathroom reachable only through a bedroom. Thenarchlang repair(a new door may pinch furniture) and re-gate.
An existing opening
validatereports off its wall (W_DOOR_OFF_WALL/W_WINDOW_OFF_WALL/W_OPENING_OFF_WALL) is a mis-coordinate, not a missing connector — runarchlang fix(it rewrites it to the attachment form) rather than adding a new one.
Pick the door KIND before you widen the room
A window has a kind too: fixed · casement · tilt · tilt_turn · sliding. Left out, it draws as a plain window. Only
casement and tilt_turn take hinge left|right. fixed and tilt are no way onto a balcony.
A door has a kind — hinged (the default) · sliding · barn · bifold · pocket · garage ·
double · glazed_sliding (a glass terrace door) — and it changes what the checks can say, not just the drawing. Only hinged and double
(two leaves, one per jamb) sweep arcs, so W_SWING_OBSTRUCTED cannot apply to any of the others.
A hinged leaf over 1219 mm raises W_LEAF_TOO_WIDE: a wide doorway is a double door.
That makes the kind a legitimate answer to a diagnostic, and often the right one:
W_SWING_OBSTRUCTEDon a door into a tight room — aslidingorpocketleaf sweeps nothing, so the warning goes away because the plan genuinely fixed it, not because you silenced a rule. Moving the furniture is the alternative; pick whichever the brief actually wants.- A
pocketearns its own check instead:W_POCKET_RUNmeasures the wall the panel must slide into. Swapping one warning for the other is a real trade, so read the new one rather than assuming a win. - Clauses are kind-specific and a wrong pairing refuses (
E_DOOR_KIND_CLAUSE):hingeis hinged-only,slide/openare sliding-family-only, andgaragetakes no clause at all — which side it parks on is derived from which face has floor. A kind other thanhingedordoubleon anarcwall also refuses (E_DOOR_KIND_CURVED).
A window has a kind too, when the source says so: fixed · casement · tilt · tilt_turn ·
sliding. It shows in describe, the schedule and the legend. hinge goes on casement and
tilt_turn only, and only when the side is known: never guess one.
archlang spec has the full grammar; examples/bungalow.arch is the worked plan.
Declare site when the brief mentions orientation
site { street <north|south|east|west> [hemisphere …] } draws nothing. It exists so orientation
becomes a fact the tools can check, and without it two things silently cannot run:
describe --jsongains asiteblock naming five directions —street,back,equator_side,sunrise_side,sunset_side— and an intent'swindows.facingmay assert those names. With nositedeclared, that assertion fails withE_INTENT_NO_SITErather than passing vacuously.W_ROOM_NOT_EQUATOR_FACINGis the one rule that reads it, flagging a room whose windows all face away from the equator side.
So: if the brief says "south-facing living room", "morning light in the kitchen", or "faces the
street", declare site first — otherwise you have written a plan whose central requirement nothing
can verify. It is a drafting heuristic for an aspect, not a daylight measurement: there is no sun
model, no latitude and no date, and _side names must not be read as more than an orientation.
examples/bungalow.arch demonstrates both this and the door kinds above.
Write a height only when the brief gives one
height <mm> (plan, level or wall) and sill/head on an opening are the vertical datum:
they draw nothing, because a plan is a horizontal cut, and describe --json reports them only if
the source wrote one — so adding a height you were not asked for changes what every consumer sees
for no gain. Write them when the brief names a ceiling, a parapet or a cill line; otherwise leave
them out and read the defaults from archlang manifest --json's datum block.
Ask the CLI, and read only what you need
The CLI documents itself, and every read can be narrowed at the source — never pull a whole plan's facts into context just to filter them yourself.
archlang <cmd> --helpprints that one command's flags and worked examples — every command carries at least one copy-pasteable invocation.archlang --helplists the commands;archlang --versionprints the version. A flag a command doesn't take is a usage error (exit3) with a did-you-mean, never a silently-swallowed filename — so a typo fails loudly instead of compiling the wrong thing.archlang describe --select <keys>emits only the named top-level keys (rooms,doors,windows,openings,furniture,access,circulation,totals,freedom,caption, …); theok/plan/units/diagnosticsenvelope is always kept, so narrowing can't lose the verdict.archlang describe --room <ids>keeps only those rooms plus the doors/windows/furniture that touch them (whole-plan facts —bbox,totals,caption, each room'sadjacent— stay whole-plan, so a narrowed read never lies about the building). Both mark the result withfiltered: true.archlang lint|validate --code <CODE,…>/--severity error|warningshow only the diagnostics you asked for. These are display filters only:okand the exit code are always computed from the unfiltered set, so reading less can never turn a failing plan green. A filtered result carriesfiltered: true+total_diagnostics.archlang context --section spec|workflow|cli|errorsprints one section of the bundle instead of all of it (about 180 KB in all) —errorsfor the diagnostic catalog,clifor the command reference.archlang fix --dry-runprints the exact unified diff it would write (to stderr;--jsonalso carries it asdiff) and touches nothing. When you do apply in place,--backupkeeps the original bytes at<file>.bak.
Structured authoring & constrained generation (optional)
- Plan JSON. Author or ingest the machine-native shape and compile it:
archlang compile plan.json --from-json -o out.svg. The schema is served at/plan.schema.json. - GBNF. To force a local model to emit only parseable ArchLang, constrain decoding with
/archlang.gbnf.
Commands
archlang spec # the whole language in one page — READ THIS FIRST
archlang context # everything in one call: spec + this workflow + CLI reference + error catalog
archlang context --section errors # just one section of it (spec|workflow|cli|errors)
archlang --help # list the commands
archlang manifest --json # the whole CLI API as data: commands, flags, formats, lint rules, error codes
archlang compile plan.arch -o out.svg --json # render (also -f dxf|txt|json|pdf|png)
archlang compile plan.arch -f txt # zero-dependency ASCII text plan on stdout
archlang compile plan.json --from-json -o out.svg # compile structured Plan JSON (see /plan.schema.json)
archlang import --from openplan3d plan.openplan.json -o plan.arch --json # an OpenPlan3D JSON plan as .arch + a report of what it left out; then lint it
echo '<source>' | archlang compile - -o - -f svg # compile stdin → SVG on stdout
archlang fix plan.arch --dry-run --json # preview the machine-applicable fixes as a unified diff (drop --dry-run to apply; --backup keeps <file>.bak)
archlang suggest plan.arch --json # advisory door/window statements: unreachable room / no entrance / bath-via-bedroom / windowless bedroom
archlang describe plan.arch --json # semantic facts: rooms, areas, adjacency, door connections, circulation
archlang describe plan.arch --select rooms,totals --room kitchen --json # narrow the facts to what you actually need
archlang impact plan.arch --set W=4500 --json # change one let: what moved and why, what held, what broke or healed
archlang lint plan.arch --json # architectural soundness warnings
archlang lint plan.arch --code W_NO_ENTRANCE --json # display filter only — never changes `ok` or the exit code
archlang validate plan.arch --strict --json # parse + resolve + lint; --strict fails on warnings (the ship gate)
archlang validate plan.arch --graph g.json --json # also check interior-door adjacency against an intended graph
archlang repair plan.arch -o fixed.arch # geometric corrector: furniture out of walls/doorways/swings + change log
archlang finish plan.arch --dry-run --json # after lint is clean: preview the furniture and sheet statements it would add (drop --dry-run to apply)
archlang fmt plan.arch --write # canonical formatting
archlang batch a.arch b.arch -f svg --json # render many plans/variants at once → results[]
archlang preview plan.arch -o plan.png # render a PNG to SHOW the user (--install fetches resvg if missing)
archlang new -o plan.arch # scaffold a starter plan
archlang explain E_ROOM_SIZE --json # look up any diagnostic code
(An optional MCP server, @chanmeng666/archlang-mcp, wraps these same library functions for
MCP-native hosts — prefer the CLI when you have a shell; it costs nothing in context until called.)
Key rules (full detail in archlang spec)
- Units are millimetres (a 4 m wall is
4000); origin top-left, +x right, +y DOWN. An optional metric suffix is exact sugar for the same mm value —4m=4000,40cm=400,20mm=20— so you can write4minstead of hand-multiplying; bare numbers are unchanged. - Attach openings to walls (
on <wall> at <pos>) so they always sit on a segment; a rawatthat lands off any wall warns (andarchlang fixrewrites it). - Furniture draws real symbols, not boxes. Every catalogued kind (
archlang manifest --json→fixtureCategories) renders a plan symbol and ignoreslabel; an uncatalogued word falls back to a labelled rectangle. Most kinds also carry a footprint, sofurniture <kind> against wall <id> in <room>needs nosize—offsetis the piece's CENTRE along the wall run. Put fixtures in every bath and kitchen so lint stays quiet. dims autodraws dimension strings for you (overall,rooms,walls, orall).- Edit is cheap: "make the bedroom 1 m wider" is a one-number change, then recompile.
Treat the CLI as the source of truth — author, render, and verify through it rather than reasoning about SVG by hand.
Task skills
Four short skills sit beside this one in skills/, one job each
(npx skills add ChanMeng666/archlang offers them with this one). Each is a
checklist of CLI calls and holds no language reference of its own:
archlang-brief-to-plan: write a new plan from a written brief and check it against the brief.archlang-edit-plan: change an existing.archwith the smallest edit, then re-verify.archlang-export: deliver SVG, PNG, PDF or DXF files, with paper size, scale and storeys.archlang-review-plan: check a plan (lint profiles, the intent gate, suggestions) without editing it.
- Downloads
- 620All time
- Security audit
- Review
- Last updated
- 1d ago
- Current version
- v1.66.0
- License
- MIT-0
