ArchLang floor-plan DSL and compiler: who it's for, a 3-minute first run, and usage boundaries

Who it's for

• Best for two groups: those who want an agent to write the floor-plan source for them and then compile it — the official positioning is “write .arch source, or have an AI agent write it” — and those who need SVG, DXF or PDF floor plans quickly, gating the source with lint and geometric validation.
• It also suits anyone putting plan checks into scripts: describe and validate both support --json output, which makes the state of the source easy to judge programmatically.
• It keeps floor plans as code: the source file is plain text, layout descriptions are reproducible and diffable, and easy to hand to an agent for changes; the compiled artifact is a drawing file in a vector or document format.
• Prerequisites: every official command runs an npm package through npx, so your machine must be able to run npx; the primary install path targets the skills of a coding agent, and the CLI subcommands run in a terminal without connecting to an MCP client.
• Not a fit, and unknowns: the evidence shows no visual editing or drag-and-drop drawing, so it does not suit people who want WYSIWYG drawing; no .arch syntax sample appears in the evidence, so the first source file must be written by you or by an agent; the precision and standards compliance of formal engineering drawings, the supported operating systems, and the license are all left unsaid.

A first run in 3 minutes

There is only one primary path: the skills install, in four steps.

1. Prerequisite: npx works in your terminal; the official commands themselves contain no keys or account parameters, so no credentials need preparing in advance. Whether any other environment setup is required is left unsaid.
2. Install: run npx -y skills add ChanMeng666/archlang --yes to install this repository's skills for your coding agent.
3. A low-cost first try: run npx -y @chanmeng666/archlang context. Its official positioning is “the whole ArchLang language in a single call”, so an agent does not need to preload any language knowledge. Success signal: the terminal prints the language description. Whether the command touches the network, and its other read/write details, are left unsaid.
4. Get the first artifact: once you have a plan.arch, run npx -y @chanmeng666/archlang compile plan.arch -o plan.svg --json; the success signal is a plan.svg generated locally together with JSON status output. Note that compile writes a local file — a local write, not a read-only operation — so it is best run after you have confirmed what the source contains.

Secondary note (another official path, not a peer of the primary one): an MCP client can run claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp, which launches the separate npm package @chanmeng666/archlang-mcp through npx and registers a server named archlang; which MCP tools that server exposes once registered is left unsaid.

Use cases

Case one: inspect before compiling. Scenario: you already have a plan.arch and want to confirm the content is trustworthy before a drawing comes out. Approach: run describe plan.arch --json first to read the structural description, then validate plan.arch --strict --json for strict validation — both share the same command prefix as compile; after fixing the source according to the validation results, recompile, which is exactly the fix-then-recompile workflow given officially. What to expect: description and validation results in JSON, with geometry problems surfacing before anything is compiled into a drawing. Both commands carry --json, so they slot into scripts as a pre-compile check; the exact field structure of the validation output is not given in the evidence.

Case two: let the agent write the drawing. Scenario: you are not familiar with .arch syntax and want to hand the source over to an agent. Approach: run npx -y @chanmeng666/archlang context first to hand the agent the entire language in one go — officially stated as requiring no preloaded language knowledge; then let the agent produce the .arch source; finally compile it into a drawing with the compile command. The source comes from the agent, while compiling and validation stay with local commands. What to expect: the source and your first plan.svg. The project's positioning supports SVG, DXF or PDF output, but the verbatim, copy-ready compile command in the evidence covers SVG only; the exact output parameters for DXF and PDF are unconfirmed — do not extrapolate them on your own.

Usage boundaries

• Read/write nature: compile reads plan.arch and writes plan.svg locally as directed by -o, an explicit local write; describe, validate and context are not officially labeled read-only tools, context is only described as printing the language description, and their other read/write details are left unsaid.
• Credentials and configuration: none of the official commands above carry key or token parameters, and no required personal fields such as name or email appear; whether any extra environment configuration exists is left unsaid.
• Telling the paths apart: the first run in this article rests on CLI subcommands plus the skills install; if your goal is for an agent inside an MCP client to make the calls, the registration command must be run separately — the two paths install different things under different prerequisites.
• Side effects and checkpoints: compile writes a local file, so confirm the output path before running; no undo path is officially described, so it should not be called “reversible”. Where exactly the skills install writes is left unsaid.
• The two artifacts are independent of each other: the skills install targets the skill package for agents; claude mcp add registers a different npm package. Their relationship, and whether installing only one of them suffices, are left unsaid.
• License, supported platforms, network behavior, and data boundaries never appear in the evidence; “nothing found” does not mean “no risk”, and this article draws no independent security conclusions.