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

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 — 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.

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:

# 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:

# 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:

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 script creates a deterministic filesystem layout that keeps generated runtimes synchronized with source packages.

The top-level test harness at 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.

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 script maintains synchronization between source packages and generated runtimes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}