agentcad

name	agentcad
description	CAD tool for AI agents. Use when the user asks you to design, model, or build a 3D object. agentcad executes build123d or CadQuery Python scripts and produces STEP files, PNG renders, mesh exports (STL/GLB/OBJ), and geometric metrics.
compatibility	Requires Python 3.10-3.12 and agentcad installed (pip install agentcad).
allowed-tools	Bash(agentcad:*)
version	0.4.0
metadata	{"openclaw":{"requires":{"bins":["agentcad"],"anyBins":["python3.12","python3.11","python3.10"]}}}

agentcad — CAD tool for AI agents

You have access to agentcad, a CLI that turns build123d or CadQuery Python scripts into 3D geometry. All output is JSON. Every command returns "command" and "status" keys.

First-time setup

agentcad init --name <project_name>
agentcad --help   # Read this — it is your complete operational briefing

Core workflow

1. Write a script. No imports needed — build123d primitives, show_object, and agentcad edit helpers are pre-injected by default. show_object(result) is required.

2. Dry-run first to check metrics without consuming a version:

   agentcad run script.py --output test --dry-run
   

   Check volume, dimensions, is_valid in the response.

3. Run for real. Visual feedback is on by default:

   agentcad run script.py --output label
   

   Every successful run produces (paths in the JSON response):

   • preview.png — 4-view composite (front, right, top, iso). Read this to confirm the part looks right before iterating. One image, all 4 angles.
   • diff.side_by_side — side-by-side PNG vs the most recent successful prior version. Read this when iterating to see what your change did.
   • diff.overlay — tinted (green prev, red this) overlay for subtle shifts. Read only if side-by-side didn't resolve the question.
   • viewer.html — interactive 3D viewer for the user (humans only; you can't render HTML). Mention it to the user so they open it.

   Pass --no-preview only for tight parametric sweeps where latency matters.

4. Show the user. After a successful build, open the interactive viewer:

   agentcad view v1_label/viewer.html   # or output.step / output.glb
   

   Users expect to see the result in a browser. Do this every run, unprompted.

5. Inspect if invalid. If is_valid: false or geometry looks wrong:

   agentcad inspect v1_label/output.step
   

6. Measure feature sizes. For dimensions beyond top-level metrics:

   agentcad measure v1_label/output.step
   

   Use this for hole diameters, cylindrical boss diameters, edge lengths, face areas, and full per-feature measurements with --features.

7. Check explicit feature requirements. If the prompt names measurable holes, bores, or cylindrical bosses, write them into spec.json before final handoff:

   {"features":[{"name":"bolt_holes","type":"cylinder","diameter_mm":6,"count":4}]}
   

   Then run:

   agentcad check-spec v1_label/output.step spec.json
   

   Revise the CAD if passed is false. status: success only means the comparison ran; passed is the actual spec-check result. If you include axis, copy it from agentcad measure's cylindrical_features[].axis.

8. Iterate. Fix the script, run with a new --output label. Use agentcad diff 1 2 to compare versions.

Script writing rules

• show_object(result) is required — at least one call.
• These are pre-injected by default (no import needed): build123d primitives like Box, Cylinder, Sphere, Plane, plus show_object, load_step, pick_face, pick_edge, fillet_edges, chamfer_edges, shell_faces, cut_pocket, boss, split_by_plane, replace_face, annular_boss, and raise_annulus.
• For imported STEP annular edits, use the non-fuse workflow:

  raw = load_step_shape("v1_vendor/output.step")
  result = raise_annulus(raw, center=(0, 0), inner_diameter=40,
                         outer_diameter=80, height=7, z=5)
  show_object(Compound(result))
  

• CadQuery remains supported. Use import cadquery as cq, initialize with agentcad init --runtime cadquery, or pass --runtime cadquery.
• CadQuery helper paths operate on TopoDS_Shape. Bridge with .val().wrapped:

  import cadquery as cq
  part = cq.Workplane('XY').box(10, 20, 5).val().wrapped
  moved = translate(part, 50, 0, 0)
  

• To show helper output:

  import cadquery as cq
  show_object(cq.Workplane('XY').newObject([cq.Shape.cast(topo_shape)]))
  

• For OCP internals (gp_Pnt, BRepPrimAPI, etc.), import manually.

Key commands

Command	Purpose
agentcad init --name NAME	Initialize project
agentcad run SCRIPT --output LABEL	Execute script, produce STEP + metrics
agentcad run ... --dry-run	Metrics only, no version consumed
agentcad run ... --no-preview	Suppress preview (on by default)
agentcad run ... --render iso,front	PNG views
agentcad run ... --export stl,glb	Mesh export
agentcad run ... --params k=v,k=v	Override script parameters
agentcad render STEP --view SPEC	Post-hoc renders with camera control
agentcad export STEP --format stl,glb	Post-hoc mesh export
agentcad measure STEP	Dimensional report (overall metrics + feature sizes)
agentcad check-spec STEP spec.json	Pass/fail checklist against intended cylindrical features
agentcad inspect STEP	Topology report (validity, free edges)
agentcad parts list REF	List parts captured for a version
agentcad parts show REF ID	Show one versioned part by stable id
agentcad diff REF1 REF2	Compare versions
agentcad context	Project state
agentcad docs [SECTION]	Deep-dive docs (17 sections)
agentcad view FILE	Run this after every successful build — opens GLB/STEP in the user's browser

Debugging playbook

1. Check metrics first — volume and dimensions catch most issues.
2. Read preview.png — the 4-view composite. Fastest way to spot obvious problems.
3. Read diff.side_by_side if iterating — confirms your change did what you intended.
4. Negative volume? Wire winding is backwards (CW instead of CCW).
5. Need a hole diameter or edge length? Run agentcad measure output.step.
6. Need to verify explicit hole/bore counts? Write spec.json, then run agentcad check-spec output.step spec.json.
7. is_valid: false? Run agentcad inspect — check free_edge_count and shell status.
8. Hollow shape? free_edge_count > 0 means open shell.
9. Complex profiles (gears, splines)? Use subtractive construction — cut from a blank cylinder/box instead of building up. See agentcad docs patterns.

Patterns

• Build at origin, then position: Create geometry at origin, use translate() and rotate() to place it.
• Compound vs Union: makeCompound() for assemblies (parts stay separate), .union() for boolean fuse into one solid.
• Parametric scripts: Top-level variable assignments become overridable via --params. Use this for iteration.
• Named parts: show_object(shape, id="wheel_left", name="Left wheel", options={"color": "red"}) for stable part handles, per-part metrics, and colored GLB export.