# How to Set Up the Development Environment for text-to-cad: Complete Guide

> This guide shows you how to set up the development environment for text-to-cad. Follow simple steps to clone the repository, install dependencies, and get ready to code.

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

---

**TLDR:** Clone the `develop` branch of `earthtojake/text-to-cad`, create a Python 3.12 virtual environment, install Python dependencies via `pip install -r requirements-dev.txt`, install Node.js dependencies with `npm --prefix viewer install`, and run [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) to symlink skills into your local agent.

The **text-to-cad** repository is a monorepo that powers AI-driven CAD generation, containing Python-based skills, a TypeScript/React CAD viewer, and provider-specific plugins. Setting up the development environment requires configuring both Python and Node.js toolchains while establishing a symlink-based layout that maps generated outputs back to their canonical sources in `skills/` and `packages/`.

## Prerequisites

Before beginning, ensure you have the following installed:

- **Python 3.12** – Required for the virtual environment and skill execution
- **Node.js and npm** – Required for the CAD Viewer build system
- **Git** – To clone the `develop` branch which contains the development symlink layout

## Step-by-Step Installation

### Clone the Repository

Start by cloning the `develop` branch, which contains the development layout with symlinks. According to [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md), this branch uses a symlink layout so that generated files in `viewer/` and `plugins/` point back to their canonical sources.

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

```

### Configure the Python Environment

Create a dedicated virtual environment and install the development dependencies listed in [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt). This installs the core packages including `packages/cadpy` and `packages/cadpy_metadata`.

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

```

### Install CAD Viewer Dependencies

The CAD Viewer located in `viewer/` requires Node.js dependencies. Run the installation from the repository root using the `--prefix` flag:

```bash
npm --prefix viewer install

```

This pulls in dependencies for `packages/cadjs`, `packages/implicitjs`, and the React UI components.

### Link Skills to Your Local Agent

Use the [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) script to create symlinks from the repository's `skills/` directory into your local agent installation. The script scans `skills/` for [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) files and creates one symlink per skill.

```bash
scripts/install/install-skills.sh --agent codex   # or claude, universal, project

```

Supported destinations include Codex, Claude, or a project-local `.agents/skills` directory. The script leaves existing non-symlink files untouched to prevent overwriting production skills.

### Verify the Symlink Layout

Confirm that all generated paths correctly point back to canonical sources by running the verification script referenced in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md):

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

```

This validates that paths in `viewer/`, `plugins/`, and other directories properly reference their sources in `skills/` and `packages/`.

## Running Skills Locally

Execute skills directly using the virtual-environment-aware wrapper located at `.venv/skills/`. Each skill has its own interpreter entry point.

For example, to run the CAD skill:

```bash
./.venv/skills/cad/bin/python skills/cad/scripts/step \
    "Create a 50 mm × 30 mm × 10 mm rectangular block with a 5 mm radius fillet on all edges." \
    --output models/example/block.step

```

Replace `cad` with `urdf`, `gcode`, or other skill names located in the `skills/` directory.

## Starting the CAD Viewer

Launch the development server with hot-reload enabled:

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

```

Open the URL printed by Vite (typically `http://127.0.0.1:5173/`) and provide an absolute `?dir=` query parameter pointing to your repository's models directory:

```

http://127.0.0.1:5173/?dir=/absolute/path/to/text-to-cad/models&file=example/block.step

```

The Viewer will render STEP files generated by the skills and allow orbiting, slicing, and exporting.

## Testing Your Setup

Validate your environment against CI expectations by running the repository test suite:

```bash

# Run all checks

scripts/test/test.sh

# Verify symlinks specifically

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

# Viewer unit tests

npm --prefix viewer run test

# Python skill tests

./.venv/bin/python -m unittest tests/python/skills/cad/test_cli.py

```

## Summary

- Clone the **`develop`** branch to get the symlink-based development layout
- Install Python 3.12 dependencies via **[`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt)** into `.venv`
- Install Node.js dependencies with **`npm --prefix viewer install`**
- Link skills using **[`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh)** for your target agent
- Verify the setup with **`scripts/dev/setup-symlinks.sh --check`**
- Run skills via **`.venv/skills/{skill}/bin/python`** and view output in the CAD Viewer

## Frequently Asked Questions

### What Python version is required for text-to-cad development?

The repository requires **Python 3.12** specifically. Create the virtual environment using `python3.12 -m venv .venv` as shown in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) to ensure compatibility with the packages in `packages/cadpy` and related modules.

### Why must I clone the `develop` branch instead of `main`?

The `develop` branch contains a **symlink layout** that maps generated output files in `viewer/` and `plugins/` back to their canonical sources in `skills/` and `packages/`. This allows you to edit a single source file and have changes reflected across all generated outputs without manual copying.

### How do I install skills for multiple agents simultaneously?

Run the install script multiple times with different `--agent` flags, or use `--agent project` to install into the repository-local `.agents/skills` directory. As documented in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md), the script creates symlinks without overwriting existing non-symlink files, making it safe to link into multiple agent configurations.

### Can I test skills without installing a full agent?

Yes. Use the virtual-environment wrappers at `.venv/skills/{skill}/bin/python` to execute skill scripts directly. For example, run `./.venv/skills/cad/bin/python skills/cad/scripts/step --help` to test the CAD skill CLI without linking to Codex or Claude.