# Text-to-CAD Open Source Projects: Architecture and Implementation of the earthtojake/text-to-cad Workbench

> Explore the earthtojake/text-to-cad open source project. Learn how this text-to-CAD workbench converts natural language into STEP, STL, and GLB files using agentic agents and shared libraries.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: architecture
- Published: 2026-08-04

---

**The earthtojake/text-to-cad repository provides a modular, agentic framework that transforms natural language descriptions into production-ready CAD files (STEP, STL, GLB) through self-contained skills and shared geometry libraries.**

Text-to-CAD technology bridges large language models with computer-aided design, enabling automated generation of manufacturable geometry from plain text. The earthtojake/text-to-cad repository implements this paradigm as a collection of independent agent skills backed by reusable Python and JavaScript packages. This open-source workbench demonstrates how modern AI agents can interface directly with industrial fabrication pipelines.

## Modular Architecture for Text-to-CAD Pipelines

The repository follows a strict separation of concerns across five distinct layers. Each layer serves a specific function in the text-to-CAD pipeline, from natural language interpretation to final artifact visualization.

### Skill Definitions Layer

The `skills/` directory contains human-readable specifications and CLI entry-points for each capability. Skills such as `cad`, `urdf`, and `gcode` each maintain their own subdirectory with three core components:

- [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) — The public contract describing supported options and example prompts
- `scripts/` — Implementation logic (Python, Node, or shell) invoked by the skill CLI
- `references/` — Design notes, validation rules, and workflow diagrams

According to the source code, these skills are **self-contained** and never import code from sibling skills, respecting the repository rule that *"each skill must be independent at runtime."*

### Shared Runtime Libraries

The `packages/` directory houses language-agnostic helpers used by multiple skills. The two principal packages are:

- **`cadpy`** — A pure-Python library for generating STEP, STL, 3MF, and GLB files, handling mesh topology and material attributes. This powers the CAD, DXF, and G-code skills.
- **`cadjs` / `implicitjs`** — JavaScript runtimes exposing low-level CAD APIs including render pipelines and implicit-shape ray-marching for the browser viewer.

Both packages are version-controlled centrally and vendored into each skill at build time via [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh).

### Browser-Based CAD Viewer

Located in `viewer/`, the viewer is a **Vite-based SPA** that renders STEP, STL, GLB, G-code, URDF, SRDF, and SDF assets locally. It automatically detects file types and selects the appropriate runtime:

- STEP / STL / GLB → `packages/cadjs` renderer
- G-code → Dedicated preview component
- URDF / SRDF / SDF → 3-D robot visualizer with MoveIt2 move-group overlays

The viewer includes a lightweight HTTP server in `viewer/src/server/*.mjs` for rapid local hosting.

### Benchmarks and Assets

High-resolution GIFs and Markdown demos illustrating prompt-to-output examples reside in `benchmarks/` and `assets/`. These serve as both documentation and regression tests, stored under Git LFS to keep repository clones lightweight.

## CLI and API Usage Examples

The repository supports both CLI-driven agent workflows and direct programmatic integration.

### Command-Line Installation

Install and invoke skills using the `skills` CLI:

```bash

# Install the skill library (production)

npx skills install earthtojake/text-to-cad

# Run the CAD skill from the CLI

skills run cad "Create a 100 mm × 60 mm × 20 mm block with a 2 mm chamfer on the top edge"

# → Generates block.step (primary) and optional STL/GLB in the current folder

```

### Local Visualization

Preview generated artifacts without external tools:

```bash

# Preview the result locally with the viewer

npx skills run cad-viewer --dir "$(pwd)"

# Opens http://127.0.0.1:4178/?dir=<absolute-path> showing the newly created STEP model

```

### Direct Python API Integration

Access the geometry engine directly via `cadpy`:

```python
from cadpy import generate_step

geom = {
    "type": "box", 
    "size": [100, 60, 20], 
    "chamfer": {"faces": ["top"], "size": 2}
}
step_bytes = generate_step(geom)
open("block.step", "wb").write(step_bytes)

```

## Development and Testing Workflow

Development occurs on the `develop` branch, while `main` contains only generated production artifacts. The [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) script creates a deterministic filesystem layout that keeps generated runtimes synchronized with source packages.

The top-level test harness at [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) runs the full validation matrix covering JavaScript, Python, documentation, and global repository policies. This ensures that text-to-CAD outputs remain deterministic across all implementation layers.

## Summary

- The **earthtojake/text-to-cad** repository implements text-to-CAD as a modular skill-based architecture where each capability (CAD, URDF, G-code) remains self-contained in the `skills/` directory.
- **Shared libraries** in `packages/cadpy` and `packages/cadjs` provide deterministic geometry generation and browser-based rendering without cross-skill dependencies.
- The **Vite-based viewer** in `viewer/` supports industrial file formats including STEP, STL, G-code, and robotic descriptions (URDF/SRDF/SDF).
- All skills adhere to a strict runtime independence rule, consuming shared functionality only through vendored packages built by [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh).

## Frequently Asked Questions

### What file formats does the text-to-cad repository support?

The repository generates and manipulates STEP, STL, 3MF, and GLB for solid geometry; DXF for 2D drawings; and G-code for CNC machining. The viewer additionally renders URDF, SRDF, and SDF files for robotic simulation and motion planning.

### How does the skill architecture ensure reliability in text-to-CAD pipelines?

Each skill in the `skills/` directory is self-contained and prohibited from importing code from sibling skills. Shared functionality is centralized in `packages/` and vendored at build time, preventing cascade failures and ensuring that text-to-CAD generation remains deterministic and isolated.

### Can I use the text-to-cad library without the CLI tools?

Yes. The `cadpy` package exposes direct Python APIs such as `generate_step()` that accept geometry dictionaries and return file bytes. This allows integration into existing Python workflows without invoking the `skills` CLI wrapper.

### What branch should developers use for contributing to text-to-cad features?

Contributors should work on the `develop` branch, which contains the active source code. The `main` branch holds only generated outputs required for production installations, and the [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) script maintains synchronization between source packages and generated runtimes.