Axle Keys — local CAD engine

Build parametric CAD models in JavaScript, run them on your own machine, and get the same verdict axlekeys.com gives — offline, and fast enough to sit inside a loop rather than beside one. A simple part rebuilds in about 30ms on a warm kernel; a cabinet with dado joints cut into both sides costs about 350ms. The kernel starts once, so watch, repl and sweep pay that startup a single time.

This is what a verdict looks like. Real output, captured by this repo's release check from the example it ships:

$ node packages/engine/cli.mjs build examples/side-table.js
✓ built in 470ms — 5 part(s)
  overall    450.0 ×   450.0 ×   500.0 mm

   Top                  450.0 ×   450.0 ×    25.0
   Leg 1                 40.0 ×    40.0 ×   475.0
   Leg 2                 40.0 ×    40.0 ×   475.0
   Leg 3                 40.0 ×    40.0 ×   475.0
   Leg 4                 40.0 ×    40.0 ×   475.0

  Solid volumes measured — 5 exactly filling its blank. A part with no note above fills its rectangular blank EXACTLY, so nothing has been taken out of it and a cut you expected there did not land. A part measuring short is either cut or simply not box-shaped (a cylinder is 78.5% of its box); volume cannot separate those, and measure(part) names the number.

  no problems.

Push a parameter past what the model declares and the same command says what went wrong — with the shared volume measured, not inferred from bounding boxes:

$ node packages/engine/cli.mjs build examples/drawer-box.js --param clearance=-1
✓ built in 893ms — 6 part(s)
  overall    400.0 ×   470.0 ×   200.0 mm

   Side L                18.0 ×   350.0 ×   200.0
   Side R                18.0 ×   350.0 ×   200.0
   Bottom               364.0 ×   350.0 ×    18.0
   Top                  364.0 ×   350.0 ×    18.0
   Back                 364.0 ×    18.0 ×   164.0
   Drawer               366.0 ×   332.0 ×   165.0 · 19.62% of its blank (16,116,408mm³ short)

  Solid volumes measured — 1 measuring short of its blank, 5 exactly filling its blank. A part with no note above fills its rectangular blank EXACTLY, so nothing has been taken out of it and a cut you expected there did not land. A part measuring short is either cut or simply not box-shaped (a cylinder is 78.5% of its box); volume cannot separate those, and measure(part) names the number.

  4 problem(s):
   [warning] bad_param_range: Parameter 'clearance' default -1 is outside its own range [0:4].
   [error] part_interference: Parts 'Side L' and 'Drawer' occupy 34,980mm³ of the SAME solid volume (measured intersection, not a bounding-box guess; boxes penetrate 1.0×212.0×165.0mm). Parts must share faces, never volume — cut the pocket/dado out of one of them, or move the other.
   [error] part_interference: Parts 'Side R' and 'Drawer' occupy 34,980mm³ of the SAME solid volume (measured intersection, not a bounding-box guess; boxes penetrate 1.0×212.0×165.0mm). Parts must share faces, never volume — cut the pocket/dado out of one of them, or move the other.
   [error] part_interference: Parts 'Top' and 'Drawer' occupy 8,768mm³ of the SAME solid volume (measured intersection, not a bounding-box guess; boxes penetrate 364.0×212.0×1.0mm). Parts must share faces, never volume — cut the pocket/dado out of one of them, or move the other.

  not passed — 3 error(s). An error fails the model.

This is the real execution path, not a demo: packages/engine/runner.mjs is the file the hosted geometry service imports, at the same paths, so a stack trace here matches a stack trace there.

Use

axle build   model.js                 # verdict: dimensions, per-part boxes, problems
axle build   model.js --json          # the same, machine-readable
axle explain model.js                 # what --param accepts: each parameter, value, range
axle sweep   model.js --range w=300:800:50 --require passed --score min:volume   # search the space
axle verify  "models/**/*.js"         # build them all; exit with the worst verdict (CI's gate)
axle watch   model.js                 # rebuild on every save, ~55ms
axle repl                             # paths on stdin, one JSON verdict per line
axle export  model.js --step --stl    # real CAD files
axle build   model.js --param topSize=700
axle check-dimensions model.js --width 450 --height 500   # overall size against numbers you typed (mm)
axle measure model.js --part-a "Top" --part-b "Leg 1"     # gap / flush / overlap, measured shared volume

⏱ Use watch or repl for real work. A one-shot axle build spends ~900ms starting Node and the OpenCascade kernel to do ~100ms of building. The persistent modes pay that once and then rebuild in ~55ms — measured at 19.8× faster than the one-shot on the same machine.

explain is the door into that: it prints every parameter with its declared range without building, so an agent can sweep a model it has never opened. explain --json returns the same params array build --json carries.

Search a space

Stop drawing one design and ask the whole range. axle sweep builds every variant of a parameter space on one warm kernel — the first build pays for OpenCascade, the rest cost ~55ms each — and ranks them by a measured field of the verdict, never an opinion: volume (mm³), overall.x|y|z, parts, problems, buildMs, or a swept parameter's own name. --require passed drops the variants whose verdict failed — an error — before ranking; --where overall.x<=800 constrains on the same terms, and --where problems==0 drops every variant with any finding. problems counts EVERY finding the geometry checks reported on that variant — errors, warnings, info and unverified ones — and on a big model an unverified finding can depend on how busy the machine was, so read what a problems==0 sweep excluded before you trust it. The model's static lint is reported once in the sweep's header, never per variant, so it cannot move a ranking or a filter. Real output, captured by this repo's release check — the widest slatPitch the checks have nothing to say about, and the first one they flag:

$ node packages/engine/cli.mjs sweep examples/slat-bench.js --range slatPitch=70:170:10 --where problems==0 --score max:slatPitch
slat-bench.js — 11 variant(s) swept in 1183ms · 11 built · 11 passed · 2 excluded by --where problems==0 · 9 ranked by max:slatPitch

  static lint: none (the model as handed in, checked once for the sweep).

   #  slatPitch  passed  problems  overall (mm)            volume (mm³)
   1        150  ✓              0  1410.0 × 400.0 × 450.0      16420000
   2        140  ✓              0  1320.0 × 400.0 × 450.0      16420000
   3        130  ✓              0  1320.0 × 400.0 × 450.0      16420000
   4        120  ✓              0  1320.0 × 400.0 × 450.0      16420000
   5        110  ✓              0  1320.0 × 400.0 × 450.0      16420000
   6        100  ✓              0  1320.0 × 400.0 × 450.0      16420000
   7         90  ✓              0  1320.0 × 400.0 × 450.0      16420000
   8         80  ✓              0  1320.0 × 400.0 × 450.0      16420000
   9         70  ✓              0  1320.0 × 400.0 × 450.0      16420000

  winner   --param slatPitch=150

  excluded (2):
   slatPitch=160  missed problems==0 — unsupported_part ×2
   slatPitch=170  missed problems==0 — unsupported_part ×2

The winner line is ready to paste into axle build. --json prints one record per variant in ranked order and a final { summary }; two runs of the same sweep are byte-identical apart from the timing fields, so a sweep is a fixture as much as a search. With no --range, every parameter explain lists is swept over its declared range; a sweep bigger than --max-variants (500) is refused before anything builds.

Verify a whole repository — and let CI hold the line

axle verify builds every model a pattern names, on one warm kernel, and exits with the worst verdict it found: 0 passed · 1 built with errors · 2 did not build · 3 could not run. A warning is reported and annotated, and does not fail the run. That is a CI gate, so there is a GitHub Action for it — a thin wrapper around that one command, and nothing else:

      - uses: actions/checkout@v4
      - uses: AxleKeys/cad-engine@main
        with:
          models: "models/**/*.js"

Each problem becomes an annotation on the line of the diff that caused it. A pattern that matches no files fails the run rather than passing quietly — a green job that verified zero models reads exactly like "every model is clean", and that is the one thing CI must never say. Full guide, including a --param matrix: docs/ci.md.

This repository runs that Action on the examples below, through the published package, on every push — including one job whose fixture is expected to fail and which then asserts that it did. See the runs.

Examples

Each one shows a single check being honest. Every row is a fixture npm test runs, with the verdict it claims; every Try is a command whose result this repo's release check asserts.

| Example | What it shows | Try | |---|---|---| | examples/side-table.js | The on-ramp. Four legs that stop exactly at the top's underside — a clean verdict with every part's box. | axle build examples/side-table.js → clean | | examples/bookshelf-3-shelf.js | Shelves that butt against the sides. Shared faces are contact, not collision, so the verdict stays clean. | axle build examples/bookshelf-3-shelf.js → clean | | examples/dado-joint.js | A real dado joint PASSES part_interference: each shelf's tongue sits inside a groove, sharing faces on five sides and no volume. The old bounding-box rule called this a collision. | axle build examples/dado-joint.js → clean | | examples/dado-interference.js | The same cabinet with the grooves never cut, so every shelf end is buried 6mm inside a side. The verdict prints the shared 32,400mm³ per joint — measured, not guessed. npm test keeps this one loud. | axle build examples/dado-interference.js → part_interference | | examples/drawer-box.js | What a --param is for. Clean at every clearance in its declared range, where the drawer touches or clears its opening; push it below the range and the verdict measures the collision. | axle build examples/drawer-box.js --param clearance=-1 → part_interference | | examples/slat-bench.js | unsupported_part doing its job: widen slatPitch past its range and the end slats sit beyond the rails. It is a warning — the verdict flags the model and still passes it. railLength is a plain const, which axle explain lists as not adjustable. | axle build examples/slat-bench.js --param slatPitch=160 → unsupported_part |

A model

A model is a function that returns named parts. Parameters are annotated consts, which is what makes --param work — a dimension is a parameter, not a coordinate to edit. Primitives are centred in X and Y and sit on z = 0; X is width, Y is depth, Z is height.

const topSize = 450;      // [300:800]
const height  = 500;      // [350:700]

const main = ({ makeBaseBox }) => {
  const top = makeBaseBox(topSize, topSize, 25).translateZ(height - 25);
  return [{ name: "Top", shape: top }];
};

A numeric const with no // [min:max] is not a parameter: --param refuses it and explain lists it as not adjustable. The range is what the model declares, not a limit the CLI enforces — which is exactly what makes the drawer example above work.

What the verdict checks

Deterministic rules, the same implementations the hosted platform runs. Every finding carries a severity, and the severity decides: an error fails the model (axle build and axle verify exit 1), a warning flags it and it still passes.

• part_interference (error) — a measured solid intersection between two parts, not a bounding-box guess. A dado joint shares faces and stays silent; a collision is reported with the shared volume in mm³.
• unsupported_part (warning) — a part with nothing beneath it. Conservative by design, and it only understands bearing from below, so it can flag legitimate end-supported joinery; that is why it flags rather than fails.
• unclosed_volume, non_positive_volume (errors) — read from the B-rep, not the mesh: a fillet that ate its stock, a shell that turned a solid inside out. Both build, both mesh, both pass a dimension check, and neither is a solid.
• empty_mesh, degenerate_dimension, empty_parts_array (errors).

A finding marked unverified means the build could not measure that pair in the time it allowed itself. It is reported, and it does not fail the model, whatever its severity — "I could not tell" is not "there is a defect".

Beside the geometry, the verdict carries the static lint the platform's push verdict carries: rules about the code's shape, read without running it, through the same function that composes them there. Five are errors — main_missing, global_replicad, code_truncated, rotate_no_args, extrude_no_args — and six are warnings — params_argument, no_parameters, too_many_parameters, bad_param_range, generic_body_name, magic_numbers. On a model that built, main_missing is dropped and code_truncated becomes a warning, because the build itself contradicts them; on one that did not build they stand at full strength, because they often name why. sweep reports the lint once for the whole sweep (its header, and summary.lint in --json), over the model as you handed it in: it is in no variant's problems or passed, so it cannot rank, filter or exclude a variant.

axle build also prints each part's solid volume against the rectangular blank it would be cut from — the sentence the platform prints under the same part. Exactly 100% proves nothing was taken out of the part; less than 100% is a cut or a part that was never box-shaped (a cylinder fills 78.5% of its box), and volume cannot tell those apart. It is a measured fact and never a gate.

Check a size, measure two parts

Two of the platform's probes answer here too, computed by the same functions its MCP tools call:

• axle check-dimensions model.js --width W [--depth D] [--height H] [--tolerance-mm T] — the overall box against numbers you type (mm; width = X, depth = Y, height = Z). The default band is ±5% or 3mm per axis, whichever is larger, and it is deliberately loose; --tolerance-mm replaces it outright on every axis. A negative or non-numeric tolerance is refused, never swapped for the default, and every answer names the band it applied. Exit 0 within the band, 1 off, 2 did not build, 3 could not run. --json prints the check_dimensions tool's answer.
• axle measure model.js --part-a A [--part-b B] — one part's box and its solid volume against its blank; or, for a pair, the per-axis gap / flush / overlap, the nearest distance, and shared_volume: the real intersection this build measured, which tells a dado (shared faces, no volume) from a collision (volume). Boxes are world-axis and conservative for rotated or notched parts; shared_volume is the number to trust. --json prints the measure tool's answer.

The targets are yours: nothing here reads a brief stored on the platform.

Install

Requires Node 23 or newer. The engine ships as plain JavaScript: the repository's TypeScript with its type annotations erased at export by Node's own stripper, positions kept, so a line number here is the line number there. No bundler, no build step. The CLI checks the Node version first and tells you so rather than failing inside a module loader.

npm install -g @axle-keys/cad-engine      # or: npx -y @axle-keys/cad-engine build side-table.js
curl -O https://raw.githubusercontent.com/AxleKeys/cad-engine/main/examples/side-table.js
axle build side-table.js

That last line is run by this repo's release check before every publish — the packed tarball is installed into a fresh project and the command is executed through the installed bin — and npx -y @axle-keys/cad-engine@<version> build side-table.js is run against the registry itself after each one.

Or clone it:

git clone https://github.com/AxleKeys/cad-engine.git
cd cad-engine
npm install
node packages/engine/cli.mjs build examples/side-table.js

That last line is the command this repo's own release check runs before publishing, so it is known to work on the files you just cloned — and it is the first capture at the top of this page.

To get axle on your PATH instead of typing the full path:

npm link          # from the repo root
axle build examples/side-table.js

Check what you installed

npm test

Two legs. The first builds every example above and asserts each gives the verdict its row claims — the clean ones clean, the loud ones loud, and each Try command producing the rule it names. The second is a positive control: it builds a model whose two parts deliberately share 62,500mm³ of solid volume and asserts the interference check reports it. That one matters more than it looks. A verifier that only ever sees a clean model prints the same success whether the checks are running or silently dead, so the failing case is tested too.

It tells you your copy runs and that its checks are alive. It does not call axlekeys.com, so it does not measure agreement with the hosted verdict — that rests on this package being generated from the same source the platform runs.

Docs — the modelling rules, as files

docs/ holds the 18 sections of the skill pack the hosted platform teaches its agents — the API it writes against, the axis convention, the joinery and domain rules, the worked examples — rendered from the same list the pack is deployed from, so what you grep here is what an agent connected over MCP is told. Start at docs/MasterSkill.md. Anything a section says to check, axle build checks.

Skills — teach your agent the whole workflow

The engine above runs on your machine. These skills are the other half: choreography for an agent driving the hosted platform at axlekeys.com, over MCP.

| Skill | Tier | What it does | |---|---|---| | brief-to-model | Free | Turn a plain-English description into a real parametric 3D CAD model — built, dimension-verified, and shown back as a picture you can spin. | | design-loop | Free | Verify an agent-built CAD model with independent critics instead of self-review — clean-context reviewers that fetch the reference and probe the geometry themselves, then a punch list you gate on. | | local-loop | Free | Iterate on an Axle Keys model on your own machine at tens of milliseconds a build — the same engine and the same verdict axlekeys.com runs — then push the finished model once instead of a round trip per attempt. | | parametric-fit | Free | Make an existing parametric CAD model fit a real space or a hard number — an alcove, the gap under a window, a maximum depth — by moving the parameters it already declares and PROVING the result with a dimension check, never by editing geometry. |

Every skill here is completable on the free tier — that is enforced at export time, not promised, so nothing in this repo walks you into a paywall.

Install as a plugin, which brings the skills with it:

claude plugin marketplace add AxleKeys/cad-engine
claude plugin install axle-cad-engine@axle-keys

Or take a single skill the way your agent takes skills — for Claude Code, drop the folder in .claude/skills/. Either way, connect Axle:

https://api.axlekeys.com/mcp

What this is not

This runs models. It does not store them.

Persistence, versions, the 3D viewport, assemblies, motion, configurators, shop drawings, cut lists and nesting, materials and textures, the knowledge layer, and the MCP interface your agent drives all live on axlekeys.com.

This package is a calculator; the platform is the notebook. It does sums. It doesn't remember anything, show you anything, or let you sell anything.

It is also read and run, never write. Local edits change your copy, not Axle — if the two ever disagree about the same model, the server is the one that counts.

Contents

Generated from the Axle Keys repository — 27 source files, derived by walking the engine's own imports; 6 examples; 18 docs sections; 4 skills. The picture at the top was rendered by a committed script through the platform's own headless renderer, and the export refuses a picture whose recorded source no longer matches the examples beside it. Do not hand-edit; changes are made upstream and re-exported.

Pinned: [email protected] · [email protected]

License

MIT.