# How to Set Up a Development Environment for text-to-CAD: Complete Setup Guide

> Set up your text-to-CAD development environment easily. Clone the repo, install Python dependencies, configure the Node.js viewer, and link skills with this complete guide.

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

---

**To set up a development environment for text-to-CAD, clone the `develop` branch of earthtojake/text-to-cad, install Python 3.12 dependencies via [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt), configure the Node.js CAD Viewer, and link skills into your agent using [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh).**

The earthtojake/text-to-cad repository organizes its codebase into three distinct layers: core skill definitions under `skills/`, shared libraries under `packages/`, and a Vite-based CAD Viewer in `viewer/`. When you set up a development environment for text-to-CAD, you must work exclusively on the `develop` branch, which maintains a symlink layout that propagates edits from canonical source files to all generated runtime locations.

## Clone the Repository (Develop Branch Only)

Always clone the `develop` branch for local development work. The `main` branch is publish-only and lacks the symlink infrastructure required for editing.

```bash
git clone --branch develop https://github.com/earthtojake/text-to-cad.git
cd text-to-cad

```

The repository separates **core source code** (skills and packages) from **generated runtime assets** using symlinks. This architecture ensures that editing a single source file automatically updates every generated location that references it.

## Configure the Python Environment

The project requires Python 3.12 specifically. Create a virtual environment and install development dependencies that include the local `packages/` libraries.

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements-dev.txt

```

The [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt) file references the Python libraries located under `packages/` and installs minimal extra dependencies required for skill script execution.

## Install Node Dependencies for the CAD Viewer

The CAD Viewer application located in `viewer/` requires Node.js dependencies for local development. Install these once using the prefix flag to target the subdirectory.

```bash
npm --prefix viewer install

```

This installs the Vite-based build system configured in `viewer/vite.config.mjs`, which handles the viewer UI and STEP/STL/URDF file previewing.

## Link Skills into Your Agent

The repository includes a helper script that creates symlinks from your checkout into your agent's skill directory. This exposes the text-to-CAD capabilities to AI agents like Codex or Claude.

Run the installer for your specific agent:

```bash

# For a single agent

scripts/install/install-skills.sh --agent codex

# For multiple agents

scripts/install/install-skills.sh --agent codex --agent claude

```

The installer scans the `skills/` directory for [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) files and creates one symlink per skill found. To remove these links later, use `scripts/install/uninstall-skills.sh --agent codex`.

## Verify the Symlink Layout

Before running tests, validate that all generated-output paths correctly symlink back to their canonical sources in `skills/` and `packages/`.

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

```

This command serves as the first guard against configuration errors and ensures the develop-branch layout is intact.

## Run the Test Suite

Execute the full repository test suite to verify your environment setup:

```bash
scripts/test/test.sh

```

This script runs Python unit tests, Node tests for the viewer, and bundle sanity checks. For faster iteration during skill development, target individual skill tests directly:

```bash
.venv/bin/python -m unittest tests/python/skills/urdf/test_cli.py

```

## Launch the CAD Viewer in Development Mode

Start the Vite development server to preview generated CAD files:

```bash
npm --prefix viewer run dev -- --host 127.0.0.1

```

The server outputs a URL containing an absolute `?dir=` query parameter. Use this URL to preview STEP, STL, URDF, and other generated geometry files in real-time.

## Create Experimental Model Directories

When prototyping new geometry or robot descriptions, store files under the `models/` tree. This ensures CI validation can process your experiments:

```bash
mkdir -p models/experiments/my-test

```

Files in `models/` are treated as permanent fixtures or generated artifacts according to the repository's source boundary policies.

## Summary

- **Use the `develop` branch**: The symlink architecture only exists here; `main` is for publishing only.
- **Install Python 3.12**: Use [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt) to capture local `packages/` dependencies.
- **Link skills**: Run [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) to expose capabilities to your AI agent.
- **Verify setup**: Always run `scripts/dev/setup-symlinks.sh --check` before testing.
- **Test locally**: Use [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) for full validation or target specific skill unit tests.
- **Preview geometry**: Launch the CAD Viewer with `npm --prefix viewer run dev` to inspect generated files.

## Frequently Asked Questions

### Why must I use the develop branch instead of main?

The `develop` branch contains the symlink layout that connects generated runtime assets back to their canonical sources in `skills/` and `packages/`. The `main` branch is publish-only and lacks these symlinks, meaning changes to source files would not propagate to runtime locations where agents execute them.

### How do I uninstall skills from my agent?

Run `scripts/install/uninstall-skills.sh --agent codex` (substituting your agent name) to remove all symlinks created by the install script. This cleans up the skill references without deleting your local repository.

### Can I test a single skill without running the full suite?

Yes. While [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) runs the complete validation, you can target individual Python unit tests directly using the virtual environment's Python interpreter: `.venv/bin/python -m unittest tests/python/skills/urdf/test_cli.py`. This is useful for rapid iteration during skill development.

### Where should I save experimental CAD models?

Create subdirectories under `models/experiments/` for temporary work. The `models/` directory is designated for permanent fixtures and generated artifacts, ensuring that experimental files undergo CI validation and remain organized within the repository structure.