Text-to-CAD Development Setup: Complete Guide for Modular CAD Workflows

Setting up the text-to-cad development environment requires cloning the repository, installing the shared Python package in editable mode, configuring symlinks via scripts/dev/setup-symlinks.sh, and optionally running the CAD Viewer for local previews.

The text-to-cad repository by earthtojake is a modular collection of agent skills for CAD, robotics, and fabrication workflows. This guide walks through the complete Text-to-CAD development setup, covering repository architecture, editable installs, and the symlink layout that keeps shared code synchronized across skills.

Understanding the Repository Architecture

The repository organizes code into distinct layers to separate concerns between reusable libraries, individual skills, and visualization tools.

Reusable Packages contain language-agnostic helpers for heavy lifting. These live under packages/ and include packages/cadpy/ (Python runtime), packages/cadjs/ (JavaScript rendering), and packages/implicitjs/ (browser-native implicit CAD).

Skills are self-contained agent capabilities exposing focused CLI or API endpoints. Each skill resides in skills/<skill>/ with a SKILL.md manifest describing its workflow and contracts. Examples include skills/cad/SKILL.md for generation and skills/urdf/SKILL.md for robot descriptions.

CAD Viewer is a lightweight web application at viewer/README.md that previews STEP, STL, GLB, URDF, SDF, SRDF, and G-code files. It imports shared JS packages to remain thin and reusable.

Scripts & Dev Tools in scripts/README.md provide build helpers and symlink management to maintain the correct develop worktree layout.

Prerequisites and Initial Setup

Begin by cloning the repository and creating a Python virtual environment for the cadpy package.

git clone https://github.com/earthtojake/text-to-cad.git
cd text-to-cad

python3 -m venv .venv
source .venv/bin/activate

Installing the Shared Python Package (cadpy)

Install the cadpy package in editable mode so changes in packages/cadpy/src/cadpy are instantly visible to importing skills.

./.venv/bin/python -m pip install -e packages/cadpy

This editable installation is essential for development, as documented in packages/cadpy/README.md. It ensures that any modification to the core geometry libraries immediately propagates to skills without reinstallation.

Configuring the Symlink Layout

The repository uses a custom script to link skills/*/scripts/packages/* directories to the actual source under packages/. This maintains a single source of truth for shared code.

Run the check command to verify the layout:

scripts/dev/setup-symlinks.sh --check

If symlinks are missing, the script will configure them automatically. This step ensures that skills reference the local development versions of cadpy and cadjs rather than bundled copies.

Installing Skills via the Skills CLI

Add skills to your agent using the Skills CLI, which pulls pre-bundled runtimes from the main branch.

npx skills install earthtojake/text-to-cad

This command registers the skill for agents like Codex or Claude Code. For local development of skill logic, you will typically invoke skills directly from the source rather than using the bundled version.

Running the CAD Viewer Locally

Start the viewer to preview generated models. The viewer requires an absolute path for the models directory.

npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models --shutdown-after 12h --json

The process exposes a JSON line reporting the chosen port and serves files from the specified directory. It supports STEP, STL, GLB, URDF, and other fabrication formats.

Development Workflow and Branch Strategy

According to AGENTS.md, development happens exclusively on the develop branch. The main branch contains pre-bundled outputs intended for end-users.

When contributing, create feature branches from develop and ensure skills remain compatible with the symlink layout. The develop branch maintains the live connections between skills/*/scripts/packages/* and packages/*/, whereas main contains static copies for distribution.

Practical Code Examples

Generating Geometry with cadpy

Create a rectangular block and export it to STEP format using the Python API.

from cadpy import cad
from cadpy.geometry import Box

# Create a 100 mm × 60 mm × 20 mm rectangular block

block = Box(100, 60, 20)

# Export to STEP (the default artifact format)

block.save("block.step")

Invoking the CAD Skill CLI

Generate an L-bracket with gussets using the command-line interface.

skills run cad "Create an L-bracket with two triangular gussets and a filleted base/back transition."

The skill writes output.step to the current directory and can trigger the viewer automatically.

Running the G-code Slicer

Slice an STL file for a specific printer. This requires a slicer executable on your system PATH.

skills run gcode "Slice the file block.stl for a Prusa i3 Mk3 printer."

The skill produces output.gcode and validates it against the slicer’s CLI output.

Previewing URDF in the Viewer

Generate a robotic arm description and view it in the local CAD Viewer.

skills run urdf "Generate a 6-DOF robotic arm with a gripper."

The skill writes robot.urdf and launches the viewer at:

http://127.0.0.1:4178/?dir=/absolute/path/to/models&file=robot.urdf

Summary

• The text-to-cad repository separates concerns into packages/ (shared libraries), skills/ (agent capabilities), and viewer/ (visualization).
• Install the Python runtime with pip install -e packages/cadpy to enable live development.
• Run scripts/dev/setup-symlinks.sh --check to ensure skills reference local package sources.
• Work on the develop branch; main contains frozen bundles for distribution.
• Use npx skills install to add skills to agents, or run skills run <skill> directly from source for testing.

Frequently Asked Questions

What is the difference between the develop and main branches?

The develop branch contains the live source code where active development occurs, including symlink connections between skills and shared packages. The main branch holds pre-bundled outputs intended for end-user installation via the Skills CLI, with all dependencies vendored.

How do I install the Python package for local development?

Navigate to the repository root, activate your virtual environment, and run pip install -e packages/cadpy. This editable installation mounts the source directory directly, allowing changes to packages/cadpy/src/cadpy to reflect immediately in running skills.

Why does the repository use symlinks, and how do I verify them?

Symlinks connect skills/*/scripts/packages/* to the canonical source in packages/, ensuring skills always use the latest shared code during development. Run scripts/dev/setup-symlinks.sh --check to verify the layout; the script will report any broken or missing links.

Can I use the CAD Viewer without installing any skills?

Yes. The CAD Viewer at viewer/README.md is an independent web application that only requires npm to run. It imports shared JavaScript packages from packages/cadjs/ and packages/implicitjs/ to render files, but does not require Python skills to be installed or configured.

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