AgenticCAD documentation

Everything the app does, how it stores it, and how to drive it by chat, by hand, or from the agent's tools. For a guided walk-through, start with the tutorials.

Overview

AgenticCAD is a desktop CAD app with a Claude agent built in. You describe the part you want, the agent models it, and you watch it appear in a 3D viewer. From there you steer it however is quickest: keep talking, point at faces and bodies in the viewer, tweak dimensions in a parameters panel, or use a Fusion-style toolbar to press, pull, hole, fillet, revolve, loft, sweep, mirror, pattern and sketch (with constraints) by hand. Multi-body designs are assemblies: section them, check them for interference, give them joints and watch them move, explode them, render them.

Every design is exact solid geometry, so what you export is production-ready: STEP for other CAD tools and suppliers, STL at the resolution you choose for 3D printing, shop drawings with hole tables, and, if you have OrcaSlicer installed, a sliced print preview with time and filament estimates. An experimental CAM workspace generates toolpaths for small mills and routers (GRBL, or the Makera Z1 and Carvera Air), with multiple setups, a 4th axis and a material-removal simulation. And when the app lacks a tool, the agent can write one: extensions add helpers, agent tools, build checks and panels from a single Python file.

• Say it: “a 60×40×8 plate with a 24 mm boss and four M4 holes”.
• Point at it: click a face or body, then “make this 2 mm thicker”.
• Tweak it: every dimension is a named parameter you can nudge; the model rebuilds instantly.
• Do it by hand: toolbar tools, sketches on any face, ISO and inch threads, measure and mass properties.
• Keep it reproducible: the whole design lives in one readable Python script that you can open, edit, save to the part library and version.

You need a Mac or Windows PC, the app (or the source), and a Claude sign-in: either Claude Code logged into your Anthropic account or an API key. Nothing else is required; the slicer is optional and only used if it is already on your machine.

Desktop app

The desktop app is the same program in a native window with Python bundled. Two things to know:

• Claude Code is required and not included. AgenticCAD drives Anthropic's Claude Code command-line tool and is not permitted to redistribute it. On first launch the app checks for it (on PATH and in the official install locations) and, if missing, shows a setup page with the install command for your platform and the sign-in step. Install: macOS and Linux curl -fsSL https://claude.ai/install.sh | bash; Windows PowerShell irm https://claude.ai/install.ps1 | iex. Then sign in once: run claude in a terminal and choose Log in (Claude Pro or Max), or paste an Anthropic API key on the app's setup page or in Settings. The app runs Claude Code headless, so it cannot show the login prompt itself; when a login expires it shows a "not signed in" banner with those two options instead of failing silently. The npm-based install on Windows (claude.cmd) cannot be launched by a desktop app; use the installer above.
• The installers show the licence first. macOS uses a standard .pkg installer and Windows an .msi; both show the licence and terms and ask you to agree before installing (free for non-commercial use, a licence per user for commercial use).
• The builds are unsigned for now. macOS: if the installer is blocked, right-click it → Open, or System Settings → Privacy & Security → Open Anyway. Windows: SmartScreen shows "Windows protected your PC"; choose More info → Run anyway. Signed builds will follow.

Your data lives in the OS user-data folder: ~/Library/Application Support/AgenticCAD on macOS, %LOCALAPPDATA%\AgenticCAD\AgenticCAD on Windows (designs, library, machines, tools, history, exports, settings). Set AGENTICCAD_WORKSPACE to move it. The app picks a free localhost port; the UI is the same page you would see from a source install, so everything else in these docs applies. Intel Macs and Linux: run from source below.

Install from source

Requirements: Python 3.12, a Claude Code login (the Agent SDK's bundled binary uses it) or an ANTHROPIC_API_KEY, and a modern browser.

# unzip the release (or git clone https://github.com/agenticcad/agenticcad.git), then inside the folder:
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python server.py            # http://127.0.0.1:8765

The workspace

• Top bar: the AgenticCAD name with the version (click for the changelog), the design name, which is the File menu (with • when unsaved), the workspaces Design · CAM · Machine (CAM and machine control are experimental), the machine's status (click for the Machine workspace), Assistant and Settings ⚙.
• Toolbar (Design): one row of Create, Modify, Assemble and Inspect tools, the less-used ones under each group's More, with Output (Render, Drawings, Slice) and Extensions as menus.
• Right column, in every workspace: Inspector (the active command's settings or the selection in Design, the selected operation or setup in CAM, the machine's steps in Machine), Assistant (the conversation with selection chips and images) and Code (the script with syntax highlighting; edit and Run with ⌘↩ to rebuild without the agent; switch between design.py, cam.py, machine.py and fixture.py). File ▸ Part library… opens the Library here too. Drag the divider to resize, double-click to reset, ⌘B to hide.
• Viewer: left-drag orbits, right-drag (or ⌘/Ctrl/⇧ + drag) pans, wheel zooms; the ViewCube snaps to faces, edges and corners and its ⌂ is the home view. Bottom toolbar: Fit, Edges, display-mesh quality (draft / normal / fine), Undo, Toolpaths and Stock toggles (in CAM).
• Browser (docked on the left, Parameters under it): the body tree with visibility dots, context menus (rename, delete, hide, zoom, export, save to library, move/rotate) and a Sketches section. + Body and + Part add primitives and library parts.
• File menu (the design name in the top bar): New (an empty design; a fresh install starts empty too), Open, Save, Save as, Import .py, Import STEP, Download .py, Export STEP, Export STL (resolution dialog), Shop drawings, Part library.

Several designs at once

Since 1.4 every open design is a tab. Each tab is a whole design: its model, its own CAM program and simulation, its own assistant (a separate Claude Code session working in that design's own folder) and its own view, so you can lay out a fixture in one tab while another design's assistant writes its CAM.

• Opening. File ▸ New and Open, and the + on the tab strip, open designs in new tabs; a design that is already open is switched to rather than opened twice. The open tabs come back when the app starts.
• Tab badges show when a tab's assistant is working, when something waits for you, and unsaved changes; closing a tab asks about both.
• Assistants. At most four run at once. The one you are looking at starts (or wakes) when its tab is shown and picks up its conversation where it left off.
• The machine is its own tab, shared by every design. Program from [design ▾] at the top picks which open design's CAM program Prepare, Zero and Run work with, and Send to machine in a design's CAM tab opens it there with that setup. While a program plays, the machine belongs to the design that sent it: other designs' assistants are refused machine moves until it ends (Hold, Pause and STOP always work). The Machine tab turns amber for a tool change and a toast says so wherever you are; an approval asked for in a tab you are not looking at raises a toast with Review.

Coming from the AgenticCAD Tabs test build (1.4.0a1–a2)? On its first start 1.4 copies the designs saved only in the test build's folder, and the files they import, into its own, without overwriting anything; the test app and its folder can then be deleted.

Design as script

A design is one build123d script that assigns result. The kernel executes it in a namespace that also provides import_step, from_library and the thread helpers.

# Mounting plate with a bossed bore
plate_l, plate_w, plate_t = 60, 40, 8
boss_d, boss_h, bore_d = 20, 15, 8
with BuildPart() as plate:
    Box(plate_l, plate_w, plate_t)
    with Locations((0, 0, plate_t / 2)):
        Cylinder(boss_d / 2, boss_h, align=(Align.CENTER, Align.CENTER, Align.MIN))
    Hole(bore_d / 2)                 # note: Hole takes a radius
result = {"Plate": plate.part}

• result may be a single shape, a dict of named bodies, or nested dicts for components: {"Base": {"Bracket": b, "Washer": w}, "Pin": pin}. A shape with disjoint solids is split into bodies automatically.
• Patterns. result = {"badge": pattern(part, cols=4, rows=2, pitch=(35, 60))} (or offsets=[...]) places one part several times. The copies (badge, badge@2 …) share its exact geometry, their display meshes are the part's moved rather than re-tessellated, and the model records the pattern, so CAM can tile it. The assistant uses it instead of copying bodies.
• Top-level name = number lines are parameters (see Parameters).
• Every successful build is saved to workspace/history/<ms>.py; Undo steps back through them.
• Manual operations rewrite the script with an AST-based editor (script_edit.py): rename/delete bodies, add bodies, set parameters, sketch blocks, and wrap the body expression for toolbar operations, hoisting _plate = plate.part before result when the body is referenced more than once.
• The agent receives a [Note] whenever you change the script out of band (open, import, undo, hand edit, toolbar operation), so it re-reads the code before editing.

Chat and selection

Click a face, an edge or a body in the viewer (or a row in the Browser) and it becomes a chip on the composer. ⇧-click for several. The sent message keeps its chips and the server expands them into a [Selected geometry] block: face id, body, analytic type, centre, normal, size, radius and the clicked point. Because face ids are renumbered on every rebuild, the agent is told to reference faces by geometry (faces().sort_by_distance((x, y, z))[0]) and to re-inspect after building. Hover a chip later to see a marker where that face was; click it to reselect the matching face by type and centre.

Selected faces stay lit (dimmer orange) while the agent works, until the next rebuild or click. Sketches are selectable as chips too.

Reference images

Attach photos, napkin sketches or old drawings with 📎, by dragging onto the composer or viewer, or by pasting. Images are downscaled in the browser (≤1600 px JPEG), sent inline so the agent sees them directly, kept as thumbnails in the bubble and saved to workspace/images/. Dimensions you type override what it estimates from the picture.

Bodies and the Browser

• Click a body to select it (chip); the dot toggles visibility (kept across rebuilds by path); double-click zooms to it.
• Right-click or ⋯: Rename…, Delete, Hide/Show, Zoom to, Export STEP/STL of that body, Save to library…, Move / rotate… (wraps the body expression in Pos(...) * Rot(...) * (...)).
• Rename and Delete rewrite the script directly when the body is a literal key in result = {...}; otherwise the request is handed to the agent. Deleting the last body at a level is refused.
• + Body: box, cylinder or sphere with dimensions and centre. + Part: insert from the library.
• Sketches ▸ ⋯ ▸ Extrude…: distance, direction, and new body / join / cut.

Toolbar tools

The toolbar above the viewer (Design workspace) gives you Fusion-style manual modelling without an agent turn; less-used tools sit under each group's More. A tool opens its command in the Inspector, which walks you through it: step indicator, a live prompt (“Click a face…”), chips for what you picked (× to drop), fields with units (↑↓ ±1, ⇧ ±10, ⌥ ±0.1), ↵ OK, ⌫ removes the last pick, Esc cancels.

Face references use the point you clicked (faces().sort_by_distance((x, y, z))[0]), never face centres, so they survive most later edits. Every operation is undoable and the agent is notified.

Sketches

Select a planar face (or none for XY/XZ/YZ plus an offset) and press K. The camera squares up to the plane. Tools:

• Line L and Arc A draw one closed profile of lines and three-point arcs: click points, switch between line and arc at any time (an arc takes its end point, then a point it passes through), click the first point or press Enter to close.
• Rectangle R, Circle C and Slot S by two clicks; Select V shows handles to drag corners, centres, radii and profile points, and Delete removes the selected item.
• Snapping to sketch points, the model's corners, circle centres and edge midpoints, edges lying in the sketch plane, the origin, and horizontal / vertical alignment with existing points, then the grid. A marker and label show what it snapped to; hold ⌥ to place freely.
• Typed dimensions: while a shape is in progress, type a number: length and angle for lines and slots, width and height for rectangles, diameter for circles (Tab switches, Enter places).
• Constraints: pick points, lines and circles with Select (shift-click to add more), then use the Constrain row: coincident, point on edge or circle, horizontal, vertical, parallel, perpendicular, tangent, equal, concentric, midpoint and fix.
• Dimensions D: a line's length, a circle's diameter, an arc's radius, the distance between two points or from a point to a line, or the angle between two lines. Type the value; double-click a dimension to change it.
• Drawing adds horizontal, vertical and coincident constraints automatically. The solver keeps everything satisfied as you drag or edit numbers. The status line shows the degrees of freedom left, and fully constrained items turn white. Conflicting or redundant constraints are refused with a message.

Toggle Subtract per item, edit numbers in the item list, then Finish. The sketch, with its constraints, is stored in the script as a block:

# sketch:sketch1 {"plane": {...}, "items": [...], "constraints": [...]}
with BuildSketch(Plane(origin=(0, 0, 4), x_dir=(1, 0, 0), z_dir=(0, 0, 1))) as _sketch1:
    with Locations((-18, 0)):
        Rectangle(14, 20)
    with Locations((-18, 0)):
        Circle(3, mode=Mode.SUBTRACT)
sketch1 = _sketch1.sketch
# /sketch:sketch1

So sketch1 is a normal build123d Sketch that you or the agent can extrude, cut with (part - extrude(sketch1, amount=-h)) or revolve. The JSON header lets the editor reopen it (Browser ▸ Sketches ▸ double-click). Sketches render as cyan outlines. The agent edits sketches only through its sketch tool, in the same item format, so anything it draws stays editable by you.

Units

Everything is stored in millimetres, but you work in whichever unit you like. Settings ▸ Units is automatic by default: a US timezone means inches, anywhere else millimetres; or force mm or in. That choice sets how the viewer stats, measurements, parameters and shop drawings read, and how the agent interprets a number you give without a unit. In scripts inch (= 25.4), IN, ft, thou and mm are pre-imported, so plate_l = 2.5 * inch can sit next to plate_t = 6; the Parameters card shows each one in its own unit and writes edits back the same way. make_drawings(units="in") dimensions one sheet differently from the default.

Threads

threads.py carries ISO metric tables (pitch, tap drill, clearance fine/medium/coarse, hex and socket head sizes, nuts, washers) and helpers available in every script:

Inch threads too. Unified sizes work everywhere a size is accepted: 1/4-20, #10-32, 3/8-16 (a bare 3/8 means the coarse series). thread("1/4-20") gives major, pitch, tpi, tap drill and ASME close/normal/loose clearance holes in mm; tap, bolt, nut and washer use ASME B18 hardware tables, and drawings call out 1/4-20 UNC THRU alongside M4×0.7.

Registered threads appear in the model summary and in shop drawings as callouts such as M4×0.7 ↧6 or M4×0.7 THRU instead of Ø3.3.

Gears

Scripts can call spur_gear(module, teeth, thickness, bore=0, pressure_angle=20, hub_d=0, hub_h=0, keyway=(w, depth)) for a true involute spur gear (Z up, tooth 0 on +X), involute_gear_profile(module, teeth) for the closed 2D outline, and gear_dims(...) / gear_centre_distance(module, za, zb) to lay out a train. Meshing gears share module and pressure angle; rotate one by half a tooth pitch so the teeth interleave. Ask for it in plain words: “a 20-tooth module 2 gear, 10 thick, 8 mm bore, with a 20 mm hub”.

For complex assemblies the agent builds one body at a time, checking each build before adding the next, so a slip in one part does not cost the whole attempt.

Planetary sets. planetary_layout(module, sun, planet, n) gives the ring tooth count, ratio, planet positions and the rotation each planet needs to mesh; it raises if the planets can't be equally spaced or would collide. Sketch a ring gear as the housing outline minus involute_gear_profile(m, z_ring, addendum=1.25, clearance=0) and extrude it, or use kit.ring_gear and kit.planetary_stage.

Design Kit

Every script has a pre-imported kit of ready-made standard components, and the agent has a kit tool to search them together with design guides. It checks the kit before hand-modelling a standard part, then calls it in the script:

motor = kit.nema_stepper(17, 40, detail="full")               # dict of parts, front face at z = 0
stage = kit.planetary_stage(0.6, 18, 18, 3, face_width=8)     # sun, phased planets, ring
result = {"Motor": motor, "Stage": kit.place(stage, Pos(0, 0, 13)),
          "Bearing": kit.place(kit.ball_bearing("688ZZ"), Pos(0, 0, 29)),
          "Screw": Pos(15.5, 15.5, 37) * kit.socket_screw("M3", 40, real=True)}

27 guides cover gears, bearings, shafts, springs, linkages, O-rings, fasteners, motors, boards, frames, enclosures, fits, materials, metric threads and stock sizes, FDM and resin printing, CNC, sheet metal, laser cutting, moulding and build123d pitfalls. Each workspace has its own kit layer in workspace/kit/: the agent adds notes to entries, saves guides and components there, and its TOC.md is regenerated with what the workspace uses most. Agent tool: kit(action, ...) with toc, search, read, note, save_guide, save_part.

Draft threads. While the agent works, real=True threads build as plain cylinders so rebuilds stay fast; when its turn ends the app builds the design once with the real helices (⚙ Settings key draft_threads).

Extensions

The agent can extend the app itself. An extension is one Python file in workspace/extensions/, written by the agent with its extension tool (a file that doesn't load, or registers nothing, is refused). build123d, the script helpers and kit are pre-imported, plus four decorators:

@helper                                   # callable from any design script
def wall_thickness(shape, point): ...

@tool("hole_report", "Every hole with diameter, depth and thread")   # agent-callable
def hole_report(ctx, body: str = None): ...                          # schema from the signature

@panel("Bolt pattern", icon="✣", description="Holes on a pitch circle")
def bolt_pattern(ctx):                    # re-rendered whenever one of its controls changes
    s = ctx.state
    return ui.panel(ui.picker("face", "Face", what="face"),
                    ui.number("pcd", "PCD", s.get("pcd", 40), min=1, unit="mm"),
                    ui.button("Apply", call="apply", primary=True))

@on_build                                 # after every successful build; return warnings
def check(ctx): ...

• Panels are declared, not coded. A panel function returns a JSON schema of sliders, numbers, selects, checkboxes, face and body pickers (click, then click in the viewer), tables whose rows select the face they describe, key/values, badges, images and buttons. The browser renders it from the Extensions menu in the Design toolbar with the app's own styling, so agent-written UI keeps working across releases. A control change re-renders the panel; open panels follow every rebuild.
• Changes go back through a result dict: set_params, wrap (rewrite a body's expression), append / edits, code, select, highlight, chat (ask the agent) and ui (show more). Extension code stays plain synchronous Python with read access to the model: ctx.bodies, ctx.faces, ctx.params(), ctx.holes(), ctx.selection.
• Tools are callable at once through extension call, and become first-class ext_<name> tools after a session restart. show_panel shows a one-off table or report without saving anything.
• Hot reload. Edit or drop a file in extensions/ and the Extensions menu updates within two seconds. ⚙ Settings ▸ Extensions lists them (enable, disable, view code, delete); a broken file shows as FAILED TO LOAD and never breaks a design.

Built-in examples, also what the agent reads for reference: Parameters (every numeric parameter as a slider with live rebuild), Hole report (Ø, depth, thread and position of every round hole; click a row to select it) and Bolt pattern (pick a face, set PCD / count / Ø / angle, Apply writes a pattern_circular cut into the script). Ask for your own: "Write an extension with a panel that estimates mass and cost per body", "Add a build check that warns when a wall is under 1.2 mm".

Parameters

Every top-level name = number in the script is a field in the Parameters card under the Browser (↑↓ ±1, ⇧ ±10, ⌥ ±0.1). Changing one rewrites that literal and rebuilds. Library parts saved as designs keep their parameters, so from_library("bracket", width=30) works. Agent tools: get_parameters, set_parameters. API: GET/POST /api/params.

Configurations. Named variants are parameter overrides declared in the script: configurations = {"Small": {"plate_l": 40, "plate_w": 30}, "Large": {"plate_l": 120}}. The Parameters card shows a selector (Default plus every variant); choosing one rebuilds the viewer with those values while the script's literals stay as they are, and editing a number while a variant is active edits that variant. Manage… opens a table to add, edit and delete variants and to Export all: every variant and the Default, built with real threads, as exports/<design>-<name>.step / .stl. The agent's configurations tool lists, sets, deletes, activates and exports them, and it can write the dict directly. The active variant is remembered per workspace. API: GET/POST /api/configs.

Measure

Press I (or Inspect ▸ Measure in the toolbar); a measure panel appears over the viewer. The cursor snaps vertex > edge > face point with a live readout: line length, arc radius and sweep, circle Ø. Two picks give the distance with the closest points drawn and labelled, Δxyz, and the angle (line–line, line–plane, plane–plane) with parallel and perpendicular flags; two circles give centre spacing; two planes give the gap. Click bodies in the Browser for volume, mass and centre of mass (material names or g/cm³), two bodies for clearance or interference volume. ⌫ or right-click removes the last pick, Esc clears. Agent tools: measure (faces, edges, points, bodies), mass_properties.

Section and interference

Section (S) cuts the model with a plane: XY, XZ or YZ with an offset slider, or parallel to a flat face you click. The half facing you is removed, and the cut faces are drawn solid and hatched in each body's colour, so the inside of a gearbox or housing reads clearly. The section stays on until you remove it (a chip in the bottom bar). The agent's screenshot tool takes a section too, so it can look inside assemblies.

Interference (J) checks every pair of bodies, or the ones selected in the Browser, with exact solid booleans after a bounding-box filter. It reports the overlap volume per pair; click one to see the overlap in red with the rest ghosted. Touching faces don't count. A bolt in a tapped hole is listed separately as thread engagement, and designs with real helical threads are checked on a quick draft-thread rebuild. The 113-body planetary gearhead takes about 20 s. The agent has the same check as check_interference and is told to run it on assemblies.

Motion, explode and render

Joints live in the script, so they are saved with the design and the agent can write them: revolute("sun", ["Gearhead/Sun", "Motor/Shaft"], axis="Z"), slider(...), couple("carrier", "sun", ratio=0.25) for gear trains and rack and pinion, parent="carrier" for parts that ride on another joint (planets), and drive("sun", 0, 1440, seconds=8). ▶ Animate in the bottom bar plays the drive and gives each free joint a slider. Check collisions runs the drive through its range and lists parts that hit each other because of the motion; the agent has the same check as check_motion.

Exploded view: a slider spreads sub-assemblies apart and then their parts (along Z, X, Y or radially) with dashed trail lines; explode({"Lid": (0, 0, 40)}, axis="Z") sets explicit offsets. Studio render (Output ▸ Render, E, or the Animate panel) switches to physically based materials with environment lighting and soft shadows: set them with appearance({"*Screw*": "black oxide", "Housing": "black anodised"}) (about 30 materials, or your own colour, metalness and roughness), with sensible defaults from part names. Save image writes a high-resolution PNG; Record video captures a turntable spin, an explode-and-return and/or the motion. Both go to exports/renders.

Shop drawings

Output ▸ Drawings (D) or File ▸ Shop drawings…, with the material and sheet size from ⚙ Settings ▸ Shop drawings: third-angle front, top and right views plus an isometric, with hidden lines (OCCT HLR projection), overall dimensions, hole callouts (n× Ø, THRU or depth, thread labels), lettered holes with a coordinate table, and a title block with size, mass, scale and date. One SVG per body plus an assembly sheet, and a DXF of the view geometry, written to workspace/drawings/. Agent tool: make_drawings.

Part library

Parts live in workspace/library/<part>/ as either a parametric script (a whole design saved with its parameters) or an exact STEP body, with description, tags and a thumbnail.

• Browser ▸ + Part inserts one as a new body: from_library("name", param=value) is added to the script.
• Body ▸ ⋯ ▸ Save to library… saves that body (exact STEP).
• The Library (File ▸ Part library…, in the right column): search by name, description and tags; insert; delete; + Design (save the current design as a parametric part); + STEP.
• The agent sees the part names in every turn and has the library tool (list, search, get, insert, save_design, save_body, delete). It is instructed to check the library before modelling standard or reusable parts.

STEP import and export

File ▸ Import STEP… (or drop a .step on the viewer) adds it as a new body (import_step("file.step") is added to the script, the file is copied to workspace/imports/), as a new design, or straight into the library. Export: File ▸ Export STEP (exact, bodies stay separate solids) and Export STL (dialog: resolution and all-or-one body). Agent: export_model(name, formats, tolerance, angular_tolerance, body). API: /api/export/{step|stl}.

3D printing

If OrcaSlicer (or Bambu Studio) is installed on your computer, the toolbar's Output menu gains Slice (P), ⚙ Settings gains a 3D printing section and the agent gains the slice_for_printing tool. AgenticCAD does not bundle a slicer; without one none of these exist.

• Set it up once in Settings ▸ 3D printing: printer, quality profile and filament (all read from the slicer's own profiles, with the printer you last used in the slicer preselected), plus layer height, infill %, wall loops, supports and brim. Everything else comes from the chosen profile.
• Slice exports the design as STL, runs the slicer headless and opens a preview panel over the viewer: layers, height, estimated time, filament weight and length, any slicer warnings, and G-code / 3MF download buttons.
• Preview: the toolpaths are drawn in model coordinates, coloured by feature (outer/inner walls, infill, top and bottom surfaces, supports, skirt). Drag the layer slider to scrub through the print; click legend entries to hide a feature; the model hides while previewing (untick to overlay). The Layers toolbar button toggles the preview, ✕ closes it.
• Agent: "slice this for my Ender 3 at 0.28 mm, 15% infill, with supports". The agent starts from your saved settings, reads printer and filament names from the slicer rather than guessing, and reports the estimates back in chat.
• Override detection with AGENTICCAD_SLICER=/path/to/slicer[::/path/to/profiles]. Outputs are kept in workspace/slicing/.

Fidelity

• The kernel geometry is exact B-rep: planes, cylinders, cones, spheres, tori, B-splines. inspect_model reports the analytic type and radius of each face.
• The viewer mesh is display-only, generated from the exact shape with exact per-vertex surface normals at a preset chordal and angular deviation (Mesh: draft / normal / fine re-tessellates without rebuilding). Picking maps triangles back to B-rep faces.
• STEP export is exact. STL is tessellated only at export, at the deviation you choose; it never reuses the display mesh.

CAM overview experimental

CAM is a second script per design, cam.py (saved as <name>.cam.py), written against cam_kernel.py and built with the build_cam tool or in Code. It must assign program. The namespace provides model, part, bodies, tools and machines.

part = bodies["Plate"]
stock = Stock.from_model(part, margin=3, top=1.0)
setup = Setup(machines["Generic 3018"], stock, origin="stock-top-left")
t6 = apply_feeds(tools[1], "aluminium", setup.machine)
program = Program(setup, name="plate")
program.add(face(setup, t6, z_top=stock.top, z_bottom=19))
program.add(adaptive(setup, t6, stock_minus(setup, part, 0.0, expand=6), z_top=19, z_bottom=4, stepover=0.15))
program.add(drill(setup, tools[5], [h for h in holes(part) if h.diameter < 6], peck="auto"))
program.add(contour(setup, t6, section(part, 0.0), z_top=4, z_bottom=-4.5, tabs=4))

Geometry comes from the exact B-rep: section(part, z), silhouette(part), stock_minus(setup, part, z, expand), free_region(part, z_top, z_bottom, within) (where a pocket can clear every level of a band without touching the part: a pocket cuts its region at every level, so a region taken from one section would cut away an island or boss rising into the band, or bore a countersink straight down), holes(part) (vertical round holes from concave cylindrical faces, with through detection), face_polygon(model.get_face(id)) for a clicked face, plus circle and rect. The CAM workspace shows the program, its setups, operations (colour and visibility) and the tools they use as a tree on the left, with warnings, Export G-code and the G-code preview; the Inspector edits the selected operation (Tool & feeds · Cut · Display) or setup (stock and origin, workholding, machine view); the machine and tool libraries live in Settings. Toolpaths, stock and the WCS origin are drawn in the viewer (rapids red) with Selected op / All and Toolpath / Stock / Machine toggles, and a timeline of op-coloured blocks with a tool marker. Send to machine → opens Machine ▸ Run with the setup's operations (experimental).

Tools. The CAM tree lists every tool the program uses, with its photo (hover for a large view with the packet's details): on a program with several setups, the tool order of each setup and which setups use each tool.

Build speed. Most of a build is usually slicing the part (section, outline, stock_minus: an exact OCCT boolean each, 0.3–1 s on a part of a few hundred faces). Slices are kept per shape and height for the session, and a setup's view of the part is the same from build to build, so when the assistant rebuilds a script against an unchanged model it reuses them: a 15-operation, two-setup sheet builds in 23 s the first time and 0.4 s after that (plus a few seconds of G-code). The slices never change the model they cut (1.4 fixed a case where an earlier slice made a later one of the same body come back empty). The assistant's Stop also stops a CAM build in progress, at its next operation or slice.

Entries. Pocket and contour passes ramp into the material at 3° (ramp=, 0 to plunge): a pocket descends along the innermost ring that is long enough to ramp on, which on a small ring is a helix, and the rings inside it follow at depth; a contour gets one entry per ring, with the lead-in just above the stock and every pass ramping down along the profile from where the previous pass ended, so there is no retract between passes and tabs still lift the tool. Face passes start and end with the tool clear of the stock. Helical ramps post as G2/G3 arcs with Z.

Simulation

Simulate on the CAM timeline (or the agent's simulate_cam tool) removes material from the stock along every move of the visible operations: all of them, or just one. The viewer shows the stock being cut in step with the slider; on the last frame gouges are red and material left on the part amber. The summary reports the volume removed, gouges (depth, area and the operation that caused them), material left on the part, stock still standing outside it, and rapids that pass through material. A GOUGES line means the program would cut the part: fix the operation's region before sending it (the assistant does). Top and bottom setups use a two-sided height map, 4th-axis setups a radial map around the axis. Side setups are not simulated yet.

On the 4th axis the cutter cuts with its real profile only up to its flute length: the body above the flutes, a neck, the shank and the holder stack are checked against the remaining bar as contacts, not cuts. The chuck body, the jaw ring and the tailstock (cone, barrel and block) are solids about the axis, placed from the machine's model and the setup's stock (the tailstock follows the stock length), and the whole tool stack is checked against them in 3D for every move, rapids included. Gouges are attributed to the operation that made them, and operations on different 4th-axis mountings (a different stock, axis, origin or machine) are refused in one simulation: simulate those setups separately. Not checked yet: the module's housing and rail, and the gaps between the jaws (the jaws are a full ring at their tips, the safe side).

Playback runs the program the way the machine would: each move takes its real time (distance at the programmed feed, rapids at the machine's rapid rate, A moves at the rotary's speed) and the tool moves continuously along it. A speed control runs from ¼× to 100× real time, ⏮ / ⏭ jump between operations, the slider is program time, and the readout shows setup · operation · tool · move · elapsed / total. The CAM tree has setup headers (WCS, stock and how it is held); ▶ in the Inspector plays from any operation or setup. On the Machine view a flipped (bottom) setup turns the work over on the table.

Rendered on the CAM timeline plays the program as a studio render: the stock is a voxel solid machined live in front of you (every move stamped into a signed-distance field in a Web Worker, meshed with smooth walls and exact floors), the part stays hidden until the stock becomes it, a chrome holder with a spinning fluted tool hangs from the spindle, the camera follows the cut with depth of field, and a HUD shows the step, tool changes and the speed factor. On a 4th-axis setup the stock is the simulator's radial map drawn as a closed bar about the axis in the same metallic material, updated at the simulation's keyframes rather than stamped live. Settings ▸ General has two switches for slower PCs: Simulation stock (voxel or the lighter height map) and Rendered simulation depth of field, which also turns itself off when a GPU takes too long per frame.

Removal rate (MRR). The simulation measures every pass against the stock as the passes before it left it: how deep the tool is buried (a ball in a slot reads the slot's depth, not the step), the volume it removes and its removal rate over one tool radius of travel. Per operation the summary gives the deepest burial against the stepdown (BITE), the highest and mean MRR against the tool's rating (stepdown × stepover width × feed) and, for finishing passes, against the operation's own average: a skim that suddenly removes several times its average has found stock the roughing left (MRR). The operations' volumes add up to the stock removed. Then limit_feeds_from_sim (the assistant's tool; also POST /api/cam/limit_feeds) slows the moves that remain over their reference, never below 25 % of the planned feed; moves that would need less are listed as path problems, because there the toolpath must change (rough first, approach from above), not the feed. Run it last, after the program is otherwise final: rebuilding cam.py resets the feeds.

Machine view and collision checks

Every built-in machine has a kinematic 3D model: the Makera Z1 and Carvera Air (bed with the real hole grid, moving bed under the rear bridge, head in X and Z, 4th-axis chuck and tailstock, enclosure), the Haas VF-2, VF-2SS, VF-4, Mini Mill and TM-1 (table with the real T-slots, saddle, column, CAT40 spindle with an ER32 holder, verified nose-to-table range) and a parametric gantry router for anything else. Machine in the CAM toolbar (A), the viewer's Machine toggle or a setup's Machine view section in the Inspector shows the program's machine around the stock and plays the simulation on it: the head, table and chuck move as they would on the real machine, the tool hangs from the spindle, and any part the simulator saw collide flashes red at that move.

The Z1's spindle head comes from Makera's own simplified CAD: a Ø16 × 20 nose under a 65 × 70 head that sits 52 mm in front of the spindle axis and only 18 mm behind it. A machine's nose stack can describe such an off-centre head as boxes about the spindle axis ({"name": "head", "box": [x0, x1, y0, y1], "h": 150}), so the collision check sees the head where it really is rather than as a circle.

The simulation checks the whole stack above the flutes (shank, collet nut, nose, collar, head) against the remaining stock, the tool tip against the bed under the spoilboard, and on 4th-axis jobs the whole stack against the chuck body, the jaws and the tailstock in 3D for every move. Contacts are listed in the summary with the operation, move, position and depth, and the agent sees them in simulate_cam. Settings ▸ Machines ▸ Model shows every number with its source and accuracy tier (verified, reference, estimated) and takes measured overrides per machine: nose profile, tool stickout, spoilboard thickness and gantry clearance. On a machine with a 4th axis the same pane has a Rotary axis row: Y (mm from the bed centre, + towards the back), Z (mm above the bed), chuck gap (the stock's end face this far in front of the chuck body face) and tailstock fitted, with a line saying where the position came from: the reference model, the machine's config (with the machine Y and Z it was converted from), probed on a date, or set here. The JSON overrides take the same keys (rotary: axis_y, axis_z in the bed frame, or axis_my, axis_mz in machine coordinates, chuck_gap, jaw_reach, tail, tail_gap, stock_length), and Zero on the 4th axis on the Machine page writes the position it finds here for the simulation. The work-area numbers are verified; castings and enclosures are representative, so treat the view as a check on the tool, holder and table, not a rendering of your exact machine.

Model your own machine

A machine's model is a script, in the same spirit as design.py and cam.py: workspace/machines/<slug>.machine.py, written in the design-script namespace plus three calls. node(name, parent, axis, mode, stock, pivot) declares the moving axes (head nodes move with the tool, table nodes carry the work the opposite way, one node carries the stock), part(name, node, shape, material, collision) attaches any build123d shape (so vendor CAD can come in through import_step), and machine(home, travel, clearance, nose, table, rotary, spoilboard, sources, notes) gives the numbers the simulator uses. The built-in Makera Z1, Carvera Air, Haas and gantry-router models are the same kind of script and are what a machine falls back to, so Code ▸ machine.py always has a starting point: edit, Run, and the machine has its own model. The Machine view section of a setup's Inspector (CAM workspace) picks any library machine, shows or hides it (the current design sits on the table) and opens or closes its doors: a script declares door nodes (node(..., door="hinge"|"slide", pivot, direction, open)) and the viewer animates them. Settings ▸ Machines ▸ Model has Show in viewer and Edit as script….

Or ask the agent. "Add my Shapeoko 5 Pro to the library and model it" is a chat request: the agent writes the script with build_machine, screenshots it, and tells you which numbers it verified and which it estimated. Drop photos of your machine into the chat and it models against them; the built-in Z1, Carvera Air and Haas VF-4 were made that way from the makers' product photos, with every number tagged verified, reference or estimated.

Fixtures: vises, clamps, plates

How the work is held is part of a setup: Setup(..., fixture="Makera low-profile vise") seats the stock's bottom-centre at the fixture's work origin (thin stock is raised on parallels automatically), the viewer draws the vise, clamps or plate around the stock and on the machine's bed, and the simulator treats every fixture part as uncuttable, so the tool or holder touching a jaw or a clamp bar is reported as a collision with that fixture. Built-ins: Makera low-profile vise, Carvera Air vise, 4" screwless vise, 6" Kurt-style vise, a parametric tooling plate and step clamps. A setup's Inspector has a fixture picker under Workholding (the choice lands in a fixtures({...}) line in cam.py), Settings ▸ Fixtures lists them with Show in viewer and Edit as script…, and Code ▸ fixture.py edits and builds them.

Several fixtures at once. Besides the fixture that holds the stock, a setup can have more on the table, each placed and turned on its own: Setup(..., fixtures=[{"name": "Step clamps", "at": (x, y), "rot": 90}]), or the setup Inspector's Workholding, where you pick, move (X / Y from the table centre), turn 90°, add and remove them. All of them are drawn on the machine and checked against the tool and holder; the simulation names the fixture it hit, and the program check warns when fixtures overlap the stock or each other.

Makera Z1 low-profile vise. Modelled from Makera's dimensioned photos and quick-start guide: a 226 × 103 mm T-slot extrusion that bolts to the bed with the MDF wasteboard removed, a fixed jaw at −X and a moving jaw on a carrier closing along X up to 130 mm. Its slotted soft jaws hold thin stock on ledges 20 mm above the rails; stock taller than the jaws sits on the rails (fixture_params={"seat": "rails"}). Heights not labelled by Makera are measured from its photos to about ±0.5 mm and err on the tall side; enter your own caliper readings with base_h, jaw_h or ledge.

Like machines, a fixture is a script: part(name, shape, material, collision) in the fixture frame plus fixture(name, work_origin, clamp_axis, max_opening, mount, sources, notes), with the stock size and parameters available. Ask the agent ("add my 3-inch screwless vise", or hand it photos) and it writes one with build_fixture; ask for a CAM job and it uses the fixture you name, or recommends one and says so.

Setups and the 4th axis

A program can have several Setups. orient="bottom" (or front, back, left, right) turns the part so that side faces the spindle; setup.view(part) gives the part as the machine sees it for section and holes. Each setup gets its own work offset (G54, G55, …); between setups the post stops the spindle, parks and pauses for you to flip or re-fixture the part, then restarts the spindle.

top = Setup(machines["Makera Z1"], stock, name="Top")
bot = Setup(machines["Makera Z1"], stock, orient="bottom", name="Bottom")
program = Program(top)
program.add(pocket(top, tools[3], rect(-15, -10, 15, 10), z_top=12, z_bottom=8))
program.add(pocket(bot, tools[3], circle(10, 0, 12), z_top=0, z_bottom=-3))   # after the flip

Tiles. Setup(..., tiles=tiles_of(model, "badge")) runs every operation at each copy of a pattern: the operation is computed once, on the part, and the post runs it at every tile, all tiles with one tool before the next tool change. program.add(op, tiles=False) is for an operation computed over the whole plate (facing, roughing the block). Time, bounds, the simulation (every tile is cut, and its statistics are folded back onto the operation's moves), the viewer and the G-code all include the tiles. On a Makera the tiles run in G54 with offsets; tile_wcs=True puts each tile in its own work offset (G54 … G59.3, with the offsets to set listed in the header) on other controllers, and is refused on a Makera, whose firmware makes the fitted tool the length reference whenever a work offset's Z is set and keeps only G54 across a restart. An 8-badge sheet: the same cutting lines as the copied-bodies program to 0.001 mm, from 635,021 moves instead of 2,108,565, posted in 25 s instead of 89 s.

sheet = Setup(machines["Makera Z1"], stock, origin="stock-top-left", tiles=tiles_of(model, "badge"))
program.add(face(sheet, t2, z_top=1, z_bottom=0), tiles=False)     # the whole plate, once
program.add(contour(sheet, t2, outline(bodies["badge"]), z_top=0, z_bottom=-2.9, tabs=3))   # at every tile

On a machine with a 4th axis (rotation about X, A in degrees), Setup(..., rotary=True) puts the part on the axis; Stock.cylinder(d, length) describes bar stock, and the work origin is on the centreline (rotary-axis-left by default, or rotary-axis-center). Indexed 3+1 work uses ordinary operations on rotary setups at fixed A angles (a=90); setups on the same mounting share one work offset and the post just turns A, and every 3+1 operation indexes A to its setup's angle by the short way, even after a continuous one. Continuous 4-axis: rotary_rough (rings or lines from a radial height map, leaving stock), rotary_finish (lines, rings or one continuous spiral, ball or flat), rotary_wrap (pocket or contour a 2D pattern wrapped onto the cylinder), rotary_profile and gear_teeth. Rings alternate direction so A stays within one turn, and after a spiral the Makera post drops the whole turns (G92.4 A0 S0, as MakeraStudio does) so the next index is a short move.

Rotary profile. rotary_profile(setup, tool, profile) turns a hex, square, cam, splines or any cross-section out of round stock: profile is a polygon in the setup's Y–Z plane (the section perpendicular to the axis, the same at every X in x_range). For every A the tool tip sits at the lowest Z that keeps the whole tool, with its real profile, clear of the turned section, cut as rings from the stock radius down stepdown per level. Concave corners tighter than the tool and slots narrower than it are reported as unreachable. regular_polygon(sides, across_flats, rotation=0) gives the polygon, with a flat facing up at A = 0.

bar = Setup(machines["Makera Z1 + 4th axis"], Stock.cylinder(20, 60), rotary=True)
program.add(rotary_profile(bar, tools[1], regular_polygon(6, 16), x_range=(5, 45), stepdown=1.0))

Gear teeth. gear_teeth(setup, tool, module, teeth, width=None, helix=0, ...) cuts involute spur or helical teeth with a gear cutter tool (Settings ▸ Tools, type Gear cutter: module, pressure angle, cutter number as the lowest tooth count of its range, disc Ø and width, arbor shank Ø and nut; it is drawn to scale with a legend, and its module must match the gear's). The cutter works from the side of the blank, where its form lines up with the tooth space: the cutter's axis is vertical, its disc is centred on the axis height, and it cuts at the 3 o'clock side of the blank (side="+y" or "-y"). Y is the depth (passes of stepdown mm of radial depth towards the axis, the last to the root radius plus leave minus backlash), X is the feed across the face width (one direction only, climb, with a lead-in and lead-out of the cutter radius plus 2 mm beyond both faces and the return made clear of the blank), and A indexes 360/N between spaces from a0. Helical teeth are A interpolated along X (helix in degrees, positive for right hand). It warns about a wrong pressure angle or cutter number for the tooth count, a disc narrower than the space at the tip line, a blank bigger or smaller than the tip diameter, an HSS surface speed over 80 m/min, and a lead-in that reaches the chuck jaws or the tailstock. The simulation cuts the teeth exactly: a 20-tooth module-1 gear comes out within 0.02 mm of the model.

blank = Setup(machines["Makera Z1 + 4th axis"], Stock.cylinder(22, 12), rotary=True)   # Ø22 = tip Ø of a module-1, 20-tooth gear
program.add(gear_teeth(blank, tools[8], module=1.0, teeth=20, stepdown=0.75))          # T8: a module-1 gear cutter

Checks for 4th-axis programs, shown as warnings in the CAM tree before you run: swing diameter and length against the module, a missing or uninstalled axis, a work origin off the rotary centreline in Y or Z (4th-axis programs must be zeroed on the axis), Y and Z reach from the axis (the Z1 with the module fitted reaches 159 mm in Y), toolpaths below the bed, A speed against the module's maximum (the controller would slow those moves and the time estimate would be short), an operation that moves A on a setup that is not rotary, and stacked roughing bands that leave different skins on their walls. In the CAM tree, + Add operation on a rotary setup offers Rotary rough, Rotary finish, Rotary profile and Gear teeth alongside the flat operations.

Makera Carvera

The Makera Z1 and Carvera Air are built-in machines, with and without the 4th axis, using a makera post written against the controller firmware: lines of at most 63 characters, no line numbers, M6 Tn on one line (the machine runs the manual tool change and measures the new tool), M3 only once a tool is active, G28 to park, M600 between setups, up to nine work offsets, no arcs while A moves, and A-axis feed rates converted the way the firmware interprets F on mixed linear and rotary moves. Tools larger than the 1/8" collet are flagged.

Haas and LinuxCNC

Two Fanuc-style posts join GRBL and Makera. haas (NGC and Classic controls): % wrapper and an O-number line, ( ) comments, every number with a decimal point (Haas reads X10 as ten least-increments), Tn M06 then G43 Hn on the first Z move, G53 G0 Z0. retracts, M00 stops between setups (and before each tool change on machines without a changer), G93 inverse-time feed for moves with the rotary axis, M30. linuxcnc (rs274ngc): G64 P0.01 path blending, Tn M6 G43 Hn (with hal_manualtoolchange LinuxCNC prompts at M6; with an ATC it changes), (MSG, …) operator messages, G53 G0 Z0, G93, M2.

Built-in machines: Haas VF-2 (30 × 16 × 20 in, 8,100 rpm, 1,000 ipm, 20-pocket changer), VF-2SS (12,000 rpm, 1,400 ipm, 24+1 side-mount), VF-4 (50 × 20 × 25 in), Mini Mill (16 × 12 × 10 in, 6,000 rpm, 10 tools) and TM-1 (30 × 12 × 16 in, 4,000 rpm, 200 ipm, no changer as standard, so the post stops before each tool change), all CAT 40 with flood coolant and the standard-configuration numbers from Haas's spec sheets; and a generic LinuxCNC mill (3-axis, and + 4th axis) whose envelope you edit to match yours. Tool offsets (H) and the work offset (G54) must exist on the control. CAM remains experimental: simulate, then prove out slowly.

Machines and tools

workspace/machines/*.json: travel, max feeds per axis, rapid, spindle range, safe and clearance Z, tool-change policy (pause, atc, manual, none, split), post (grbl, makera, haas, linuxcnc), collet, 4th axis, max_stepdown per material for the feeds calculator (the Makera Z1 caps aluminium at 0.8 mm), arcs on/off and arc tolerance, start and end G-code. workspace/tools.json: flat, ball, bull nose, V-bit, chamfer, drill, tapered ball and gear cutter tools with diameter, flutes, flute length, feed, plunge, rpm, stepdown, stepover (a gear cutter adds module, pressure angle, cutter number, disc width, arbor shank and nut). Defaults: a Generic 3018, a Shapeoko-class router, the Makera Z1 and Carvera Air with and without the 4th axis, the Haas VF-2 / VF-2SS / VF-4 / Mini Mill / TM-1, and a LinuxCNC mill with and without a 4th axis; tools T1–T7. Edit them in Settings ▸ Machines (a form per machine, or JSON) and Settings ▸ Tools (a list and an editor that describes each tool the way its packet does), or ask the agent (save_machine, save_tool). feeds(tool, material, machine) and apply_feeds(...) compute feeds for 13 materials with spindle and feed clamping and radial chip thinning; Settings ▸ Tools has a calculator with “Apply to Tn”.

Per-operation tool settings. Click an operation in the CAM tree; the Inspector's Tool & feeds shows the spindle speed, feed, plunge, stepdown and stepover it runs with. Blank fields use the tool's values; anything you type overrides them for that operation only, and a calculator fills them for a material on the program's machine. Overrides are one line at the top of cam.py, overrides({"Pocket": {"feed": 500, "stepover": 0.3}}), keyed by operation name ("Face#2" for the second op with the same name), so they are saved with the design and the agent keeps them; an override that no longer matches an operation is flagged.

Operations

All operations work in model coordinates; the post translates to the WCS origin you chose: stock-top-left, stock-top-center, stock-bottom-left, stock-bottom-center, model-origin, or an (x, y, z); on a rotary setup rotary-axis-left or rotary-axis-center.

Adaptive clearing

The adaptive op is constant-engagement by construction. It keeps a polygon of the region cleared so far; each pass is the boundary of that region offset inward by (radius − stepover), intersected with the cut region, so the tool's leading arc never exceeds the target engagement angle in open material. It starts with a helix entry, morphs spirals outward, links passes with short retracts, and slows the feed where geometry forces a higher engagement (concave corners, which the summary and G-code warn about). A fine-grid sweep audit in the test suite measures the leading-half contact angle along every pass. Rest machining removes what a larger previous tool could not reach.

Post and G-code

Program.gcode() writes the GRBL dialect: header comments (machine, stock, origin, time, warnings), G21 G90 G94 G17, G54, M3 S, G0/G1 with F on change, G2/G3 arcs fitted to circular runs (chord-sagitta checked, ≤180° per arc, collinear moves merged), M6/M0 tool-change pauses, M30. Makera machines use the Makera post. Checks: machine travel, spindle range, feeds clamped, cutting below the stock bottom, multiple tools with tool_change: none, and the 4th-axis checks on rotary programs. Tolerance per kind: roughing operations are posted at the machine's arc tolerance; finishing operations (parallel3d, vcarve, chamfer, rotary_finish, rotary_profile, gear_teeth, and anything cut with a V or chamfer tool) at 0.005 mm, so the roughing tolerance never becomes the surface accuracy of a facet edge. Every point the collinear merge drops is tested against the chord that replaces it, and straight runs with rounding noise are never fitted as huge-radius arcs. Download with Export G-code in the CAM workspace or /api/gcode; the agent's export_gcode writes to workspace/exports/ and reports line, move, arc and tool-change counts. Not yet: canned drilling cycles (GRBL has none), thread milling.

Makera Z1 control experimental

The Machine workspace connects to a Makera Z1 on your network (type its address or Find, then Connect). The status strip shows the state, position, tool and Control; nothing moves until Control is on, and it turns itself off on disconnect, alarm, lost status or after five minutes unused. Hold, Pause, Stop program and STOP are always in the strip. Below it, the machine's camera with the jog pad, and four steps in the Inspector. On a Z1 with the rotary module the strip and the phone's DRO show A° (work A over machine A) next to X, Y and Z, and the jog pad gets an A+ / A− column with its own step (1°, 10°, 45°, 90°), under the same guards as the other axes; A appears only when the machine is known to have a 4th axis (the machine record has it, or the status reports a non-zero A).

• Prepare: connect, home, change tool (Makera's own M6 Tn: park, wait for you, then measure the tool on the setter; every tool and probe is measured before the machine moves with it), accessories (light, dust collector, spindle fan). The setup's tools are a picture list in the order it uses them, then the probes and the rest of the library, each with Change (Re-measure for the fitted one); hover a picture for a large view. A tool's photo shows on the change card so you pick up the right one, and the card names the tool the program is waiting for (the next tool, not the fitted one).
• Zero: what the CAM setup wants (for example the front-left top corner of the block) next to what set the machine's origin this session, with a guided 3D-probe sequence. Find the block probes three outside corners of a block in the L-bracket and puts X0 Y0 on the front-left corner from the measured faces, checking the block size against the setup. On a rotary setup the card is Zero on the 4th axis: Makera's own routines, one step at a time, each behind a confirmation. Read from the controller fetches the module's position (config-get sd coordinate.rotation_offset_x/y/z, read-only); then Z0 on the centreline is Makera's 4th-axis Z probe (M495 X0 Y0 O0 with the wired probe T0 fitted and measured: Z goes up, the head goes to the module's reference pad, touches it fast then slow, and the firmware sets work Z0 the rotation offset below the pad, on the chuck centreline; watched like the 3D-probe routines); Bed height (optional) is Auto Z here over the bare bed with the same probe then Use as bed height, which gives the axis height above the bed exactly because the probe's length cancels, and writes it to the machine's model for the simulation; Y0 on the centreline is G10 L2 P0 Y at anchor1_y + rotation_offset_y, the controller's own sum, or a typed machine Y; A0 here makes the chuck's current angle A0 (G92.4 A0, then G10 L20 P0 A0), with Shrink A (G92.4 A0 S0) to drop whole turns from the count; and X0 at what the setup wants, X0 here or the chuck face's machine X plus the offset to the origin. With Z0 on the centreline the stock top sits at Z = the stock radius, so the card offers a Z floor above it before you jog. The CAM program's warnings cover the rotary checks (origin off the centreline, Y/Z reach, A speed, swing and length); read them before Send to machine →.
• Run: a readiness checklist (connected, homed, origin set for this setup, the tool fitted and measured), the program's operations grouped in tool runs, Air cut first, then progress op by op, with time left shown large for this operation and for the whole program (with the clock time it should finish), from each operation's estimate scaled by how the run is going against it. Every spindle start lifts in machine coordinates, moves over the first point, starts the spindle and only then comes down.
• Manual: go to (Z goes up first), set the origin at the head or by typing, any 3D-probe routine, a 4th axis row (A0 here, Shrink A, 4th-axis Z probe) on machines with the module, a one-line console (each line confirmed, blocked commands refused) and Run a file with the same checks.

The assistant can work the machine too: hold, pause, stop program and STOP act at once; everything else becomes an approval card in the chat and on the Machine page, and runs only when you click Approve. Settings ▸ Phone control adds a phone page with the camera, STOP and tool changes, and (1.2) notifications on the phone when the machine waits for a tool, finishes or stops — Web Push done in the app: the app makes its own certificate (trusted once on the phone) and push keys, and sends each message, encrypted, straight to the phone's push service; tapping opens the page with Confirm. Machine ▸ Manual has a Cleaning position (Z to the top, head over the front-middle of the bed, table fully back) so what Home covers can be brushed out; Home again when done.

Settings and MCP

The Settings button (the gear at the right of the top bar) opens a window with tabs: General, MCP servers, Extensions, Drawings & printing, Machines, Fixtures, Tools and Phone control. General and MCP: Claude model (default Claude Opus 5.5; any model id, or the Claude Code default), effort (low … max), max steps per turn, thinking summaries, web tools, extra standing instructions, and MCP servers (stdio, http or sse configs as JSON with enable toggles and live connection status from the session). Saved to workspace/settings.json; “Save & restart agent” starts a fresh session with the new options and tells the agent its earlier history is gone. API: GET/POST /api/settings, GET /api/agent/status, POST /api/agent/restart. Settings also holds the Shop drawings defaults (material, sheet) and, when a slicer is installed, the 3D printing defaults (printer, quality, filament, layer height, infill, walls, supports, brim) used by Output ▸ Drawings and Slice and by the agent.

Agent tools reference

The agent runs in a Claude Agent SDK session with an in-process MCP server named cad. It has no shell; everything it knows about the model comes back from these tools.

Keyboard shortcuts

Architecture

A local server runs the kernel and the agent; the browser (or the desktop window) is the UI. There is no cloud component other than Claude itself, and the slicer is whatever you already have installed.

The design itself is one Python script written against build123d. The agent edits it through its tools; chat, the toolbar, the parameters panel and the sketch editor all edit the same file, so every route stays reproducible. One server process holds one design and one agent session.

Files and API

HTTP endpoints: /api/designs, /api/design/{save,open,new,import,download}, /api/export/{fmt}, /api/import/step, /api/params, /api/measure, /api/drawings, /api/library/*, /api/sketches, /api/cam/{library,machine,tool}, /api/gcode, /api/gcode/preview, /api/settings, /api/agent/{status,restart}, /api/version. The WebSocket carries chat, builds, undo, quality, screenshots, and the manual operations (op, rename_body, set_sketch, add_primitive, transform_body, …).

Versioning

version.py holds the version (next to the AgenticCAD name in the top bar, click for the changelog) and CHANGELOG.md follows Keep a Changelog. Pre-1.0: minor bump for features, patch bump for fixes; a release is a bump plus a git tag. /api/version serves both.

Tests and evals

.venv/bin/python -m pytest -q            # unit / API tests, seconds, no Claude calls
.venv/bin/python evals/run.py            # agent evals: real agent, headless, graded; ~$5 per run
.venv/bin/python evals/run.py --filter cam --model claude-sonnet-5 --repeat 3

• Unit tests (438) cover the kernel (bodies, ids, exact normals, exports, measurement), script editing, CAM (holes, sections, every op, arc post, machine checks, feeds, simulation, setups, the 4th axis and an independent engagement audit of the adaptive op), drawings, the library, the Design Kit, threads, sketches and the constraint solver, features, interference and motion, extensions, and the FastAPI/WebSocket API with the Claude session disabled.
• Evals (39 cases) run the real agent in a throwaway workspace, one fresh session per case, graded by deterministic geometry, program, UI and answer checks (bbox, bodies, holes, volume, interference, parameters, script contents, op parameters, G-code validity, simulation results, extension files and panels, tools used, answer regex). Results land in evals/results/<stamp>.json|md with pass rate, cost, steps and time per case. Add a case by appending to evals/cases.py.

Known gaps and roadmap

• One user per server; up to four assistants run at once, and a conversation resumes when its tab wakes but not after the app restarts.
• CAM simulation checks run on a height map (tool, holder and head against stock, bed and fixtures); side setups and different 4th-axis mountings are simulated separately and time estimates ignore acceleration. On the 4th axis the chuck body, jaws and tailstock are checked in 3D, but not the module's housing and rail, and the jaws are a full ring with no gaps between them.
• Adaptive corners rely on feed reduction; no trochoidal slotting, no 3D rest, no Z-level finishing.
• Sketches have no fillet, trim or construction geometry yet.
• Manual tools are typed, not dragged (except Press/Pull and sketch points); joints are declared in the script rather than placed by mating faces; pattern() places copies of a whole part (no feature patterns).
• Drawings have overall dimensions and hole tables only; no section views or PDF.
• Face and edge ids change on every rebuild.

Roadmap, roughly in order: projects and sessions; CAM holder and shank collision checks; mate-based assembly positioning; drag handles everywhere; a WebSerial G-code sender; drawing and import upgrades; deployment (Docker, auth, multi-user); other posts and 3D-printing exports. Issues and contributions: github.com/agenticcad/agenticcad.

Licence

AgenticCAD is free for non-commercial use under the PolyForm Noncommercial License 1.0.0: personal projects, research, education, hobby making, charities, schools and public institutions. Commercial use (in a business, in products or services, or as part of paid work) needs a commercial licence: A$99 per user per year, one licence per person who uses it. Buy online for the number of users you need; the Stripe receipt showing users and period is your licence record, with nothing to enter in the software. Volume or site licences: agenticcad@prodevelop.com.au.