Primus

Primus is a standalone CLI for agent-driven parametric CAD generation. It wraps Pi with a managed build123d workshop so first-time setup and day-to-day CAD workflows run from one command surface.

Install

npm install -g @shaurya-sethi/primus

Prerequisites

• Node.js 20.19.0 through 24.x
• git on PATH
• Python 3.11-3.14 on PATH
  • macOS/Linux launchers: python3.11-python3.14 or python
  • Windows launchers: py -3.11-py -3.14, python3.11-python3.14, or python
• Internet access during setup (clones build123d, installs managed tools/packages)

First-Time Setup

primus setup

primus setup:

• validates Node/Git/Python prerequisites
• creates managed venv at ~/.primus/workspace/.venv
• clones build123d to ~/.primus/workspace/vendor/build123d
• installs managed Python deps (build123d, pytest, ocp-vscode)
• installs/verifies managed uv, serena-agent, and tavily-cli
• indexes workspace with Serena
• writes MCP config to ~/.primus/agent/mcp.json

First run can take several minutes while Serena indexes.

LLM Providers

Primus needs an LLM to run. Use /login inside a session to authenticate with a subscription or store an API key:

• Claude Pro/Max — Anthropic subscription
• ChatGPT Plus/Pro — OpenAI Codex
• GitHub Copilot — Copilot subscription

You can also configure any supported provider via environment variables (e.g. ANTHROPIC_API_KEY=sk-ant-...) before launching. For the full list of providers, API key env vars, and advanced auth options see the Pi providers docs.

Core Usage

Primus must be run from a project directory — do not run it from your home directory or any other generic location. Each directory you run Primus from becomes its own design workspace.

For the very first launch in a new project directory, run /init inside the session to scaffold the repo layout and initialise git:

mkdir my-cad-project && cd my-cad-project
primus
# then inside the session:
# /init

Subsequent launches in the same directory pick up where you left off.

Launch entrypoints:

• primus starts Primus CAD workshop
• primus design <description> starts goal-alignment flow via /design
• primus modify <description> starts modify flow via /modify

If launch reports machine is not ready, run primus setup first.

Commands

• primus setup - bootstrap or repair managed workshop
• primus doctor - run environment/runtime diagnostics
• primus update - self-upgrade global install, then refresh managed workshop
• primus preview <script> [expression] - push model preview to ocp-vscode viewer
• primus help or primus --help - command help
• primus --version - installed version

How It Works

Primus isn't a thin prompt wrapper. Every design session follows a deliberate four-stage workflow backed by purpose-built skills, specialist subagents, state management, and a set of tools that each cover a distinct slice of the problem.

Four-stage design workflow

Stage 1 — Goal Alignment (cad-goal-alignment skill) is where Primus pins down exactly what you want before touching any code. Rather than accepting a vague one-liner and guessing the rest, Primus runs a relentless structured interview — adaptive batches of 2–4 targeted questions covering shape and function, dimensions and tolerances, what should be parametric, and what the output format needs to be. Ambiguities get surfaced and resolved one at a time. The stage only closes when both sides agree on an approved plan.

Stage 2 — Research (build123d-research skill) turns the approved plan into actionable implementation knowledge. Primus spawns specialist subagents to inspect the local build123d source and optionally gather domain knowledge from the web. Findings are synthesized into a structured implementation brief that covers exactly which classes and functions to use, which patterns fit the geometry, and what pitfalls to avoid — so the authoring stage starts from verified knowledge rather than guesswork.

Stage 3 — Script Authoring (cad-script-authoring skill) is where the model actually gets written. Primus — and only Primus as the orchestrator — authors the final generator script and its verification suite. Tests run before the stage closes. The orchestrator can draw on the research brief, the source research artifacts, and its own long-term memory of the session to write the script, but it doesn't have to do it all in one go: if it hits a gap in knowledge or needs to verify something during authoring, it can spin up more research subagents on the fly, without losing context or momentum.

Stage 4 — Review Loop (cad-review-loop skill) runs a dedicated cad-reviewer subagent that checks the script against the plan, verifies API usage against build123d source, and audits the test suite. The orchestrator applies fixes and can request a second pass for substantial edits. The workflow only completes after the review clears and a live ocp-vscode preview handoff succeeds.

Toolchain

Pi is the agent harness Primus runs on.

build123d is the Python CAD programming library that generates the actual 3D geometry. Primus manages a dedicated Python venv with build123d installed, writes parametric generator scripts against its API, and exports finished models as STEP or STL files.

Serena MCP gives Primus semantic code intelligence over the local build123d source tree. Instead of hallucinating API signatures.

Tavily handles domain-specific research — manufacturing tolerances, standard dimensions, material properties, and anything else that lives outside the build123d source. It's intentionally narrow in scope: Serena covers the code, Tavily covers the domain knowledge that code can't answer.

Multi-agent orchestration

Primus keeps itself as the sole writer of scripts and tests. Specialist subagents — build123d-source-scout for Serena-backed source research, domain-research-worker for Tavily-backed domain knowledge, and cad-reviewer for post-authoring critique — each run inside a tight, narrowly scoped task and write only to their designated directories. This matters for two reasons: it prevents conflicting writes to the working tree, and it preserves the orchestrator's reasoning quality across long sessions by offloading deep, narrow work to agents that start fresh, do one thing, and return a structured artifact. The orchestrator never loses its own context window to sub-problems it can safely delegate.

Version-controlled design artifacts

Every stage transition commits to git. The approved plan, research artifacts, generator scripts, tests, and review logs are all tracked — giving you a full audit trail, the ability to roll back to any point in the workflow, and clean branch isolation if you want to explore a design variant without disturbing earlier work.

Platform Notes

I've done extensive end-to-end testing on macOS and Linux — install, setup, and full design workflows all run smoothly there. Windows has seen only limited testing, so expect rough edges; if you hit something, please open an issue.

CI runs npm run typecheck, npm test, and npm pack --dry-run against ubuntu-latest, macos-latest, and windows-latest on every push, so the package itself stays installable across all three — it's the runtime workflow on Windows where gaps may still exist.

Troubleshooting

• Primus not ready on this machine:
  • Run primus setup, then primus doctor
• Tavily auth failure during setup/doctor:
  • Set TAVILY_API_KEY=tvly-..., or run tvly login, then rerun setup/doctor
• Python prerequisite failure:
  • Install Python 3.11-3.14, ensure launcher is on PATH, rerun setup
• primus update refused:
  • Update only supports global npm install mode (npm install -g @shaurya-sethi/primus)
  • If vendored build123d checkout is dirty, commit/stash/discard local changes first

License

MIT. See LICENSE.