Model with AI agents.

01 / The reference

Give your agent the language

Start with the short Pegmatite Script Guide, then let your agent fetch individual topics as needed. The public guide covers the language and verification workflow in small Markdown documents. The full download is optional.

• /guide/start.md The short starting guide. Give this to your agent first.
• /llms-full.txt All public guide topics in one optional download.
• /llms.txt An index linking directly to each guide topic and the available tools.

02 / Inspect with the CLI

Read measurements before rendering images

Use --check as the agent's primary inspection tool. It reports overall dimensions, individual part bounds, and labelled features' sizes and positions as text, so an agent can correct placement directly from measurements. Compare the report with the design, fix discrepancies and recheck before spending a round on images.

The Pegmatite CLI on npm requires Node.js 22 or newer. Run it with npx --yes pegmatite, or install it in your project with npm install pegmatite.

# Primary inspection: read the measurements and diagnostics
npx --yes pegmatite --check --strict model.pegm

# Fix discrepancies and repeat --check; export once validated
npx --yes pegmatite model.pegm

# Or export STEP for CAD programs, with OpenCascade beside the CLI
npx --yes -p pegmatite -p replicad-opencascadejs@1.1.0 pegmatite model.pegm -o model.step

--check builds the complete model without writing a file. The report goes to stdout: overall X × Y × Z dimensions in millimeters and part count, then labelled volumes' sizes, axis spans and source lines. In a script with parts, each part has its own material bounds and labelled rows. Label important features, including cutters; label a compound or macro call to inspect its result, since its inner labels are private. Avoid --quiet, which hides the report.

model.pegm  40 × 20 × 36 mm, 1 part
  base:  40 × 20 × 10  x -20..20  y -10..10  z 0..10   line 1
  post:  6 × 6 × 20    x -3..3    y -3..3    z 10..30  line 2
  cap:   12 × 12 × 6   x -6..6    y -6..6    z 30..36  line 3

Here the post begins at the base's top, Z = 10, and the cap begins at the post's top, Z = 30. Their X and Y spans show they are centered, and the stack ends at Z = 36. An agent can verify these dimensions and alignment without an image. Compare feature spans to check offsets, gaps and whether a cutter reaches across the intended thickness.

Diagnostics go to stderr with source locations. A subtraction that removes no material is a warning. --strict fails on warnings and can stop before printing the report; fix diagnostics and rerun. A material row shows bounds that differ from the placement slot. no material on a slot describes intentionally empty reference space, not a missed cut.

Read the values even when the command succeeds: an empty model can pass with zero parts. Unexpected part counts can flag disconnected material, but separate parts and color splitting also affect the count. The report does not list every disconnected positive feature, and overlapping bounds alone do not prove physical contact or a through-hole.

Use a preview for a remaining visual question

Images supplement the text checks. Render one when shape, hole openings, curved surfaces or appearance still need inspection. Choose a useful view and open the PNG; rendering alone is not inspection. Images are not required on every iteration.

# Optional: choose a view for a remaining visual question, then open the PNG
npx --yes pegmatite model.pegm -o model-top.png --view top

Views include iso (the default), top, front, back, left, right and bottom. PNG rendering needs no browser or GPU. See the CLI guide for report interpretation and the full validation loop.

03 / In a chat

Claude, ChatGPT and other assistants

An assistant that can browse reads the reference from its URL. Otherwise, download the file and attach it to the conversation. Then describe the part with its dimensions:

Read https://pegmatite.dev/guide/start.md, the short Pegmatite Script guide.
Fetch linked topics only when needed for this model.
Create sun-pendant.pegm: a sun pendant 40 mm across and 3 mm thick,
with a 3 mm hanging hole near the top. Keep the main dimensions as variables.

Use text inspection as the primary validation loop. With Node.js 22+:
npx --yes pegmatite --check --strict sun-pendant.pegm

Label the pendant and hole cutter. Read the report and diagnostics;
compare dimensions, part count and the hole's X/Y/Z spans with the design.
Check that the cutter spans the thickness. Fix warnings, errors and
measurement mismatches, then rerun --check before rendering.

If shape, hole openings or connected rays still need visual confirmation,
render a useful view and open it, for example:
npx --yes pegmatite sun-pendant.pegm -o sun-pendant-top.png --view top
Images supplement text checks; do not render every iteration by default.

After the relevant checks pass, export with:
npx --yes pegmatite sun-pendant.pegm

Return the script and 3MF, plus any previews used. Summarize the dimensions
and relationships verified and any remaining uncertainty. If the CLI or
a needed visual check is unavailable, state what remains unchecked and
provide the script for review in the editor.

If the assistant cannot run commands, run --check --strict yourself and share its report and diagnostics. You can also review the script in the editor and share a screenshot for a visual question.

04 / In a project

Claude Code, Cursor and other coding agents

Keep models as .pegm files in a repository, so the agent edits them in place and you review the changes like any other code. Save the reference next to them:

curl -o PEGMATITE.md https://pegmatite.dev/guide/start.md

Then point the agent at it from its instructions file, CLAUDE.md or AGENTS.md:

## 3D models

Models are written in Pegmatite Script (.pegm). Read PEGMATITE.md before
writing or editing a .pegm file. Follow its formatting paragraph and fetch
linked guide topics only when needed.

Prefer text inspection with the pegmatite npm CLI (Node.js 22+):
1. Label important features, including cutters. Record expected overall
   and per-part dimensions, positions, alignment, gaps and cutting depths.
2. Run npx --yes pegmatite --check --strict model.pegm. Read stdout and
   stderr; do not use --quiet. The report lists part bounds and labelled
   volumes' sizes, X/Y/Z spans and source lines.
3. Compare the report with the design. Fix errors, warnings and measurement
   mismatches, then recheck. A subtraction that removes no material warns;
   strict mode can stop before printing the report. Bounds alone do not
   prove contact or a through-hole.
4. For remaining visual questions, render a selected view and open it:
   npx --yes pegmatite model.pegm -o model-top.png --view top
   Use iso, front, back, left, right or bottom if more informative.
   Images are not required on every iteration. After corrections, recheck
   and rerender only when the visual question needs another look.
5. Export with npx --yes pegmatite model.pegm to create model.3mf.

Replace model.pegm with the actual path. Report measurements and
relationships checked, any views inspected, and remaining uncertainty.
If the CLI or a needed visual check is unavailable, say what is unchecked.

Download the file again to pick up new language features.

05 / The loop

Check, correct, preview if needed, export