cad

Files (16)

• LICENSE
• SKILL.md
• openai.yaml · agents/
• animation-deformation.md · references/
• build123d-modeling.md · references/
• cad-brief.md · references/
• inspection-and-validation.md · references/
• kinematics.md · references/
• migrations.md · references/
• positioning.md · references/
• project-layout.md · references/
• project-template.md · references/
• repair-loop.md · references/
• snapshot-review.md · references/
• step-generation.md · references/
• supported-exports.md · references/

SKILL.md (first lines)

# CAD modeling and inspection

Provenance: maintained in [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad).
Use the installed local skill files for the current interface.

A model is a Python function; running its script rebuilds it in cadgen's warm engine, and the
page the person has open updates. Files are exports, made when asked.

## Start with the task

| Task | Start with | Reference |
| --- | --- | --- |
| **Create or edit a part or assembly** | The project's model script, or a new one ([below](#write-a-model-and-run-it)). | [Models](references/model-contract.md), [build123d](references/build123d-modeling.md), [positioning](references/positioning.md) |
| **Organize a CAD project** | The project's existing layout. | [Project layout](references/project-layout.md) |
| **Export STEP, STL, 3MF, GLB or xbf** | `cadgen export <id> <file>`. | [Exports](references/exports.md) |
| **Use a vendor STEP, an xbf or a scan in a model** | `read_step`, `read_xbf` or `read_mesh` in the body. | [Inputs](references/model-contract.md#inputs) |
| **Resolve a reference from a prompt** | `cadgen inspect <id> '<ref>'`. | [References](references/inspection-and-validation.md#references) |
| **Measure or check geometry** | A check script that calls the model. | [Inspection](references/inspection-and-validation.md) |
| **See a model, a view or a pose** | `cadgen snapshot <id> out.png`. | [Snapshots](references/snapshot-review.md) |
| **Articulate a mechanism** | build123d joints in the body, then `cadgen.ap242`. | [Kinematics](references/kinematics.md) |
| **Explode, reveal or showcase a model** | `cadgen.gltf`'s `animation()` in the body. | [Animation](references/animation.md) |
| **Open an existing XBF, STEP/STP, STL, 3MF or GLB** | Show it to the user. | [Show the model](#show-the-model) |

A project built with cadgen 0.7 may need migrating: see [migrations](references/migrations.md).

For 2D DXF drawings use `$dxf`; this skill owns any 3D part the drawing projects.
Use the corresponding robot-description skill for URDF, SRDF or SDF.

## Setup and paths

Run cadgen through the `cadgen` command its installation writes, so this skill's commands
share one installation, and its engine server, with the CAD app's:

- `cadgen` below means `cadgen +0.8.1` (`~/.local/bin/cadgen +0.8.1` where `~/.local/bin` is not on your PATH)
- `python` below means `cadgen +0.8.1 run`

If `cadgen` is not on your PATH, or it says 0.8.1 is not installed, run
`uvx --no-config --managed-python --python 3.13 --from cadgen==0.8.1 cadgen doctor` once,
outside any sandbox or with its permission: it installs cadgen, registers it, writes the
`cadgen` command and starts the engine. With the CAD app's server running, nothing else
needs the sandbox's permission: it starts the engine and holds it. Without it, a sandboxed
shell cannot start the engine; when a command says no engine is running, run `cadgen server`
outside the sandbox once.

`cadgen doctor <skill-dir>` reports the installation in use, whether it is the one
this skill pins, whether the CAD kernel loads, and whether the engine is running, starting
it when none is. Each
command's `--help` lists its flags. The first launch downloads cadgen and may outlast a
host's server start timeout (Claude Code: 30 s by default, raised by setting `MCP_TIMEOUT` in
milliseconds; Codex: the plugin asks for 300 s); a restart resumes the download.

A project venv can put its own `cadgen` ahead of the launcher on PATH, even when
`~/.local/bin` is on PATH. Run `~/.local/bin/cadgen +0.8.1 doctor` to diagnose that
case and use that full launcher path for commands until PATH is corrected.

One engine serves the installation: the first run starts it, every run and every
command goes through it, and it serves the viewer. `cadgen status` lists its workers
and the documents it holds; `cadgen stop` stops it, and any older one left running.
A build cut off by the shell's time limit keeps running in the engine; run the same
command again and it waits for that build and replays it (`cadgen status` shows it).
Give a cold build of a large model the shell tool's longest timeout, or run it in the
background. A refused folder is another case: if a command ends with 'the system denies
cadgen's local engine', this shell's sandbox forbids the engine's folder itself: rerun it
with the sandbox's permission (in Codex, escalated permissions) rather than retrying.

Command-line paths, and the paths `read_step`, `read_xbf`, `read_mesh` and `export`
take, are relative to the working directory, as are a model's own file reads. Anchor
them on `__file__` in code that must run from any folder.

## Write a model and run it

A part or an assembly is a function with no parameters, decorated `@model` (or with its
file decorators, never both), that returns a build123d shape. Its dimensions are the
arguments of a plain helper function, and each configuration is a `@model` of its own, with
its own id and page; constants several models share live in a module they import. A call
builds it and returns its document: a handle with `.id`, `.url`, `.shape` (the built shape)
and `.export(...)`. For example, `src/bracket.py`:

```python
import build123d as bd
from cadgen import model


def bracket_body(width, thickness, bore):
    body = bd.Box(width, 20, thickness)
    hole = bd.Cylinder(bore / 2, thickness)
    body = body - hole
    body.label = "bracket"
    body.color = "#4a6fa5"
    return body


@model
def bracket():
    return bracket_body(40, 6, 8)


@model
def bracket_wide():
    return bracket_body(60, 6, 8)


if __name__ == "__main__":
    bracket()
    bracket_wide()
```

```bash
python src/bracket.py
```

```text
built src/bracket.py::bracket cold in 2.61s: bodies 1 run; 6 misses, 0 hits; body 0.01s, names 0.00s, document 0.00s
  parts 1 · bounds 40 × 20 × 6 mm · joints 0 · sequences 0
  id: 0dc50a92-a21f-5895-a245-ebdeb5352f3b
  view: http://127.0.0.1:54360/0dc50a92-a21f-5895-a245-ebdeb5352f3b?token=...
built src/bracket.py::bracket_wide warm in 0.01s: bodies 1 run; 6 misses, 0 hits; body 0.01s, names 0.00s, document 0.00s
  parts 1 · bounds 60 × 20 × 6 mm · joints 0 · sequences 0
  id: 966d03a5-7b43-5bed-b75c-eb67d56c72d2

From earthtojake/text-to-cad, MIT.

More from earthtojake/text-to-cad