# 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.

<p align="center">
  <img src="assets/primus.png" alt="Primus CLI in the terminal" />
</p>

## Install

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

```bash
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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md).

## 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:

```bash
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` - update Pi, Serena, build123d, and managed workshop dependencies
- `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 one question at a time, with a recommended answer for each question to make tradeoffs explicit. It walks the design tree branch-by-branch, resolves dependencies between decisions, and checks repository context first when a question is discoverable from existing artifacts. Ambiguities get surfaced and resolved before plan synthesis. 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](https://github.com/earendil-works/pi)** is the agent harness Primus runs on.

**[build123d](https://github.com/gumyr/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](https://github.com/oraios/serena)** gives Primus semantic code intelligence over the local build123d source tree. Instead of hallucinating API signatures.

**[Tavily](https://www.tavily.com/)** 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` issues:
  - If vendored `build123d` checkout is dirty, commit/stash/discard local changes first
  - To update Primus itself, run `npm install -g @shaurya-sethi/primus@latest`

## License

MIT. See [LICENSE](./LICENSE).