Locus is a relational language and CLI for deterministic plane-geometry figures and technical diagrams. Declare geometric relationships, verify them with assertions, and export SVG or PNG.
Designed for AI agents and people, Locus provides structured diagnostics and
stable JSON feedback so figures can be created, inspected, and revised through text.
Diffable .locus source files make changes reproducible and auditable.
Under active development; breaking changes are expected. Only files starting
with locus 0 beta 7 are accepted. The specification
defines the current language and toolchain contract.
Quick start · Examples · CLI guide · Specification
- Geometry through relationships. Define distances, alignment, tangency, containment, and separation; derive further objects from those relationships.
- Reusable diagrams. Compose functions, named instances, and ordered groups. Labels are measured before solving so text can determine shape sizes and layout.
- Feedback for revision. Check assertions, inspect selected measurements, and use source-linked diagnostics to locate errors.
- Self-contained rendering. Bundled text and math fonts support SVG and optional PNG output without installed fonts or an external TeX process.
Install Rust with Cargo and rustup. The repository pins Rust 1.94.0 in
rust-toolchain.toml.
Build and install the CLI from source:
git clone https://github.com/Tackoil/locus.git
cd locus
cargo install --locked --path crates/locus-cli
locus --versionEnsure Cargo's binary directory (usually ~/.cargo/bin) is on your PATH.
Then validate and render a bundled example:
locus check examples/demonstrations/point_relations.locus
locus render examples/demonstrations/point_relations.locus -o figure.svgOpen figure.svg in a browser or image viewer. To run without installing,
replace locus with cargo run --release --locked -p locus-cli --.
Save this as triangle.locus:
locus 0 beta 7
style textbook
point A()
point B() where { align_center_y(A, B), hdist(A, B) == 4 }
point C() where { align_center_x(A, C), vdist(A, C) == 3 }
polygon triangle(A, B, C)
label lA(A, $A$) { dir: SW }
label lB(B, $B$) { dir: SE }
label lC(C, $C$) { dir: NW }
assert dist(B, C) == 5
assert area(triangle) == 6
The relations align the triangle's legs and set their lengths. The assertions verify the resulting hypotenuse and area.
locus check triangle.locus
locus render triangle.locus -o triangle.svgExplore geometry and diagram examples, including tangent circles, flowcharts, sequence diagrams, architecture, and charts. The example corpus also covers stress workloads and rendering checks.
Use check as the validation step before rendering. Start with the default
concise, deterministic plain text for agent feedback, then request specific
measurements when investigating a problem:
locus check triangle.locus
locus inspect triangle.locus --distance B C
locus inspect triangle.locus --angle B A C
locus describe triangle.locus --jsonPlain text is agent-oriented feedback, not a stable schema. Integrations should
use --json, which remains the unchanged full, pretty-printed JSON with a stable
schema. The temporary --human flag selects the existing rich human output and
conflicts with --json; --compact has been removed. Angles are returned in
radians; the middle point is the vertex.
For stricter visual validation, include annotation placement and fail on warnings:
locus check triangle.locus --layout --strictEvery check measures declared text and validates required routing, path-label
placement, and clipping. --layout adds annotation collision diagnostics.
Warnings are non-fatal unless --strict is set. Incomplete layout-preference
settling can produce a warning even when hard requirements are satisfied, so
visual review remains part of authoring.
| Exit code | Meaning |
|---|---|
0 |
Success; all assertions pass |
1 |
Failed assertions, or warnings with check --strict |
2 |
Evaluation, construction, dependency, solve, or layout failure |
3 |
Usage or parse error |
Create and revise figures by writing or editing complete .locus source files
directly. After saving changes, run locus check triangle.locus; once it passes,
run locus render triangle.locus -o triangle.svg and review the image. See the
CLI guide for report details and the
authoring skill for the agent workflow.
locus render triangle.locus -o triangle.svg
locus render triangle.locus --stdout > triangle.svgSVG is the default; output extensions do not select the format. The default
background is transparent; use --background white for an opaque background.
render --stdout still emits only the raw artifact, and fmt still emits
formatted source rather than a status report (fmt --json emits the AST).
Rendering evaluates the source independently and can export a figure with failed
assertions, so a successful render does not replace check.
PNG requires the optional png build feature. From the repository root:
cargo run --release --locked -p locus-cli --features png -- \
render triangle.locus --png --background white --dpi 300 -o triangle.pngAlternatively, add --features png to the installation command to enable
locus render --png. See the rendering guide for DPI,
font support, output options, and TeX limitations.
Capture solver and layout steps in an offline HTML viewer:
locus render triangle.locus -o triangle.svg --dump triangle.trace.json
locus visualize triangle.trace.json -o triangle.trace.htmlDump capture is opt-in and adds runtime and memory overhead. The viewer includes
the source, intermediate results, geometry previews, and interactive relationships.
Add --timings or --timings=json to any command for
pipeline timing metrics on stderr.
| Resource | Purpose |
|---|---|
| Language specification | Normative syntax, relations, solver semantics, and CLI contract |
| CLI guide | Detailed checks, diagnostics, rendering, dumps, and timings |
| Development guide | Full validation commands, rejected-request archives, and license notice generation |
| Scene stages and compilation | Source, evaluation, layout, and compiled-scene responsibilities and guarantees |
| Authoring skill | Beta 7 authoring and verification workflow for agents |
| Drawing benchmark | Native agent comparison of Locus and handwritten SVG on shared tasks |
| Zed extension | Highlighting, diagnostics, completion, hover, navigation, and formatting |
| WebAssembly library | Browser SVG rendering with the same measured solve/layout pipeline |
| Project website | Introduction, demo gallery, browser playground, and documentation build |
See CONTRIBUTING.md for the contribution workflow and Rust style policy.
Run these checks from the repository root; the source audit requires Python 3:
python3 scripts/check_examples.py
cargo fmt --all -- --check
cargo clippy --workspace --all-features --all-targets -- -D warnings
cargo test --workspace --all-features --all-targetsDebug/dev CLI builds archive failed invocations, including source and submitted
input, under .locus/rejected-requests/. Release builds disable this feature.
See the development guide for archive controls and the full
validation workflow.
| Directory | Contents |
|---|---|
crates/ |
Rust libraries, CLI, language server, WebAssembly bindings, and crate-local tests |
spec/ |
Normative specification and reference diagrams |
examples/, tests/ |
Runnable figures, shared fixtures, expected outputs, and stress tests |
docs/ |
CLI and development guides |
scripts/ |
Source and third-party notice audits |
ecosystem/ |
Tree-sitter grammar and Zed integration |
skills/locus/, benchmarks/ |
Agent authoring reference and drawing benchmarks |
assets/, website/ |
Project artwork and website |
licenses/, vendor/ |
Third-party provenance and pinned dependency patches |
Locus's own code is available under either the MIT license or the Apache License, Version 2.0, at your option. Dependencies and bundled fonts retain their own terms; preserve the applicable third-party notices when distributing them.
Before preparing a release: ordinary CLI builds include ReX, whose upstream license documentation is incomplete and whose generated tables have unresolved provenance questions. Review the ReX licensing investigation for the evidence and outstanding items.