agentcad-cli

AgentCAD

AgentCAD is a CLI-first CAD workflow runtime for coding agents.

It gives a coding agent a repeatable workspace, a contract-driven modeling protocol, deterministic build/export, geometric measurement, multi-view previews, design-time and post-build validation, regression snapshots, assembly validation, workflow diagnostics, and a delivery manifest — so the agent can iterate on CAD models with measurable feedback instead of visual intuition.

discovery -> concept -> design contract -> suggest-checks -> precheck
  -> params/source -> build -> measure -> render -> validate
  -> preview-check -> probe proof -> review -> quality review -> workflow

If interrupted at any stage, agentcad doctor <model> reports workflow gaps and recommends the next command. Before final handoff, agentcad workflow <model> is the hard gate: it runs the nonblocking proof loop and writes outputs/workflow.json.

What's in the box

Every command prints stable machine-readable JSON output. Failures include stage, error.type, and error.message. Validation failures include suggested_fix with likely_source, next_commands, and param_candidates.

Validation check types

The geometric relation checks (min_clearance, hole_accessibility, min_wall_thickness, feature_position) close the historical gap where inner_diameter_at_z would report a correct diameter for a hole that was half-covered by an adjacent wall.

agentcad review treats missing hole-access checks as blocking when holes are declared, and load-bearing attachment features without root/interface checks as blocking warnings. agentcad suggest-checks generates check templates for the same gaps before validation runs and reports suggestion_quality metrics: template count, placeholder count/ratio, concrete template count, and exact placeholder paths. A concrete suggestion should use params.json, metadata.json, existing checks, geometry bbox, and the probe plan instead of leaving unresolved <...> fields.

Assembly validation

Assemblies live in assemblies/<name>/assembly.json and reference existing models by component id, model name, and rigid transform. agentcad assembly validate <name> rebuilds stale components, resolves metadata anchors and interfaces, validates interface schema (cylindrical_male/female, screw_axis, dovetail, snap_pin/socket, gear_axis, planar), measures declared cylindrical interfaces against STL sections, emits mate residuals, checks pair coverage, writes combined/exploded SVG previews, exports <name>.mjcf.xml, generates an interactive preview.html, and round-trips the MJCF body/site data against assembly_geometry.json.

Interference validation uses two layers: AABB broad phase first, then a mesh narrow phase for overlapping component pairs. The narrow phase records triangle-contact evidence, inside-sample penetration depth, and sampled minimum surface distance.

Batch validation and regression

agentcad validate all discovers models, variants, and assemblies across the workspace, runs validation in deterministic order, and emits a project-level JSON report with per-target summaries and timings.

agentcad snapshot write stores normalized snapshots (stripping volatile timestamps/paths, keeping check results, geometry metrics, and artifact presence). agentcad snapshot compare reports check status drift, geometry metric drift (bbox, volume, triangles), and artifact changes between current and baseline — useful for CI regression detection.

Quick start

uv tool install agentcad-cli
agentcad --help

Create a workspace and start modeling:

agentcad init my-agentcad-project --model demo
cd my-agentcad-project
claude

Then ask Claude to design your target model (for example: "Design an adapter from an 8025 fan to a round duct") — it will read CLAUDE.md in this workspace and follow the workflow automatically.

For local development:

uv sync
uv run agentcad --help

Quick example

agentcad init my-cad-project --model bracket
cd my-cad-project

# 1. Suggest missing checks based on the design contract
agentcad suggest-checks bracket

# 2. Design-time: solve the contract before geometry
agentcad precheck bracket

# 3. Implement part.py, then run the post-build pipeline
agentcad validate bracket

# 4. Final hard gate before handoff
agentcad workflow bracket

# 5. If interrupted, diagnose workflow gaps
agentcad doctor bracket

The default generated model is a simple build123d cuboid. Agent rules and common-error catalog live in AGENTS.md, CLAUDE.md, and references/ (always-on reference docs for build123d patterns and validation strategy).

Feature helpers

AgentCAD ships a library of geometry helpers that build common mechanical features and optionally emit contract checks via ContractBuilder:

Helpers auto-emit contract checks (inner_diameter, section_bbox, volume_range, etc.) and metadata interfaces (cylindrical_male/female, screw_axis, snap_pin, dovetail) so every feature gets validation coverage without manual authoring. A hardware dimension database (agentcad.hardware) provides ISO/DIN specs for screws, nuts, washers, and heat-set inserts.

Examples

Re-run any example:

cd examples/fan-adapter-8025
agentcad validate fan_duct_adapter_8025
agentcad review fan_duct_adapter_8025
agentcad workflow fan_duct_adapter_8025

Batch validate the whole workspace:

cd examples/fan-adapter-8025
agentcad validate all
agentcad snapshot write
agentcad snapshot compare

Tests

uv run pytest -v

The full test suite currently reports 741 passed. It covers CLI dispatch, workspace scaffolding and sync modes, STL reading and measurement, section extraction and SVG rendering, JSON IO, post-build validation checks, feature classification, weak-check severity and review blocking gates, design schema hardening, negative regression fixtures, min_wall_thickness range mode, metadata interface schema, ContractBuilder interface emission, feature helpers, hardware lookup tables, geometric primitives, interactive previews, variants, assembly validation, batch validation, regression snapshots, workflow diagnostics (doctor), suggest-checks, CADBench quality gates, suggested-fix enrichment, timing instrumentation, section cache, executable helper cookbook, and artifact cleanup. GitHub Actions runs the fast suite on pushes and PRs; slow tests run on a scheduled/manual workflow.

Documentation

• docs/DESIGN.md — architecture, first principles, and V0–V6 iteration roadmap (with delivered milestones marked).
• docs/STATUS.md — current implementation state, recent lessons, delivered validation gates, and remaining roadmap direction.
• docs/ROADMAP.md and docs/ROADMAP_EXECUTION_PLAN.md — prioritized future work plus PR-level execution, test, and acceptance plans. P0–P4 are marked Done; P5 (optional integrations) is next.
• AGENTS.md / CLAUDE.md (workspace) — operating rules for the coding agent, including the 16-stage TDD workflow and the common design-error catalog.