agentcad
CAD CLI and MCP server for AI agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jdilla1277/agentcad with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jdilla1277/agentcad'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/jdilla1277--agentcad)HTML
<a href="/listings/jdilla1277--agentcad"><img src="/api/listings/jdilla1277--agentcad/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install agentcad, then paste this into Claude Code, Cursor, or any coding agent:
Create a Python 3.12 virtual environment, then: pip install agentcad agentcad init --name phone-stand Design me a phone stand: a simple angled cradle that holds a phone at 60 degrees. About 80mm wide, 50mm deep, with a 5mm lip at the bottom to keep the phone from sliding. Show me a preview when you're done.
Keep generated files in a build directory
Create `agentcad.toml` in your source project before initialization:
build_dir = "./build"
Then run `agentcad init`. Version directories, the generated manifest, viewers, exports, and logs go under `build/`; authored scripts and installed guidance stay in the source project. Add the build directory to your own `.gitignore`.
For CI, initialize and select an independent root with `agentcad init --build-dir /tmp/cad-build` and `agentcad run model.py --label first --build-dir /tmp/cad-build`. Overrides do not edit project configuration. Relative build paths resolve from the project root, not the caller's working directory. Existing projects keep their current layout unless configured. `--output` remains a deprecated version label, never a destination. See `agentcad docs artifacts` for the full contract.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 451 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # agentcad
- **CAD tool for AI agents.** Give your coding agent the ability to design 3D models.
- Your agent writes build123d Python scripts by default. agentcad handles execution, STEP export, PNG rendering, mesh export (STL/GLB/OBJ), geometric metrics, validation, diffing, and browser preview. CadQuery remains available as an explicit compatibility mode. Each command's final response is structured JSON on stdout.
- > **Reading the output:** the JSON response is written to **stdout**; human-readable progress and diagnostics go to **stderr**. Parse stdout as JSON and treat stderr as plain text — don't merge the streams with `2>&1` before a JSON parser, or the progress lines will break parsing. If you need both, capture them separately.
- agentcad is open source under the Apache License 2.0. It runs locally and requires no signup.
- [](https://www.producthunt.com/products/agentcad?utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-agentcad)
- ## Demo
- [](https://www.youtube.com/watch?v=Zsn31-IilWM)
- A coding agent designing in agentcad, live. See more at [agentcad.dev](https://agentcad.dev).
- ## Recently from agentcad
- - **November 11, 2026 — [From PDFs, images, and drawings to Revit](https://agentcad.dev/revit):** Model from drawings, photos, and measurements, review the geometry, and bring checked STEP files into Revit.
- - **November 6, 2026 — [v0.7.2: Retry builds without creating duplicate versions](https://agentcad.dev/changelog/v0.7.2):** Recover saved results after a lost response, keep projects separate, and preserve non-English text on Windows.
- - **October 28, 2026 — [Measuring agentcad's effectiveness, again](https://agentcad.dev/measuring-agentcad-effectiveness-again):** The workflow candidate behind v0.7.0 scored 33% higher overall than the previous agentcad result, with editing up 42% and 80 of 81 valid outputs.
- - **September 29, 2026 — [Using Meta's Muse agent for 3D printing and CAD](https://agentcad.dev/muse-3d-printing):** A CAD workflow from a phone with Meta's Muse agent, including a video walkthrough.
- - **September 3, 2026 — [The original effectiveness benchmark](https://agentcad.dev/measuring-agentcad-effectiveness):** The earlier comparison against direct build123d, with its [video walkthrough](https://www.youtube.com/watch?v=IacqGZH8Gu4).
- Browse the [change log](https://agentcad.dev/changelog) for more updates.
- The five-stage workflow below was evaluated in the v0.7.0
- [Candidate L CADGenBench run](https://huggingai4engineering-cadgenbench.hf.space/reports/james-dillard_gpt-5-nano-candidate-l-pi-harness-five-s_20261001-001100.html).
- GPT-5 Nano scored .245 overall (.175 generation, .353 editing) with 80 of 81
- valid outputs. This was a single release-candidate run, not an evaluation of
- the current release or a fresh matched direct-build123d comparison; see the
- [experiment closeout](docs/product-plans/agentcad-performance-next-steps.md)
- for the baseline, caveats, and next evaluations.
- ## Quick start
- Install agentcad, then paste this into Claude Code, Cursor, or any coding agent:
- ```
- Create a Python 3.12 virtual environment, then:
- pip install agentcad
- agentcad init --name phone-stand
- Design me a phone stand: a simple angled cradle that holds a phone
- at 60 degrees. About 80mm wide, 50mm deep, with a 5mm lip at the bottom
- to keep the phone from sliding. Show me a preview when you're done.
- ```
- To install the reusable agent skill separately, use
- [`npx skills add jdilla1277/agentcad-skill`](https://skills.sh/jdilla1277/agentcad-skill/agentcad)
- or [`clawhub install agentcad`](https://clawhub.ai/jdilla1277/skills/agentcad).
- Both install guidance, not the CAD executable; install `agentcad` with pip as
- shown above. For a project-local guide, run `agentcad skill install` instead.
- ### Keep generated files in a build directory
- Create `agentcad.toml` in your source project before initialization:
- ```toml
- build_dir = "./build"
- ```
- Then run `agentcad init`. Version directories, the generated manifest, viewers,
- exports, and logs go under `build/`; authored scripts and installed guidance
- stay in the source project. Add the build directory to your own `.gitignore`.
- For CI, initialize and select an independent root with
- `agentcad init --build-dir /tmp/cad-build` and
- `agentcad run model.py --label first --build-dir /tmp/cad-build`.
- Overrides do not edit project configuration. Relative build paths resolve from
- the project root, not the caller's working directory. Existing projects keep
- their current layout unless configured. `--output` remains a deprecated version
- label, never a destination. See `agentcad docs artifacts` for the full contract.
- ## Required agent workflow
- `agentcad init` installs a guide that requires the same workflow for new models
- and edits:
- > **Inspect → Specify → Build → Validate → Deliver**
- - **Inspect:** understand drawings, requirements, orientation, dimensions, and
- any source geometry before writing a model.
- - **Specify:** record measurable requirements and assumptions. For edits, also
- identify the target, expected change, and geometry that must remain stable.
- - **Build:** create the simplest geometry that can satisfy the specification;
- use the smallest bounded operation for an edit.
- - **Validate:** inspect visual, dimensional, difference, and structural evidence.
- If a check fails, return to the earliest incorrect stage and iterate.
- - **Deliver:** hand off only the exact STEP and requested exports that passed.
- ## Capabilities by workflow stage
- ### Inspect
- - **`agentcad import supplier.step --init`** — import a versioned baseline with
- a bounded inspection report, geometry IDs, and sampled four-view images.
- Retrieve the complete inventory or saved artifacts through `inspect`; no
- experimental flag is required. See the [artifact retrieval guide](docs/inspection-artifacts.md).
- - **`agentcad inspect output.step`** — bounded topology, orientation, addressable
- IDs, edit risk, and structural evidence
- - **`agentcad measure output.step`** — dimensions, edge lengths, face areas, and
- circular/cylindrical feature measurements
- - **`agentcad render output.step --view top,front,right,iso`** — visual evidence
- for orientation and feature location
- - **`agentcad parts list REF` / `parts show REF ID`** — inspect named parts and
- isolate one versioned part
- ### Specify
- - **`spec.json`** — records supported cylindrical-feature and structure
- requirements before modeling
- - **`agentcad check-spec output.step spec.json`** — evaluates that contract
- during validation
- ### Build
- - **`agentcad run script.py --label label`** — execute a build123d script,
- producing a versioned STEP file and geometric metrics
- - **Pre-injected helpers** — build primitives, import existing STEP geometry,
- select features, and perform bounded or validated editing operations
- - **[CAD recipes](recipes/)** — reusable features and models to copy and adapt,
- starting with a PCB enclosure with board supports and connector openings
- ### Validate
- - **`agentcad run ... --preview`** — four-view PNG for visual verification; the
- browser viewer can export an on-demand turntable GIF
- - **`agentcad diff 1 2`** — compare versions, including actual
- shared/reference-only/candidate-only source-frame volume for valid closed solids
- - **`agentcad view old.step new.step`** — open a synchronized A/B comparison
- with separate centered projection and source-frame 3D volume artifacts
- - **Live project viewer** — successful runs open one stable local project URL
- and refresh it after subsequent completed builds. Leave the tab open while
- iterating; camera and compatible review settings survive updates. Failed
- builds leave the last successful model visible. Versioned `viewer.html`
- snapshots remain available; from v2,
- previous and current are preloaded for side-by-side, overlay, and
- Parts-tab change review (`--no-view` opts out)
- - **Spatial review comments** — pin human feedback to a surface and named part;
- comments persist locally for the agent's next revision
- - **`agentcad review list --status open`** — read shared review threads; humans
- and agents can reply, resolve, and reopen with an auditable history
- - **`agentcad parts view REF`** — hand off an isolated, focused, or grouped part review viewer
- ### Deliver
- - **`agentcad run ... --export stl,glb`** or **`agentcad export`** — write mesh
- deliverables and report validation for each written format
- - **`agentcad viewer [open|status|stop]`** — open the live project or manage its
- lightweight local service; `open` is the default
- - **`agentcad docs [section]`** — runtime-aware built-in documentation and worked examples
- ## Spatial review comments
- Live project viewers opened after a run or with `agentcad viewer open` use the existing service bound to
- `127.0.0.1`. Click **Comments** in the bottom-left viewer controls, then **+ New comment**
- (or press `C`). Click the model, confirm the inferred named part and
- revision scope, then choose **Send comment**. To hold feedback back, choose
- **Save draft** instead; unsent drafts can be edited, deleted, sent individually,
- or submitted together with **Send all drafts**.
- Comments are plain local JSON under the selected build root's `.agentcad/reviews`—there is no database or
- hosted account. On its next turn, an agent can discover and reply to the review:
- ```bash
- agentcad context
- agentcad review list --status open
- agentcad review comment --message "Could this rib be thinner?" --part support_rib --version current
- agentcad review reply C1 --message "Increased the clearance to 4 mm." --version current
- agentcad review resolve C1 --message "Implemented in the current revision." --version current
- ```
- Agents can also initiate an immediately-open thread on a named part. Add
- `--scope previous|both` to target comparison sides or `--point-mm X,Y,Z` to
- place its pin more precisely. Humans and agents can both reply, resolve, or
- reopen. Every action records its
- actor, timestamp, optional message, and associated revision. The older
- `mark-addressed` command remains available for compatibility.
- New builds wait while you write or send a comment or reply, then update the
- model once you send, save, or cancel. Current/Previous/Both follow the displayed
- revision sides; the original source version stays in the thread. If a part
- disappears, its comment remains in the list as unplaced. Hiding a part hides its
- comment pins in the 3D view; its threads stay in the sidebar. Showing the part
- restores its pins. Comments become
- available to the agent on its next turn; they do not start a new agent run.
- File viewers and temporary part/diff viewers remain read-only.
- To reposition the model, click **Pan** and drag, or hold **Shift** while dragging.
- Click **Pan** again to return to orbiting. **Fit view** centers the visible model
- and adjusts the zoom to fit it on screen.
- `--label` names the version; the JSON response returns the actual file under
- `outputs.step`. The older `--output LABEL` spelling remains a deprecated
- compatibility alias and never denotes a destination path.
- ### Keep one preview open
- After a normal `run` or `import`, give the human `project_viewer.url` from the
- JSON response. That URL tracks the latest completed viewer; `viewer` still
- points to this version's snapshot. An active page prevents another browser tab
- opening. Updates are checked about once a second (less often in background
- tabs). A new model replaces the previous one only after it loads successfully.
- `--no-view` never launches a browser or starts the viewer service. If it still
- generates viewer artifacts, an already-open project page can receive them.
- The core-only `--no-preview --no-diff --no-view` combination generates no viewer;
- the page retains the older model and reports that the new preview is unavailable.
- The service binds to `127.0.0.1` and serves only registered viewer snapshots at
- private project URLs. These are local bookmarks, not public share links. URLs
- survive service restarts and builds, but moving the project folder changes its
- identity. Viewer state lives in `~/.cache/agentcad/viewer` (override with
- `AGENTCAD_VIEWER_HOME` for isolated automation). Keep that directory to preserve
- the saved port and private URLs. If the port is occupied, AgentCAD reports the
- problem without silently changing the URL. Use `agentcad viewer status` and
- `agentcad viewer stop` for diagnostics; `agentcad viewer open` restarts it.
- An incompatible service protocol requires stopping the service with the
- installation that started it before reopening with the new installation.
- ## No boilerplate
- Scripts need zero imports. By default, build123d primitives, `show_object`, and agentcad edit helpers are pre-injected:
- ```python
- box = Box(10, 20, 5)
- show_object(box)
- ```
- For editor completion or explicit dependencies, the same AgentCAD-owned
- callables are available from the stable authoring module:
- ```python
- from agentcad.api import load_step, safe_cut, translate, show_object
- ```
- Import build123d primitives such as `Box` or `Vector` from `build123d` itself.
- Do not import STEP writers: `show_object` hands the result back to AgentCAD,
- which writes and tracks the canonical STEP file.
- In build123d scripts, capture each shape object once, including across
- `show_object()`, `show_assembly()`, and `show_compound()` calls and within
- assembly iterables. Capturing an assembly also captures all its descendants;
- do not capture a child separately or reuse it in another captured assembly.
- Repeated references fail with `error_kind: "duplicate_capture"`;
- changing the name or ID does not create another instance. For intentional
- instances, use `from copy import deepcopy`, then copy the shape before positioning
- and capturing it. See `agentcad docs parts` for an example.
- `agentcad init` records build123d as the project runtime. That keeps the
- script API, built-in docs, and subsequent runs on one clear default.
- ## CadQuery compatibility
- CadQuery remains supported for existing scripts and projects, but it is not
- the default authoring path and it is not installed by default. `pip install
- agentcad` ships build123d and the OpenCascade binding only. Enable the
- compatibility runtime with the optional extra:
- ```bash
- pip install "agentcad[cadquery]"
- agentcad daemon restart # if a daemon was already running
- ```
- The extra pulls in CadQuery and its own dependency chain (CasADi and the
- COIN-OR solver libraries it bundles), which carries a larger third-party
- license surface than the default install. Selecting the CadQuery runtime
- without the extra returns a structured error naming this command. Adopting
- agentcad inside a product or hosted service? See
- [Incorporating agentcad into your project](https://agentcad.dev/incorporating-agentcad).
- For a CadQuery project:
- ```bash
- agentcad init --name legacy-model --runtime cadquery
- agentcad docs quickstart --runtime cadquery
- agentcad run script.py --label first
- ```
- For a one-off CadQuery script inside a build123d project:
- ```bash
- agentcad docs preamble --runtime cadquery
- agentcad run legacy.py --label legacy --runtime cadquery
- ```
- Keep each script on one CAD API. Conflicting imports, including mixed imports,
- are rejected against the project runtime before daemon startup or version
- creation, with guidance for fixing the script or intentionally overriding the
- runtime. Unpinned projects still detect the runtime and reject ambiguous scripts.
- Run responses identify the selection in `runtime_source` (`command`, `project`,
- or `detection`, which includes the default fallback). Run
- `agentcad docs runtimes` for the complete dispatch contract.
- ## MCP integration
- For native tool integration with Claude Code, Cursor, or Windsurf:
- ```bash
- pip install agentcad[mcp]
- ```
- Extras combine: `pip install "agentcad[mcp,cadquery]"` installs both.
- Add to `.mcp.json`:
- ```json
- {"agentcad": {"command": "python", "args": ["-m", "agentcad.mcp"]}}
- ```
- For local STEP/STP/BREP files, call `import_cad` with `file`, `cwd`, and
- `initialize=True` to start a project. Imports prepare typed geometry IDs,
- measurements and a compact inspection report by default. No Inspect opt-in is
- required. The default response includes the import
- JSON and up to nine inspection PNG attachments. Use `report_images=False` for
- an image-free report or `report=False` to keep the bundle on disk. Image
- attachments are delivered to the MCP client; how they appear to the user depends
- on the client. Follow the
- returned IDs and paths with `inspect` and `run`. Local paths refer to the MCP
- execution filesystem. See `agentcad docs mcp` for controls.
- For retry-safe imports, pass `idempotency_key="supplier-001"` (CLI:
- `agentcad import supplier.step --init --idempotency-key supplier-001`). Preserve
- the key and identical source/options after a lost response: retries return the
- original version without importing or opening the viewer again. A different
- source, label, runtime request, validation profile, report/image limits or
- viewer/diff options conflicts with that key. Explicit checks JSON content and
- `--defer-checks` must also match. Use a new key for an intentional
- new import. Keys are scoped to the selected build directory; the original file
- must remain readable with identical bytes.
- A contended retry waits up to ten seconds, then reports `in_progress` if the
- original process still owns execution; retry the same request later. A stopped
- process releases ownership automatically. Retrying recovers a committed version
- and marks unfinished artifacts interrupted, or explicitly reports that execution
- stopped before commit. Optional analysis is not automatically resumed. Saved
- responses describe the original attempt; use `inspect` for fresh inspection.
- When retrying from another project subdirectory, returned actions target the
- selected baseline from that caller directory. Inline detail/media may be trimmed
- further to keep the final report within its text budget; saved analysis and IDs
- stay unchanged. If required references cannot fit, `inspection_delivery` reports
- the omission and provides a retrieval action with a larger allowance.
- Deleting `.agentcad/import_requests` deletes retry protection for those keys.
- Imports return a durable `inspection_job` and wait for inspection by
- default. Use `--inspection-background` or `--inspection-wait-timeout SECONDS`
- to return before analysis finishes. A wait deadline leaves the worker running;
- follow the returned status/wait/resume/cancel actions. These wait controls do
- not change import retry identity. See [inspection jobs](docs/inspection-jobs.md)
- for CLI/MCP examples, checkpoints and cancellation behavior.
- Import and `inspect --report` default to a 2,000-estimated-token limit for the
- complete JSON response, with bounded image samples and a full-response retrieval
- action. `--full-response` opts out of whole-response compaction. Agents can supply `--context-window`, `--response-budget`,
- `--response-text-budget`, `--image-budget` and a caller-estimated
- `--vision-profile` to bound complete inspection delivery. Limited responses
- include a full saved response and an executable retrieval action. See
- [inspection budgets](docs/inspection-budgets.md) for estimates, CLI/MCP parity
- and the distinction between whole-response limits and report preparation.
- Saved response snapshots default to 30 days and 64 MiB per build root, with
- configurable limits and explicit expiry/eviction responses. Cleanup preserves
- geometry, issued IDs, import retry records and resumable jobs.
- Analysis, image sheets and completed job results also have shared
- [cache limits](docs/inspection-cache.md), defaulting to 30 days/512 MiB per build
- root. Resumable checkpoints remain protected; a full quota stops enrichment
- with a resume action while preserving the imported model.
- To retrieve the complete inventory without opening server-side files, call
- `inspect(artifact="manifest", file=..., cwd=...)` (CLI: `inspect FILE --artifact
- manifest`). Saved report/image paths and `artifact="baseline"` use the same
- bounded byte transfer, with checksums and copyable continuations. See
- [inspection artifacts](docs/inspection-artifacts.md). This works through the
- existing MCP tool connection; the separate `cloud_*` API is unchanged.
- ### Cloud projects
- For setup and a complete agent build-and-edit loop, see the
- [cloud workflow guide](docs/cloud-workflow.md).
- If your host supplies a hosted MCP URL, a supported agent can connect directly
- with the issued key pair, without installing AgentCAD locally. Call `cloud_help`
- for remote tools and explicit content uploads. The guide covers URL setup and
- retrieving private evidence through MCP.
- If your host has issued an AgentCAD API address and key pair, the same local
- MCP server also offers `cloud_run`, `cloud_import`, `cloud_measure`,
- `cloud_inspect`, `cloud_check_spec`, `cloud_render`, and `cloud_diff`. Project,
- job, and download tools support that workflow. Set `AGENTCAD_API_URL`,
- `AGENTCAD_KEY_ID`, and `AGENTCAD_KEY_SECRET` in the server process environment.
- Keep credentials in a password manager, outside project files and agent prompts.
- For the local cloud CLI, install
- `pip install 'agentcad[cloud]==0.8.0'` (also included in `agentcad[mcp]`),
- as shown in the guide above:
- ```bash
- agentcad cloud projects create --name Bracket
- agentcad cloud run PROJECT examples/cloud/bracket.py --label first
- agentcad cloud job PROJECT JOB --wait
- agentcad cloud measure PROJECT 1
- agentcad cloud inspect PROJECT 1 --summary
- agentcad cloud check-spec PROJECT 1 examples/cloud/spec.json
- agentcad cloud render PROJECT 1
- agentcad cloud download PROJECT iso.png --job RENDER_JOB --kind render
- ```
- Replace `PROJECT` and `JOB` with the returned IDs. Submissions return immediately;
- poll the same job until it completes. Keep its `idempotency_key` for an identical
- retry after a lost response. Upload an edited script with a new key and label to
- create another version, then compare with `agentcad cloud diff PROJECT 1 2`.
- Only the named script, STEP, or spec file is uploaded. No local project is needed.
- With matching client/host export support, `agentcad cloud export PROJECT VERSION
- --format stl,obj,glb` exports a saved whole model without rebuilding it. Poll
- that export job, read its per-format mesh validation, and download with
- `--kind stl`, `obj`, or `glb`. See the [export workflow](docs/cloud-workflow.md#export-a-saved-model)
- for availability, units, private retrieval, and limits.
- Downloads require an explicit destination and preserve existing files by default.
- Job completion, geometry validity, spec verdicts, and human approval remain
- separate. Run `agentcad docs cloud` for all commands, limits, and MCP tool names.
- Cloud access uses your host's installed CAD engine and credentials; it is not a
- hosted remote MCP endpoint or a general remote mode for local commands.
- ## Requirements
- - Python 3.10–3.12 (OpenCascade bindings do not support 3.13+)
- ## License
- Apache License 2.0. See [LICENSE](LICENSE).
- ## Feedback
- If your agent struggles, run `agentcad feedback "what happened"` to capture a friction log.
- For a detailed session report, create and fill in a guided feedback template:
- ```bash
- agentcad feedback --template --output feedback.md
- # Fill in the task, what happened, evidence, and any workaround.
- agentcad feedback --file feedback.md
- ```
- Creating a template sends nothing. Reports include recent session context;
- review what you send, or add `--local-only` to keep it local. Partial reports,
- positive feedback, and ideas are welcome. See `agentcad docs feedback` for
- file/stdin input and upload receipts.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.