How to Set Up the Development Environment from the develop Branch in text-to-cad

To set up the development environment from the develop branch, clone the repository with --branch develop, install Python and Node dependencies, and run scripts/dev/setup-symlinks.sh to configure the symlink-driven layout that maps generated outputs back to editable source.

The earthtojake/text-to-cad repository uses a unique symlink-driven development architecture on the develop branch that keeps skills self-contained at runtime while allowing centralized editing. Unlike the main branch which contains production bundles, develop separates canonical source code (in skills/, viewer/, and packages/) from runtime artifacts, requiring a specific setup script to wire everything together. This guide walks through the exact steps documented in CONTRIBUTING.md and AGENTS.md to create a functional local workspace.

Clone the develop Branch

Start by cloning the specific branch that contains the editable source code and development tooling.

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

The develop branch serves as the source of truth for all ongoing work, and all pull requests must target this branch rather than main. The main branch contains compiled production outputs that are unsuitable for development.

Configure Python and Node Environments

This repository contains both Python backend logic and a Node.js-based CAD Viewer frontend, requiring dual environment setup.

Create the Python Virtual Environment

The Python code lives under packages/ and various skill directories. Use Python 3.12 to create a virtual environment and install development dependencies:

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

The requirements-dev.txt file installs shared packages from packages/cadpy* and any skill-specific extras needed for local development.

Install CAD Viewer Dependencies

The CAD Viewer frontend resides in the viewer/ directory and requires npm packages:

npm --prefix viewer install

This step prepares the Viewer build tooling, which is separate from the Python runtime but necessary for full-stack development.

Set Up the Symlink Development Layout

The symlink layout is the critical difference between develop and main. On develop, you must replace production bundle paths with symlinks pointing back to canonical sources using the repository's orchestration script:

scripts/dev/setup-symlinks.sh

This script calls two internal helpers—setup-skill-symlink.sh and setup-plugin-symlink.sh—to remap directories so that edits in skills/ and packages/ are immediately reflected in runtime locations. To verify the current state without making changes, add the --check flag:

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

This layout satisfies the repository requirement that each skill remains self-contained at runtime while avoiding code duplication between source and distribution directories.

Link Skills into Your Local Agent (Optional)

For rapid iteration with AI agents like Codex, Claude, or Gemini, symlink the skill directories directly into your local agent's runtime:

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

To see available agent targets and their destination paths, run:

scripts/install/install-skills.sh --list-agents

This creates live links from the repository's skills/ directory into your agent's execution environment, allowing immediate testing of changes without reinstallation.

Validate Your Development Setup

Run the repository's validation suite to confirm that symlinks, Python imports, and Viewer builds are correctly configured:

scripts/dev/setup-symlinks.sh --check
scripts/test/test.sh
npm --prefix viewer run test

Successful execution confirms that the symlink layout bridges source and runtime locations properly, the Python environment resolves packages/ imports, and the Node build pipeline is functional.

Summary

• Clone specifically from develop: The main branch contains production bundles unsuitable for editing; always use git clone --branch develop.
• Run the symlink script: Execute scripts/dev/setup-symlinks.sh to map skills/, viewer/, and packages/ into their runtime locations.
• Use Python 3.12: Create a virtual environment and install requirements-dev.txt for the backend tooling.
• Install Viewer dependencies: Run npm --prefix viewer install to prepare the frontend build system.
• Validate before coding: Use --check flags and the test suite to verify the symlink layout and dependency resolution.

Frequently Asked Questions

What is the difference between the main and develop branches?

The main branch contains generated production outputs and compiled bundles, while the develop branch contains the canonical editable source code under skills/, viewer/, and packages/. Working on develop requires running scripts/dev/setup-symlinks.sh to replace production paths with symlinks back to source files, enabling live editing without code duplication.

Why does the develop branch use symlinks?

The symlink-driven layout enforces the repository's architectural rule that each skill must be self-contained at runtime while keeping source code centralized. According to AGENTS.md and CONTRIBUTING.md, this approach allows the runtime to see skills as independent units while developers edit them in a single canonical location, preventing drift between source and distribution files.

Can I use a different Python version than 3.12?

The repository documentation specifies Python 3.12 for the virtual environment setup. While other versions may function, the requirements-dev.txt and package configurations in packages/ are tested and validated against Python 3.12, making it the recommended version for consistent development.

How do I unlink skills from my agent?

Re-run the installation script with the appropriate agent flag to refresh or remove links, or manually delete the symlinks created by scripts/install/install-skills.sh in your agent's skill directory. The --list-agents flag shows where skills are currently linked for each supported agent.

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