Coupon

ClauderaCAM

Claude-drivable 2.5D heightmap CAM for the Makera Carvera Air. STL relief → rough / semi / finish / cutout → physical stock-simulation verification → live 3D viewer → .nc. Built from the exact code that cut the brass Mango coin, then hardened by a 42-agent adversarial review whose 35 confirmed findings are each either fixed or a named check (see DESIGN.md "2026-07-28: adversarial review & hardening"). A second lane mills PCBs from KiCad gerbers through the same gate (see The PCB lane below).

Setup

python3 -m venv .venv
.venv/bin/python -m pip install -e .          # pure-python (works everywhere)
.venv/bin/python -m pip install ./kernel      # optional Rust kernel (~10-50x
                                              # faster verify; needs cargo)

The two kernels are parity-locked (tests/kernel_parity.py): bit-exact stock, epsilon-exact measurements. The Python one is the semantic reference.

MCP (primary interface)

.mcp.json in this repo registers the server for Claude Code sessions started here. From elsewhere:

claude mcp add --scope user clauderacam -- \
  <repo>/.venv/bin/python -m clauderacam.mcp_server

Tools: load_job, generate, verify, preview, view (opens the job as a session in the live viewer, starting a server only if none is running), sessions (lists open sessions). There is deliberately no upload tool — .nc files reach the machine only by hand.

The viewer is a stage-aware, multi-session inspection app. One server holds many sessions — one per open job file — and every process joins it: the MCP, the CLI and any number of browser tabs land on the same server via a discovery file, so a change Claude pushes appears in the watching browser within a second. Sessions are keyed by job path, so opening a file that is already open joins its session (that's the collaboration model). In the browser: a session list with verdict badges and a job-file picker (opening verifies in the background; the browser never generates or edits — job changes are Claude's); per session, the program's logical operations (recovered from the .nc bytes themselves) as a selectable list with per-stage time estimates — selecting one shows the simulated stock as it will exist after that operation with the material that stage removes highlighted — plus a stage-detail card (removed volume, tool contact, windowed chip load and cutting power, each drawn as a utilization bar against its limit), the tool library with the active stage's tool marked, and the full check list. Claude runs the job; the viewer exists so a human — including a CAM expert — can audit it. Each session offers a download of its program — serving the exact bytes that were verified (stored at push time; a later regenerate can never hand out unverified toolpaths under a displayed PASS), with an explicit are-you-sure on anything not cleared for metal. Downloading to a human hand is the Article VII workflow: the file still reaches the machine only by that hand.

CLI

.venv/bin/clauderacam all jobs/mango.toml       # generate + verify + preview
.venv/bin/clauderacam view jobs/mango.toml      # open in the live viewer at
                                                # :8323 (joins a running
                                                # server, else serves)
.venv/bin/clauderacam serve                     # empty viewer server; open
                                                # job files from the browser

The rule

Nothing goes to the machine without verify returning PASS. The verifier strictly parses the program (anything it cannot model — unknown tools, arcs, modal G-less lines — is fatal, never skipped), carves every move into virtual stock, and checks:

• geometry (simulation facts): rapids (lateral and descending), true per-move tool contact for every tool (footprint max vs move-start stock, limits calibrated to metal evidence), shank/holder clearance against standing stock, depth vs stock bottom, gouging below the target surface, surface completeness, cutout sever-through, the fixture keep-out zone, and the spindle-state dialect (M5 before M6, dwell after M3)
• cutting physics (model verdicts, provenance-annotated in physics.py): per-material sustained chip load and spindle power over 0.25s windows, rubbing (starvation feed), plunge rate, machine feed caps, a sustained- power heat proxy, and an enclosed-chip gumming proxy — materials carry specific cutting energy, chip-load floors and evacuation limits; tools carry flutes, flute length and shank geometry; the machine model is the Carvera Air's 200W / 13k RPM spindle

tests/negative_suite.py proves the gate can fail: 24 distilled hazards — slams, stalls, rubbing, gumming, shank crashes, rapid plunges, arcs in disguise — that must each be caught. tests/stage_model.py proves the per-stage model tells the truth: stage snapshots partition the carve bit-exactly and per-stage stats are measured, not inferred.

Golden test

.venv/bin/python tests/golden_mango.py

Regenerates the mango job (assets/mango-coin-d52.stl — yes, that's a real cat) and asserts byte-identical toolpaths against the G-code in tests/golden/ that cut the physical coin, then verifies the assembled program. Run it after touching anything in ops/, engine.py, or heightmap.py.

Reference suite

.venv/bin/python tests/reference_suite.py

assets/generate_references.py synthesizes four deterministic shapes, each paired with a job in jobs/ that stresses a different hazard:

Together with mango these cover the supported tool set: flat 3.175, flat 2.0, ball 2.0, ball 1.0, plus twist drills for registration holes — the geometries validated by cut metal. V-bits and tapered ball noses need a conical offset model plus a real-world tip engagement limit, so they are roadmap, not shipped guesses.

Two-sided (pin-and-flip) jobs

One TOML with [twosided], [pins] and per-side op lists describes a coin machined on BOTH faces: side 1 cuts the front art plus a minimal moat, then spot-faces and peck-drills registration holes through the stock into the spoilboard — same setup, so the holes are coaxial by construction. Flip the blank onto dowel pins (layout must be symmetric under the configured flip axis — enforced), and side 2 cuts the back art and the tabbed cutout. Two .nc programs come out; each verifies through the same gate, and the back side is additionally checked against the carried, flipped front stock: punch-through into the front art, sever against the actual material bottom, a continuous tab bridge from coin to skeleton, and pin keep-out. The cutout's tab_top is derived from the carried front floor to hit a target tab_bridge thickness (hand-written values are refused — the first cut coin's hand-picked tab_top made 0.24mm tabs that snapped too thin). jobs/twoside-ref.toml + tests/twosided_suite.py are the executable spec, negatives included.

The PCB lane

Gerbers + Excellon in, verified Carvera programs out: isolation-milled PCBs through the same gate. A [pcb] TOML names a KiCad export directory and parameterizes the operator's six-phase chain — cut traces (0.2mm vee, a multi-pass ladder so gaps too wide for one pass and too narrow for the clearing tool still come out copper-free) → clear copper → solder mask (operator: squeegee + UV cure) → silkscreen (455nm laser onto the cured mask) → scrub mask off pads (spring tool) → drills + edge cut. FlatCAM (a pinned headless fork) runs as the geometry engine only: its per-phase output is strictly parsed and re-emitted through emit.py, so every shipped byte obeys the house dialect (the laser program has its own — one M321, then a mandatory G0 Z0 defocus, dose-ceilinged M3 S). Verification never trusts the generator: gerbv rasterizes the same gerbers through an unrelated parser lineage, and the gate measures the assembled programs against those maps — iso containment and coverage, a residual-copper law on the simulated carve (no bridging sliver survives between what isolation reaches and what clearing owns — a loupe-found incident), clearing margins, scrub laps inside pad copper, pad scrubbability, thermal-relief spoke delivery, silk clearance and stroke metrics, the exact Excellon hole schedule, cutout ride + tab census, and true sheet stock simulation for the milling programs (guides/pcb-dfm-notes.md translates the big fab houses' hand-solder DFM rules into this milled lane's numbers). Double-sided boards compose [pcb] + [twosided]: per-side phase tables, both machine frames derived from the one Edge.Cuts, registration pins under the coin lane's pins law, both-side annular-ring and flip-concentricity checks for hand-soldered wire vias, and a side-2 scrub generator that laps drilled pads annularly instead of driving the spring tip across open holes. Board contracts — plus each board's assembly map, companion sheet and machine-side tool pull-list — live in boards/, golden assets in tests/golden_pcb/; the viewer opens a [pcb] job as one session per program, with 2D overlays for the non-carving stages and the operator's run-sheet card. FlatCAM and gerbv are external optional binaries (like the Rust kernel): the blessed goldens verify without them and the suites skip loudly.

The tool crib

jobs/inventory.toml is the machine's physical tool inventory. A job may only use tools that match an entry — type, diameter, shank, flutes, reach, quantity on hand — and refuses to load otherwise (Article XI). Geometry in the crib is measured or catalog-sourced, never guessed; a tool with an unknown dimension is absent, and the resulting refusal is the feature.

Project law

CLAUDE.md is the constitution: the verification gate, the golden-test contract, and the incident-traced safety rules. Read it before contributing — human or model.

License & credits

MIT (see LICENSE). Vendors three.js r160 (MIT) for the viewer. Named for Claude + Carvera: designed and written by Claude Code working alongside a human machinist, and proven by cutting real metal before it was ever a package.