# Develop from source

> Monorepo workspaces, build and check scripts, package boundaries (ai, agent, coding-agent, tui), and contributor conventions from AGENTS.md.

- Repository: PrimeIntellect-ai/prime-agent
- GitHub: https://github.com/PrimeIntellect-ai/prime-agent
- Human docs: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1
- Complete Markdown: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1/llms-full.txt

## Source Files

- `package.json`
- `AGENTS.md`
- `packages/coding-agent/README.md`
- `packages/agent/README.md`
- `packages/ai/README.md`
- `packages/tui/README.md`

---

---
title: "Develop from source"
description: "Monorepo workspaces, build and check scripts, package boundaries (ai, agent, coding-agent, tui), and contributor conventions from AGENTS.md."
---

Prime Agent is an npm workspaces monorepo rooted at `package.json`. Source packages live under `packages/*` with inherited npm names `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui`. The public product, CLI, and release artifact are `prime-agent`. Local development runs through `./prime-agent.sh` (tsx on `packages/coding-agent/src/cli.ts`) or `./prime-agent.sh --dist` after a full build.

<Note>
Release docs and install scripts use Prime Agent product names. Workspace manifests still keep inherited `@earendil-works/pi-*` identifiers, a source `pi` bin entry, and some `PI_*` compatibility env vars until the namespace migration completes. Do not treat those inherited names as the public install path.
</Note>

## Prerequisites

| Requirement | Constraint |
|-------------|------------|
| Node.js | `>=22.8.0` (root `engines`; coding-agent enforces this at CLI entry) |
| npm | Prefer npm `>=11.10` so `.npmrc` `min-release-age=7` is enforced |
| Git | Required for clone and `PRIME_AGENT_BUILD_ID` from `git describe` |
| Python | Kernel runtime expects Python `>=3.10` with `ipykernel` (auto-bootstrap or `PRIME_AGENT_KERNEL_PYTHON`) |

Dependency updates resolve only to packages published at least 7 days ago (`min-release-age=7` in `.npmrc`). For an urgent security patch younger than 7 days:

```bash
npm install --min-release-age=0 <pkg>
```

## Clone and install

<Steps>
  <Step title="Clone and install workspaces">
```bash
git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci
```

Workspaces include `packages/*` plus selected coding-agent extension examples:

- `packages/coding-agent/examples/extensions/with-deps`
- `packages/coding-agent/examples/extensions/custom-provider-anthropic`
- `packages/coding-agent/examples/extensions/custom-provider-gitlab-duo`
- `packages/coding-agent/examples/extensions/sandbox`
  </Step>
  <Step title="Run from source against a project cwd">
```bash
/path/to/prime-agent/prime-agent.sh
```

The launcher can be invoked from any directory and preserves the caller’s working directory, so a source checkout can target a separate test project.
  </Step>
  <Step title="Verify the toolchain">
```bash
npm run check
```

`npm run check` runs Biome (format/lint with `--write --error-on-warnings`), `tsgo --noEmit`, installer render checks, and browser smoke checks. It does **not** run the test suite.
  </Step>
</Steps>

## Run from source

`prime-agent.sh` is the primary local entrypoint.

| Mode | Behavior |
|------|----------|
| Default | `tsx packages/coding-agent/src/cli.ts` |
| `--dist` | `node packages/coding-agent/dist/bundle/cli.js` (bundled build; fails if bundle missing) |
| `--no-env` | Unsets common provider API key / OAuth env vars for auth-path testing |

```bash
# Dev path (tsx)
./prime-agent.sh

# Release-like path after build
npm run build
./prime-agent.sh --dist

# Isolated config (avoids colliding with daily sessions)
PRIME_AGENT_CODING_AGENT_DIR=/tmp/prime-agent-dev ./prime-agent.sh
```

Success signals:

- Interactive TUI starts in the current cwd (or daemon-backed session attaches).
- Missing deps fail fast: `tsx not found … Run npm install from the repo root first` or `Bundle not found … Run npm run build first`.

### Config directories

| Scope | Default path | Override |
|-------|--------------|----------|
| User config | `~/.prime/agent/` | `PRIME_AGENT_CODING_AGENT_DIR` (compat: `PI_CODING_AGENT_DIR`) |
| Sessions | under agent dir | `PRIME_AGENT_SESSION_DIR` |
| Project config | `.prime/agent/` in project root | — |
| Package assets | resolved via `getPackageDir()` in `packages/coding-agent/src/config.ts` | `PI_PACKAGE_DIR` |

Use `getPackageDir()`, `getThemeDir()`, and related helpers for package assets. Do not resolve themes, skills, or docs from raw `__dirname` when packaging must work for source, Node dist, and standalone binaries.

## Monorepo layout

:::files
prime-agent/
├── package.json              # workspaces, root scripts, engines
├── AGENTS.md                 # contributor rules (source of truth for agents)
├── prime-agent.sh            # source launcher
├── prime-agent-runtime/      # Python kernel shim (ipykernel, rlm)
├── scripts/                  # release, pack, check, kernel bootstrap helpers
├── packages/
│   ├── ai/                   # @earendil-works/pi-ai — LLM providers & models
│   ├── agent/                # @earendil-works/pi-agent-core — agent loop runtime
│   ├── tui/                  # @earendil-works/pi-tui — terminal UI primitives
│   └── coding-agent/         # @earendil-works/pi-coding-agent — CLI, daemon, RLM
│       ├── src/              # CLI, modes, core services
│       ├── skills/           # built-in Python skills
│       ├── examples/sdk/     # SDK samples
│       ├── test/             # vitest suites + suite harness
│       └── docs/             # in-repo product docs
└── .npmrc                    # min-release-age=7
:::

## Package boundaries

```mermaid
flowchart TB
  subgraph app["Application"]
    CA["coding-agent<br/>@earendil-works/pi-coding-agent<br/>CLI · daemon · sessions · RLM"]
  end
  subgraph libs["Libraries"]
    AG["agent<br/>@earendil-works/pi-agent-core<br/>Agent loop · state · events"]
    AI["ai<br/>@earendil-works/pi-ai<br/>Providers · stream · models"]
    TUI["tui<br/>@earendil-works/pi-tui<br/>TUI components · editor"]
  end
  subgraph py["Python"]
    RT["prime-agent-runtime<br/>kernel rlm shim"]
  end
  CA --> AG
  CA --> AI
  CA --> TUI
  AG --> AI
  CA --> RT
```

| Package | Workspace name | Role | Depends on |
|---------|----------------|------|------------|
| `packages/ai` | `@earendil-works/pi-ai` | Unified LLM API, provider streams, model catalog, OAuth helpers | Provider SDKs |
| `packages/agent` | `@earendil-works/pi-agent-core` | Stateful agent runtime (`Agent`, loop, events, tool handling) | `pi-ai` |
| `packages/tui` | `@earendil-works/pi-tui` | Differential-render TUI primitives (Editor, Markdown, overlays) | chalk, marked, optional koffi |
| `packages/coding-agent` | `@earendil-works/pi-coding-agent` | Product CLI, interactive/RPC/JSON/ACP modes, daemon/worker, skills, harness | `pi-ai`, `pi-agent-core`, `pi-tui` |
| `prime-agent-runtime` | Python project | Kernel-side recursion shim (`rlm`, skills, harness helpers) | ipykernel, nest-asyncio, tyro |

Release packaging rewrites coding-agent name/bin/config for distribution (`scripts/pack-prime-agent-release.mjs`). In-tree, `piConfig` sets product name `prime-agent` and config dir `.prime/agent`, while the source `bin` entry remains `pi` pointing at `dist/bundle/cli.js`.

Root TypeScript path aliases in `tsconfig.json` map workspace packages to `packages/*/src` for typecheck without requiring a prior emit.

## Root scripts

| Script | What it does |
|--------|----------------|
| `npm run build` | Ordered: `tui` → `ai` → `agent` → `coding-agent` |
| `npm run clean` | `clean` in each workspace |
| `npm run dev` | Concurrent watch builds for all four packages via `concurrently` |
| `npm run check` | Biome + `tsgo --noEmit` + installer + browser-smoke |
| `npm run test` | `npm run test --workspaces --if-present` |
| `npm run release:patch` / `release:minor` / `release:major` | Lockstep release via `scripts/release.mjs` |
| `npm run release:pack` | Pack versioned release artifact |

Coding-agent package scripts of note:

| Script | Purpose |
|--------|---------|
| `build` | `tsgo` build, asset copy (themes, skills, `prime-agent-runtime`), esbuild bundle |
| `test` | vitest full package |
| `test:ci` | Kernel bootstrap + vitest excluding process supervisor stress |
| `test:process` | Daemon supervisor process tests |
| `test:kernel` | Kernel-heavy ACP/state tests (serialized) |

CI (`.github/workflows/ci.yml`) runs `npm ci` → `npm run build` → `npm run check`, then matrix tests per package (coding-agent sharded `test:ci` with uv for Python).

## Validation workflow

Contributor rule from `AGENTS.md`: after code changes (not pure docs), run `npm run check` and fix all errors, warnings, and infos before committing. Husky pre-commit runs `npm run check` and restages formatter-touched files.

<Warning>
Root agent rules intentionally restrict automated agents from running `npm run dev`, `npm run build`, and full `npm test` unless the user instructs otherwise. Humans developing locally still use those scripts as needed. Prefer focused package tests during iteration.
</Warning>

### Focused tests

Run tests from the **package root**, not the monorepo root:

```bash
cd packages/coding-agent
npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts
```

Rules:

- If you create or modify a test file, run that file until it passes.
- Coding-agent suite tests under `test/suite/` use `test/suite/harness.ts` and the **faux** provider — not real provider APIs, keys, or paid tokens.
- Issue regressions: `packages/coding-agent/test/suite/regressions/<issue-number>-<short-slug>.test.ts`.

Optional full offline suite driver: root `test.sh` moves `~/.prime/agent/auth.json` aside, unsets provider env keys, and runs workspace tests without live credentials.

## Contributor conventions

`AGENTS.md` is the binding contributor contract for this repository.

### Code quality

- No `any` unless unavoidable; prefer real types from installed packages.
- No inline/dynamic imports for modules or types — use top-level static imports.
- Do not downgrade code to silence type errors from outdated deps; upgrade the dependency.
- Do not hardcode key matches (`matchesKey(keyData, "ctrl+x")`). Keybindings must be configurable with defaults in `DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS`.
- Never edit `packages/ai/src/models.generated.ts` by hand. Change `packages/ai/scripts/generate-models.ts` and regenerate via the ai package build/`generate-models` script.
- Do not preserve backward compatibility unless explicitly requested.
- Ask before removing intentional behavior.

### Parallel-agent git safety

Multiple agents may share a worktree. Commit only files you changed in the current session:

```bash
git status
git add packages/ai/src/providers/transform-messages.ts packages/ai/CHANGELOG.md
git commit -m "fix(ai): description"
```

Forbidden without extreme care: `git add -A` / `git add .`, `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash`, `git commit --no-verify`.

Include `fixes #<n>` / `closes #<n>` when closing issues via commit.

### Changelogs

Each package has `packages/*/CHANGELOG.md`. New bullets go only under `## [Unreleased]` as past-tense one-liners (Added/Changed/Fixed/Removed). Do not edit released version sections.

### Issue labels

Use `pkg:agent`, `pkg:ai`, `pkg:coding-agent`, and/or `pkg:tui` on GitHub issues.

### Daemon protocol changes

Wire changes must be classified as backward-compatible, capability-gated, or incompatible:

- Optional features: negotiate server capability; clients must check before use.
- Incompatible or startup-required behavior: bump `DAEMON_PROTOCOL_VERSION`.
- Every wire change: update `DAEMON_SCHEMA_REVISION`, command/event compatibility maps, and both new-client/old-daemon and old-client/new-daemon tests.
- Optional metadata/UI must degrade locally; never block agent start or attachment.
- Do not require a new daemon command at startup without a protocol or capability gate.

### Adding an LLM provider

High-level surface (details in `AGENTS.md`):

1. Types in `packages/ai/src/types.ts` (`Api`, options, `KnownProvider`).
2. Provider implementation under `packages/ai/src/providers/`.
3. Subpath export in `packages/ai/package.json`, type re-exports, lazy registration in `register-builtins.ts`, credentials in `env-api-keys.ts`.
4. Model generation in `packages/ai/scripts/generate-models.ts`.
5. Provider matrix tests under `packages/ai/test/`.
6. Coding-agent wiring: `model-resolver.ts`, `provider-display-names.ts`, CLI env docs, providers docs.
7. `packages/ai` README + CHANGELOG unreleased entry.

Providers are BYOK/BYOC: callers supply API keys or OAuth; the monorepo does not hard-require a hosted Prime-only model.

### Versioning and release

All packages share one version (lockstep). Semantics used by the project:

| Bump | Meaning |
|------|---------|
| `patch` | Bug fixes and new features |
| `minor` | API breaking changes |

Release scripts finalize changelogs, commit, tag, and publish. Prefer updating `[Unreleased]` as you land work.

## Local debugging surfaces

| Surface | Location / command |
|---------|-------------------|
| Hidden `/debug` log | `~/.prime/agent/prime-agent-debug.log` |
| Daemon/client/provider logs | `~/.prime/agent/logs/` |
| Service status | `prime-agent status` (or `./prime-agent.sh status`) |
| Repair | `prime-agent doctor` / `doctor --fix` |
| Shutdown | `prime-agent shutdown` |

Interactive TUI smoke via tmux (from `AGENTS.md`): create a fixed-size session, send `./prime-agent.sh`, capture the pane, send keys — avoid killing unrelated tmux sessions on shared hosts.

## Format and typecheck toolchain

| Tool | Config | Role |
|------|--------|------|
| Biome | `biome.json` | Lint + format (tabs, line width 120) on `packages/*/src|test` and coding-agent examples |
| TypeScript | `tsconfig.base.json` + root `tsconfig.json` | Strict ES2022 / Node16 modules; root is `noEmit` check |
| Package emit | `packages/*/tsconfig.build.json` | `tsgo` production builds to `dist/` |
| Vitest | package `vitest.config.ts` | Unit/integration tests |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `tsx not found` | Root install missing | `npm ci` from repo root |
| `Bundle not found` with `--dist` | Dist not built | `npm run build` |
| Node version error at CLI start | Node &lt; 22.8.0 | Upgrade Node |
| Check fails on format only | Biome `--write` expected | Re-run `npm run check`, restage |
| Live provider tests fail offline | Real keys required | Use faux provider / suite harness; keep env keys unset for unit paths |
| Daemon attach collides with daily sessions | Shared `~/.prime/agent` | Set `PRIME_AGENT_CODING_AGENT_DIR` to a temp dir |
| New dependency resolves oddly | Old npm ignoring `min-release-age` | Use npm ≥ 11.10 |

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Stable install command, checksum verification, and binary placement for non-source installs.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First interactive session after install or source launch.
  </Card>
  <Card title="Extensions and custom tools" href="/extensions">
    Extension registration patterns used by monorepo examples.
  </Card>
  <Card title="Minimal SDK agent" href="/sdk-minimal">
    Programmatic bootstrap using workspace packages from `examples/sdk`.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Auth, resume, provider 401, and connection-mode failure probes.
  </Card>
  <Card title="Overview" href="/overview">
    Product entry points, modes, and runtime assumptions.
  </Card>
</CardGroup>