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

> Set up your text-to-CAD development environment. Follow this guide to clone the repo, install packages, configure symlinks, and enable local CAD previews for modular workflows.

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

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) for generation and [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) for robot descriptions.

**CAD Viewer** is a lightweight web application at [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```bash
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.

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

```

This editable installation is essential for development, as documented in [`packages/cadpy/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
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.

```bash
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.

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```python
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.

```bash
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.

```bash
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.

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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.