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

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, configure the Node.js CAD Viewer, and link skills into your agent using 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.

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.

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

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:

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

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:

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:

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

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:

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 to capture local packages/ dependencies.
• Link skills: Run 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 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 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.

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