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

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 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, this branch uses a symlink layout so that generated files in viewer/ and plugins/ point back to their canonical sources.

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. This installs the core packages including packages/cadpy and packages/cadpy_metadata.

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:

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 script to create symlinks from the repository's skills/ directory into your local agent installation. The script scans skills/ for SKILL.md files and creates one symlink per skill.

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:

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:

./.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:

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:

# 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 into .venv
• Install Node.js dependencies with npm --prefix viewer install
• Link skills using 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 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, 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.

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