How to Run text-to-cad on Linux, macOS, and Windows: Complete Setup Guide

To run text-to-cad on any operating system, install Node.js ≥16 and Python 3.9+, clone the earthtojake/text-to-cad repository, create a Python virtual environment, install dependencies with pip install -r requirements-dev.txt and npm ci, then register the skill with npx skills add earthtojake/text-to-cad and launch with skills run cad.

text-to-cad is an open-source collection of agent skill packages that generate, inspect, and visualize CAD geometry from natural language prompts. This guide explains how to run text-to-cad on different operating systems using the repository's hybrid Python and Node.js runtime architecture.

Prerequisites for All Platforms

Before installing text-to-cad, ensure your system meets these requirements:

• Node.js LTS (version 16 or higher)
• Python 3.9+ with venv module support
• Git for cloning the repository

The repository combines a Python backend for geometric computation with a Node.js frontend for the CAD viewer interface.

Installing text-to-cad on Linux and macOS

POSIX systems use similar terminal commands for setup. The installation process relies on the scripts/install/install-skills.sh helper to register skills with the CLI.

1. Clone the repository:

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

2. Create and activate a Python virtual environment:

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

3. Install Python dependencies:

pip install -r requirements-dev.txt

This file pins the correct cadgen version required by the packages/cadgen runtime.

4. Install Node dependencies:

npm ci

This command installs the JavaScript CAD library located in packages/cadgen-js/ and ensures a reproducible Node environment as documented in packages/cadgen-js/README.md.

5. Register the skill with the Skills CLI:

npx skills add earthtojake/text-to-cad

6. Launch a CAD generation task:

skills run cad "cube size=10"

This command spawns the cadgen.viewer backend and opens http://localhost:3000 in your default browser.

Installing text-to-cad on Windows

Windows installation follows the same logical steps but uses PowerShell syntax for path handling and virtual environment activation.

1. Clone the repository:

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

2. Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

3. Install Python and Node dependencies:

pip install -r requirements-dev.txt
npm ci

4. Register and run the skill:

npx skills add earthtojake/text-to-cad
skills run cad "cylinder radius=5 height=20"

The viewer backend starts automatically and launches your browser to the local interface.

Alternative Installation via AI Agent Plugins

If you use Codex, Claude, or Grok instead of the standalone Skills CLI, install text-to-cad using these platform-specific commands. All methods ultimately register the same skill definitions found in the repository's skill package.

Codex Plugin Installation

codex plugin marketplace add earthtojake/text-to-cad
codex plugin add cad@text-to-cad

Claude Plugin Installation

claude plugin marketplace add earthtojake/text-to-cad
claude plugin install cad@text-to-cad

Grok Plugin Installation

grok plugin install earthtojake/text-to-cad --trust

After installation through any plugin, invoke skills using the standard skills run cad "your prompt here" syntax.

Running CAD Generation Commands

Once installed, use the skills run command to generate geometry. The system processes natural language through the Python runtime in packages/cadgen/ and renders results via the viewer application in apps/viewer/.

Create a 3D box with specific dimensions:

skills run cad "box width=15 height=5 depth=8"

Export a model to GLB format:

skills run cad "box width=10 height=2 depth=4 export=glb"

This writes output.glb to your current working directory using the export functionality defined in the CAD generation pipeline.

Generate a DXF mesh with layers:

skills run dxf "circle radius=4 layers=top,bottom"

Understanding the Repository Structure

Key files and directories referenced during installation:

• requirements-dev.txt – Pins Python dependencies including the cadgen package version required for geometric operations
• packages/cadgen/README.md – Documents the Python + Node hybrid runtime architecture
• packages/cadgen-js/README.md – Describes the JavaScript CAD renderer and geometry library
• scripts/install/install-skills.sh – Automates skill registration with the local CLI
• apps/viewer/README.md – Contains instructions for launching the CAD Viewer backend and client interface

The cadgen.viewer module mentioned in the raw analysis serves as the bridge between the Python geometry engine and the browser-based visualization interface.

Summary

• Install Node.js ≥16 and Python 3.9+ before attempting setup on any OS
• Use source .venv/bin/activate on Linux/macOS or .\.venv\Scripts\Activate.ps1 on Windows to activate the Python environment
• Install dependencies via pip install -r requirements-dev.txt and npm ci to satisfy both runtime requirements
• Register the skill using npx skills add earthtojake/text-to-cad or equivalent plugin commands for Codex, Claude, or Grok
• Launch generation with skills run cad "your description" to automatically start the backend viewer at localhost:3000
• Generated files export to your current directory when using the export=glb or similar parameters

Frequently Asked Questions

What are the exact Node.js and Python version requirements for text-to-cad?

text-to-cad requires Node.js LTS version 16 or higher and Python 3.9 or newer with the venv module available. These versions ensure compatibility with the packages/cadgen-js JavaScript library and the Python geometric computation backend. Earlier versions may fail during the npm ci or pip install steps due to dependency conflicts.

Can I run text-to-cad on Windows without using PowerShell?

Yes, you can use Git Bash or the standard Command Prompt (cmd.exe) instead of PowerShell. In Git Bash, use the same POSIX commands as Linux (source .venv/bin/activate). In Command Prompt, activate the virtual environment with .venv\Scripts\activate.bat instead of the PowerShell script. The npx and skills commands function identically across all Windows shell environments.

How do I uninstall the text-to-cad skill from my system?

Run the uninstall script provided in the repository or use the reverse of your installation method. For Skills CLI installations, execute npx skills remove earthtojake/text-to-cad. If you used the scripts/install/install-skills.sh helper during setup, the companion scripts/install/uninstall-skills.sh script removes all registered skills and cleans up local cache directories.

Where does text-to-cad store generated CAD files?

By default, exported files write to your current working directory where you executed the skills run command. When you include export=glb or similar parameters in your prompt, the Python backend in packages/cadgen/ handles file I/O and saves outputs relative to the shell's active directory. The viewer interface at localhost:3000 displays previews but does not permanently store geometry unless you explicitly export.

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