How to Build text-to-CAD from Source: Complete Developer Guide

Building text-to-CAD from source requires Python 3.11+, Node.js 14+, and executing the repository's automation scripts to compile JavaScript packages, generate Python wheels, and bundle runtime artifacts for the Skills CLI.

The earthtojake/text-to-CAD repository is a multimodal CAD generation toolkit that combines Python backends with JavaScript frontends. When you build text-to-CAD from source, you assemble the cadpy libraries, cadjs runtime, and Viewer UI into deployable skill bundles. The official build process uses repository-specific scripts documented in AGENTS.md and CONTRIBUTING.md to ensure consistent compilation across environments.

Prerequisites

Before building, ensure your system meets these requirements:

• Python 3.11 or higher for the cadpy and cadpy_metadata packages
• Node.js 14 or higher for the JavaScript CAD runtime
• Git for cloning the monorepo structure
• Bash for running the build automation scripts

The repository organizes code into packages/ (shared libraries) and skills/ (deployable agents), requiring coordinated builds across both Python and JavaScript ecosystems.

Step-by-Step Build Instructions

1. Clone the Repository

Retrieve the source tree including all submodules and package definitions:

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

2. Create a Python Virtual Environment

Isolate the Python dependencies to avoid conflicts with system packages:

python3 -m venv .venv
source .venv/bin/activate

On Windows, use .venv\Scripts\activate instead.

3. Install Python Development Dependencies

Install the core CAD helpers and testing tools specified in requirements-dev.txt:

pip install -r requirements-dev.txt

This installs the cadpy package and metadata handlers located in packages/cadpy/.

4. Install JavaScript Dependencies

Install Node packages for the shared libraries and Viewer UI. The repository uses path-prefixed npm commands to target specific monorepo locations:

npm --prefix packages/cadjs install
npm --prefix packages/implicitjs install
npm --prefix viewer install

These commands populate node_modules for the CAD runtime (cadjs), implicit geometry library (implicitjs), and the web-based Viewer.

5. Build the Runtime Bundles

Execute the master bundler to compile TypeScript, generate type stubs, and prepare distribution artifacts:

scripts/bundle/bundle.sh

According to the repository's AGENTS.md, this script compiles the JS packages, copies generated artifacts into each skill's dist/ folder, and updates version stamps. It produces the runtime bundles that the Skills CLI expects when loading local skills.

6. Verify Development Symlinks (Develop Branch Only)

If working on the develop branch, ensure symlinks point to true source files for local editing:

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

As noted in CONTRIBUTING.md, this verification step is required for development workflows but optional when building from main.

7. Run the Repository Tests

Validate the build by executing the unified test harness:

scripts/test/test.sh

This script runs both Python and JavaScript test suites, confirming that cadpy imports resolve correctly and that the bundled JavaScript executes without runtime errors.

8. Install the Built Skills Locally

Register the freshly compiled library with the Skills CLI:

npx skills install .

This makes the local text-to-cad build available to agent runtimes for immediate testing.

9. Launch the CAD Viewer (Optional)

Start the web-based viewer to inspect generated models:

npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models

The viewer serves the UI on localhost and watches the models/ directory for CAD files generated by the skills.

Key Build Scripts Explained

Understanding these automation scripts helps debug build failures:

• scripts/bundle/bundle.sh: The canonical build orchestrator that traverses packages/, runs npm run build where appropriate, and aggregates outputs into skills/*/dist/ directories. It handles TypeScript compilation, wheel generation, and artifact staging.

• scripts/dev/setup-symlinks.sh: Manages the symlink layout required by the develop branch. It ensures that Python imports resolve to the source files in packages/cadpy/ rather than installed site-packages, enabling live editing without reinstallation.

• scripts/test/test.sh: A unified test runner that executes pytest for Python components and npm test for JavaScript packages, providing a single verification command for the entire codebase.

Summary

To successfully build text-to-CAD from source:

• Install Python 3.11+ and Node.js 14+ before starting
• Use requirements-dev.txt for Python dependencies and path-prefixed npm install for JavaScript packages
• Run scripts/bundle/bundle.sh to generate the compiled artifacts required by the Skills CLI
• Execute scripts/test/test.sh to verify the build integrity across Python and JavaScript
• Install locally with npx skills install . to activate the development build

Frequently Asked Questions

What are the minimum system requirements to build text-to-CAD?

You need Python 3.11 or higher and Node.js 14 or higher installed on your system. The build process creates Python wheels for the cadpy package and compiles TypeScript in the cadjs and implicitjs packages, requiring both interpreters to be available in your PATH.

What does the bundle.sh script actually compile?

The scripts/bundle/bundle.sh script performs the repository-wide compilation step. It builds the JavaScript packages (cadjs, implicitjs), generates Python type stubs, creates wheel distributions for cadpy, and copies all generated artifacts into each skill's dist/ directory. This bundling step is essential because the Skills CLI expects compiled assets in specific locations rather than raw source files.

Do I need to run setup-symlinks.sh when building from the main branch?

No. The scripts/dev/setup-symlinks.sh script is only required when working on the develop branch to maintain symlink consistency for local development. If you are building a stable release from main, you can skip this step and proceed directly to scripts/test/test.sh after bundling.

How can I verify that the build completed successfully?

Run scripts/test/test.sh to execute the full test suite covering both Python unit tests and JavaScript integration tests. Additionally, running npx skills install . should complete without errors, and launching npm --prefix viewer run serve should start the CAD Viewer without module resolution failures.

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