mechanism

Build inspectable models from evidence. See what is known, estimated and tested.
A skill for coding agents that researches a real product or machine, writes a spec where every number says where it came from,
refuses to render when the numbers do not add up, and outputs a film, an interactive viewer and a 3D model.

Live page · Try the viewers · Install · Examples · How it works

What it does

Ask your agent for an exploded view of something real: a machine, a chip, or software (a file format, a protocol, an algorithm's output). It does not draw what it can look up wrong:

1. Researches. Searches, opens datasheets and teardowns, downloads the pictures and looks at them, measures them.
2. Writes a spec. Parts with real dimensions, how they move, and the evidence behind every number.
3. Runs the gate. The model is run against what is published. A spec that does not add up is not rendered.
4. Renders. A 4:5 / 9:16 / 1:1 film with real recorded sound, a live viewer, and an STL / GLB.

The gate

$ node scripts/check-spec.mjs examples/rubik/spec.js
Rubik's Cube  (rubik)
parts: 26   claims: 9   sources: 2
cube: 26 cubies
  phase R U R' U' x 6: 6 (24 turns)
  phase Longest period: 1260 (10 turns)  published 1,260  ok
  phase Superflip: 20 moves (20 turns)  published 20 moves  ok
  phase Positions: 43,252,003,274,489,856,000 (0 turns)  published 43,252,003,274,489,856,000  ok

PASSES

The cube is 26 pieces that really turn, with no permutation tables. The numbers above are read off the pieces.
Break something and it says exactly what:

$ node scripts/check-spec.mjs examples/k20a/spec.js      # firing order changed to 1-2-3-4
ERROR  firing order 1-2-3-4: cylinder 3 would have to fire at 360 degrees and its crank throw is at 180 (not possible with that crankshaft)
ERROR  phase Firing order: the model gives 1-2-3-4 and the published one is 1-3-4-2

DOES NOT PASS: 3 error(s)

It fails (exit 1) when a number has no source, a DERIVED claim has no cross-check, a MEASURED one no error, an ESTIMATED one no reason; when two meshing gears are not at the centre distance their module and teeth demand; when a mode of operation does not give the ratio the maker publishes; when a cipher disagrees with a published test; when a firing order is impossible with the crank; when the superflip does not flip 12 edges.

Examples

Every example is a film, a live viewer (examples/<name>/index.html?explore, add &theme=night) and a model.

Install

The one-line way, as a Claude Code plugin (Claude Code 2.1.275 or later):

/plugin install mechanism --marketplace DiegoLopez0208/mechanism

The skill then runs from the plugin folder, and your objects go in your own project.

Or by hand, as a plain skill:

# macOS / Linux: a partial clone, 4 MB (the repo also holds the films, the site and a long history, 85 MB or more, which you do not need to use the skill)
git clone --depth 1 --filter=blob:none --sparse https://github.com/DiegoLopez0208/mechanism ~/.claude/skills/mechanism
git -C ~/.claude/skills/mechanism sparse-checkout set kit scripts examples data tools tests
# Windows (PowerShell)
git clone --depth 1 --filter=blob:none --sparse https://github.com/DiegoLopez0208/mechanism $env:USERPROFILE\.claude\skills\mechanism
git -C $env:USERPROFILE\.claude\skills\mechanism sparse-checkout set kit scripts examples data tools tests

The skill can also be found with npx skills add DiegoLopez0208/mechanism --list (checked: it lists it). The kit, the scripts and the examples are plain files in this repo, so a clone is the safe way to get all of them.

Then ask: "Use mechanism to model a mechanical keyboard switch from its published sources." The agent researches, writes the spec, runs the gate and renders.

Needs Node 22+, Edge or Chrome (on Linux, Google Chrome stable), and ffmpeg; for rendering films, a GPU. uv is only used to measure photos. Nothing else to install.

Use the toolkit directly

node scripts/new.mjs my-object --title "My object"          # a spec that already passes the gate
node scripts/check-spec.mjs examples/my-object/spec.js      # the gate
node scripts/probe.mjs "examples/my-object/index.html?explore" out/probe   # mouse-driven check of the viewer
node scripts/render.mjs examples/my-object/index.html --blur 3 --out out/my-object.mp4
node scripts/render.mjs examples/my-object/index.html --style studio --aspect 9:16 --out out/my-object-916.mp4    # dossier (default) | paper | night | studio
node scripts/render.mjs examples/my-object/index.html --from 13 --to 21 --out out/clip.mp4      # a clip
node scripts/render.mjs examples/my-object/index.html --export glb --e 1 --out out/my-object.mp4   # also: --export stl
node scripts/render.mjs examples/my-object/index.html --remux out/my-object.mp4                  # redo only the sound, in seconds

How it works

One spec in, everything out:

spec.js  ->  film (4:5, 9:16, 1:1; paper or night; stereo)
         ->  clips cut from the film
         ->  interactive viewer (orbit, explode, measure, run the mechanism)
         ->  STL and GLB of the model

A part, with the evidence it stands on:

{ id: 'ring', kind: 'ring', p: { m: 0.8, z: 60, ro: 27.4, width: 8 }, mat: 'steel-dark',
  at: [0, 0, 0], body: 'ring', explode: [0, 0, -12], conf: 'derived', claims: ['teeth', 'formula'] }

The director builds the film by itself: staggered assembly, a cutaway while the mechanism runs, one mode at a time with its published number, the exploded view, a tour with a callout per part, re-assembly, and an evidence table with the sources.

The look

Every film is drawn as a dossier: a blue engineering drawing with a grid and ruler ticks, monospaced type, and a data block that counts how many numbers are SPEC, DERIVED and ESTIMATED. It is the look of evidence, not of a pretty explainer. The same engine can draw three other styles, chosen with --style (or ?style= in the viewers) and defined as one table entry each in MX.styles (kit/core.js):

The verdict is three-state, never a bare "pass"

The gate ends with verdict: VERIFIED 8 reproduced, 1 estimated, 0 unchecked. Only one thing earns VERIFIED: at least one published figure was compared with the model, all of them matched, and none is pending. A model that compares nothing says NOTHING CHECKED (a description, not a verification); a pending comparison says INCOMPLETE; any mismatch is DOES NOT PASS. node scripts/check-spec.mjs <spec> --json verdict.json writes the report (verdict, errors, spec and kit SHA-256, Node version, date).

It also refuses what a template leaves behind: example.com and TODO in sources, claims or part names, non-positive or non-finite dimensions, a spec with no parts, a calculated variable with no claim, an expression that gives undefined/NaN/Infinity, an invalid tolerance and an ESTIMATED part with no reason. node scripts/new.mjs starts a draft that fails until it is filled in. Every one of those cases is a test in tests/gate.test.mjs (npm test) and runs in CI.

Three lengths

The same spec renders three films: --length short (about 30 s: the plain sentence, the unpacking or the first checks, the explode, two parts, the receipt), normal (the default: verdict-first opening, every check, the tour, the evidence pages) and extended (longer checks, up to 12 parts in the tour). node scripts/render.mjs examples/hub/index.html --length short --out out/hub-short.mp4. A spec can say what its short cut keeps: director: { short: { modes: ['unpack', 'crc'], tour: ['out25', 'bookP'] } } (a cube or a cipher keeps every phase, because their state runs through all of them) and its default with director.length.

Provenance per dimension, and a register

A part can say where each of its sizes comes from, and the gate compares the drawn size with the source:

params: { w: { value: 15.63, unit: 'mm', conf: 'spec', claim: 'size', tol: 0.005 },
          wall: { unit: 'mm', conf: 'estimated', why: 'the datasheet has no drawing' } }

A drawn 15.0 against a sourced 15.63 is an error; the compared dimensions count as reproduced figures; and a part whose headline class is stronger than its weakest dimension is reported as mixed (the card lists both). node scripts/registry.mjs runs the gate on every example and writes docs/registry.html, docs/registry.json and an SVG badge per object (docs/badges/<id>.svg), all straight from the gate's output.

Recognisable, not just correct

A model whose numbers all match can still look like nothing. A spec declares what a stranger should call the object and the features that make it that object, each tied to parts that exist:

recognize: { object: 'Honda K20A inline-four engine',
  iconic: [{ text: 'red cam cover', parts: ['cover'] }, { text: 'four pistons', partsPrefix: 'piston' }] }

The gate refuses an iconic feature that is not built. Then the stranger test: node scripts/stranger.mjs <example> saves a still with no title, labels or panels (?bare), a model with no context is asked what it is, and the answer is recorded in recognize.blind. A wrong answer is a warning on the verdict, not a hidden one. Run on the shipped examples it found two that were not recognisable (the hub, and the first RAR5 film that was only hex cubes).

Software

Software is verified the same way, against the real program: pick what it writes (a file format, a message, a result), make the real tool produce a sample, write a pure model from the published description, and let the gate demand that the model rebuilds the sample byte for byte and that the real tool accepts what the model built. examples/rar5 does it for RAR5: scripts/make-rar5-sample.mjs runs Rar.exe and UnRAR.exe, the model is kit/rar5.js, and the evidence travels with the spec in data.js.

Films open with a verdict

A film can open with the question and the published answers being checked one by one (director.cold), shows each part's sources as it is inspected, and closes with a receipt (VERIFIED or DOES NOT PASS) listing every figure compared.

Brand identity

An object has to look like itself. The maker's wordmark, colours and finish are drawn with decals (type, rules and shapes on any face, with optional glow), never with logo files, and they are declared like any other number: a livery that no opened source shows is an ESTIMATED claim and says so. director.hold gives the finished, lettered object a beauty shot before the cutaway starts.

Sound

Real recordings, not synthesis: keys, metal, glass, plastic and rubber impacts (CC0, see THIRD_PARTY.md), mapped per material and size. Tooth ticks are the real tooth passes of the running gears, and the engine fires in its real order.

Repository

Agent runs

Does it work without someone holding its hand? Two objects were given to fresh agents with only the skill and one sentence, under criteria written before the results (docs/benchmark/criteria.md):

Two runs are two data points, not a success rate; the agents were subagents with a clean context, not independent sessions, and the plan is 20 objects. The logs keep every failure and the toolkit problems the agents hit were fixed afterwards (the version each run used is written in its notes). Notes: docs/benchmark/run-01-antikythera.md, docs/benchmark/run-02-floppy.md. There is also a hand-edited Antikythera (docs/benchmark/antikythera-refined/), labelled as such, that is not part of the result.

Limits, stated plainly

• Mechanisms so far: gear trains (one degree of freedom), presses and slides, rotor ciphers, crank-slider engines, the Rubik cube and calculated figures. No general linkages yet.
• The hub's power path per mode is simplified: pawls and clutch are not modelled, and the film says so.
• Interiors need photos or drawings. Without them they are estimated and dashed.
• A single photo gives no millimetres: it needs a published size, a ruler or a datasheet.
• A GPU makes rendering fast; without one it is very slow. On a laptop with a discrete GPU a normal film takes about 2 to 3 seconds per second of video and the 30 s cut about a minute (--draft gives a quick preview). On a machine with no GPU (software WebGL) one frame takes about 7 seconds, so a 30 s film would take over an hour: use --still, lint-film.mjs and the viewer there, and render elsewhere.
• Platforms. Developed on Windows. Tested on Ubuntu 24.04 (WSL2, Node 22, Chrome and ffmpeg installed from scratch, as a normal user): the partial-clone install, all the tests and gates, stills and the film lint work. Films were not rendered on Linux (no GPU there) and nothing was tried on macOS. The tests also run on Linux in CI.
• The sources can be wrong too. The spec keeps them next to each claim so you can check, and notes where a page refused to be read.

Roadmap

bicycle drivetrain, and the next 18 objects of the agent test. The rule is the same for all: numbers that can be computed and checked against what is published.

Inspiration

Anatomy showed that an agent skill can explain something by building it as an interactive physical object, and its "Fig N" card is where ours started. mechanism goes the other way: not ideas explained with a metaphor but real objects, with every number traced to a source, a gate that refuses to render when the model contradicts what is published, and films with sound and 3D files as outputs.

License

MIT. three.js, Inter and Cormorant Garamond are bundled under their own licenses, and the sound samples are CC0: see THIRD_PARTY.md. Product names identify the objects modelled and belong to their owners; their photos and datasheets are not redistributed.