# How to Build PrimeIntellect-ai/prime-agent from Source: Complete Installation Guide

> Build PrimeIntellect-ai/prime-agent from source easily. Follow our complete guide to clone the repo, install dependencies, compile, and launch the agent for your projects.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Build Prime Agent from source by cloning the repository, running `npm ci` to install workspace dependencies, `npm run build` to compile all packages, then launching with [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh).**

Prime Agent is a TypeScript-based monorepo that orchestrates a daemon, workers, an IPython kernel, and model provider integrations. This guide walks through **how to build prime-agent from source** on Node 22.8+, with practical commands for development, testing, and distribution builds.

## Prerequisites

Before building Prime Agent, verify your environment meets these requirements:

- **Node.js ≥ 22.8.0** — enforced by [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) engines field
- **Git** — for cloning the repository
- **npm** — bundled with Node.js for workspace management

Check your Node version:

```bash
node --version

```

## Step 1: Clone the Repository

Clone the PrimeIntellect-ai/prime-agent repository and enter the project directory:

```bash
git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent

```

The repository structure follows a monorepo pattern with npm workspaces under `packages/*`.

## Step 2: Install Dependencies

Install all workspace dependencies with **exact versions** from the lockfile:

```bash
npm ci

```

This command installs packages for:
- `packages/tui/` — Terminal UI components
- `packages/ai/` — Model provider adapters
- `packages/agent/` — Daemon supervisor
- `packages/coding-agent/` — Core runtime and session management

## Step 3: Build All Packages

Compile the entire workspace in dependency order:

```bash
npm run build

```

The build script in [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) orchestrates compilation of:
- TUI presentation layer (React + Ink)
- AI provider wrappers
- Daemon supervisor
- Coding agent workspace with `AgentSessionRuntime`

## Step 4: Launch the Built Application

Run the freshly built binary using the launcher script:

```bash
./prime-agent.sh

```

The [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) launcher intelligently selects between:
- **Development mode** — Runs TypeScript entry point via `tsx` (default)
- **Production mode** — Runs pre-bundled build with `--dist` flag

### Run the Optimized Distribution Build

For faster startup after building:

```bash
./prime-agent.sh --dist

```

The script verifies that [`packages/coding-agent/dist/bundle/cli.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/dist/bundle/cli.js) exists before launching. If missing, it aborts with an error message.

## Development Workflow

### Validate Code Health

Run the full check suite before committing:

```bash
npm run check

```

This executes:
- **Biome** formatting and linting
- **TypeScript** type checking
- Installer rendering validation
- Browser smoke tests

### Run Individual Tests

Execute a specific coding-agent unit test:

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

```

### Isolate Configuration Directory

Prevent collisions with system installations during development:

```bash
PRIME_AGENT_CODING_AGENT_DIR=/tmp/prime-agent-dev ./prime-agent.sh

```

The daemon stores config and transcripts under the specified temporary path instead of `~/.prime/agent/`.

## Architecture Overview

Understanding the build output requires knowing how components interact:

| Component | Source Location | Role |
|-----------|----------------|------|
| **Interactive TUI** | `packages/tui/` | Renders UI, captures input |
| **AgentConnection** | [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts) | Client-daemon protocol boundary |
| **Supervisor** | `packages/agent/` | Manages workers, session routing, crash recovery |
| **Session Worker** | `packages/coding-agent/src/core/` | Owns `AgentSessionRuntime` tree |
| **AgentSessionRuntime** | [`packages/coding-agent/src/core/AgentSessionRuntime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/AgentSessionRuntime.ts) | Executes prompts, schedules sub-agents |
| **IPython Kernel** | `packages/coding-agent/src/kernel/` | Python environment for tool calls |
| **Model Providers** | `packages/ai/src/providers/` | Streams from OpenAI, Anthropic, etc. |
| **Persistence** | `packages/coding-agent/src/storage/` | JSONL transcripts and artifacts |

The execution flow follows: **TUI → AgentConnection → Supervisor → Worker → AgentSessionRuntime → Model Providers/IPython**.

## Complete Build Example

```bash

# Clone and enter repository

git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent

# Install workspace dependencies

npm ci

# Compile all packages

npm run build

# Launch development build

./prime-agent.sh

# Or launch optimized production build

./prime-agent.sh --dist

```

## Key Source Files for Builders

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) | Workspace definition, build scripts, Node version constraint |
| [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) | Launcher script with `--dist` flag handling |
| [`packages/coding-agent/docs/development.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md) | Official developer setup guide |
| [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) | System diagrams and execution flow |
| [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts) | CLI entry point invoked by launcher |

## Summary

Building Prime Agent from source requires four essential steps:

- **Clone** the PrimeIntellect-ai/prime-agent repository
- **Install** dependencies with `npm ci` across all workspaces
- **Build** with `npm run build` to compile TypeScript packages
- **Launch** via [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) or `./prime-agent.sh --dist` for production

The monorepo structure separates concerns across `packages/tui/`, `packages/ai/`, `packages/agent/`, and `packages/coding-agent/`, with [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) serving as the unified entry point for both development and distribution builds.

## Frequently Asked Questions

### What Node.js version is required to build Prime Agent?

**Node.js 22.8.0 or higher is required.** The [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) explicitly enforces this version in its engines field. Earlier versions may cause compilation failures or runtime errors with the TypeScript configuration.

### How do I run Prime Agent without rebuilding after code changes?

Use [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) without the `--dist` flag. This launches the TypeScript source directly via `tsx`, enabling instant reflection of code changes without recompilation. For production performance, build first then use `--dist`.

### Where does Prime Agent store configuration and session data?

By default, data persists to `~/.prime/agent/` or project-local `.prime/agent/`. Override this with the `PRIME_AGENT_CODING_AGENT_DIR` environment variable to use a custom path for isolated development or testing.

### What is the difference between `npm run build` and `prime-agent.sh --dist`?

`npm run build` compiles TypeScript to JavaScript bundles. `./prime-agent.sh --dist` executes the pre-built bundles from [`packages/coding-agent/dist/bundle/cli.js`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/dist/bundle/cli.js) for faster startup. Without `--dist`, the launcher runs source files through `tsx` with slower but instant-update behavior.