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

> Quickly set up the text-to-cad development environment from the develop branch. Clone the repo, install dependencies, and configure symlinks to start coding.

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

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) and [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```bash
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:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
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:

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

```

This script calls two internal helpers—[`setup-skill-symlink.sh`](https://github.com/earthtojake/text-to-cad/blob/main/setup-skill-symlink.sh) and [`setup-plugin-symlink.sh`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
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:

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

```

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

```bash
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:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) and [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.