AgentSCAD

English | 中文

---

AgentSCAD is a local-first, open-source AI parametric CAD workspace. Built like a precision metrology instrument bench, it features a full-bleed 3D viewport and floating instrument modules. Type a single natural-language sentence to generate editable OpenSCAD code, real-time 3D rendered geometry, deterministic physical validation metrics, and 3D-printable STL artifacts.

Live Demo: https://agentscad.vercel.app

---

📸 Overview

Precision Metrology Instrument Design:

• Full-Bleed 3D Viewport: Immersive real-time WebGL rendering with zero docked-sidebar clutter.
• Floating Instrument Modules: Draggable, collapsible plates for parameter steppers, manufacturing checks, and physical readouts.
• Solid 56px ViewCube: 26 clickable standard orientation zones (faces, edges, corners) mirroring camera rotation.
• Single Centred Composer: One unified prompt field with one dominant action (Generate, Rebuild, or Stop).

---

⚡ Quick Start (3 Minutes)

1. Launch AgentSCAD

Run locally using Bun or Docker Compose:

# Clone the repository
git clone https://github.com/Kevoyuan/AgentSCAD.git
cd AgentSCAD

# Install dependencies and initialize SQLite schema
bun install
bun run db:push

# Start the dev server
bun run dev

Or using Docker Compose:

cp .env.example .env
docker compose up --build

Open http://localhost:3000 in your browser.

2. Configure Your LLM Provider

Click the Settings gear (⚙️) in the top-left status module:

• Select a preset (e.g. DeepSeek, OpenAI, OpenRouter, Anthropic, Gemini, or local models).
• Paste your API key, click Test, then click Save.
• Keys are saved locally in .agentscad/ or in encrypted browser-session cookies.

3. Generate Your First CAD Model

Type your part description in the bottom input bar:

Create a wall-mountable phone holder with rounded corners and two screw holes.

Press ⌘ Enter (or click the orange circle button ↑). AgentSCAD automatically:

1. Understands Intent: Extracts dimensions, tolerances, and mechanical constraints;
2. Generates OpenSCAD Code: Matches your request against a local alias index — Chinese and English alike — then injects ranked reference examples, design patterns, and known failure modes before writing parametric OpenSCAD source;
3. Renders Real Geometry: Invokes OpenSCAD (Native CLI or pinned WebAssembly) to generate mesh & STL;
4. Performs Deterministic Checks: Validates manifoldness, minimum wall thickness, and outer bounds.

---

🎯 Key Capabilities

1. Instant Parameter Tuning (Steppers)

Once generated, the right floating module exposes extracted dimensions. Increment or decrement parameters (wall thickness, hole diameter, width/height) and rebuild instantly:

Parameter Tuning (调参)	Focus View (看模型)

2. Intent Disambiguation ("Needs Decision")

When a natural language description contains mechanical ambiguity, AgentSCAD halts before rendering and presents options for you to decide, ensuring engineering precision:

3. Fast New Design Creator (⌘ N)

Click ＋ New Design on the rail to open the quick composer, with built-in material, manufacturing, and tolerance presets:

---

⌨️ Keyboard Shortcuts

Shortcut	Action
⌘ Enter	Submit prompt / Rebuild model
Space	Toggle all floating modules (instant switch to clean 3D focus view)
⌘ N	Create a new design
1 – 6	Standard views: Front (1), Right (2), Top (3), Back (4), Left (5), Bottom (6)
0	Default isometric view
F	Fit model to viewport
⌘ K	Open command palette

---

🛠️ Architecture & Principles

AgentSCAD strictly follows: "LLMs write code; deterministic tools govern geometry facts."

• OpenSCAD Geometry Authority: Native OpenSCAD CLI for local development; pinned official OpenSCAD WebAssembly (WASM) runtime for zero-install serverless setups.
• Measurable Physical Checks: Python / Trimesh inspects actual STL geometry for manifold topology, bounding boxes, wall thickness, and hole connectivity.
• Deterministic Retrieval: cad_knowledge/retrieval-index.json is the source of truth for what retrieval can match. Requests and aliases are normalized (case, full-width forms, punctuation), scored by strong/supporting alias weight and specificity, ranked deterministically, and cut to a per-group budget. Hard negatives keep near-miss families apart — a planetary gearbox never matches the spur-gear entry. Unmatched requests receive no examples rather than order-by-filename noise. It is lexical, not semantic: there is no embedding index, and none is claimed.
• Separate Evidence Levels: DELIVERED proves the artifacts exist, not that you accepted the part. An append-only JobOutcome ledger records accepted, rejected, user_edited, and exported events, and the summary only reports taskSucceeded when the most recent decision is accepted. Edits and exports are process signals, never success. Read it at GET /api/jobs/{id}/outcome.
• Local-First Persistence: SQLite stores Job records, JobVersion history, and the append-only JobOutcome ledger locally; artifacts are saved directly on disk with complete export capabilities.

---

📋 Common Commands

Task	Command
Dev server	bun run dev
Build for production	bun run build
Start production server	bun run start
Unit tests	bun run test
Test WASM runtime	bun run test:wasm
Push database schema	bun run db:push
Reset database	bun run db:reset
Run CAD eval benchmark	bun run cad:eval:fast

---

📚 Deeper Documentation

• Architecture
• Skills and Routing
• Memory and Outcomes
• Development and CI
• Benchmarking
• OpenSCAD Runtime & Libraries
• Design System (DESIGN.md)
• Changelog

---

📄 License

Distributed under the MIT License.