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

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.

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 engines field
• Git — for cloning the repository
• npm — bundled with Node.js for workspace management

Check your Node version:

node --version

Step 1: Clone the Repository

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

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:

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:

npm run build

The build script in 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:

./prime-agent.sh

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

./prime-agent.sh --dist

The script verifies that 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:

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:

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:

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

# 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	Workspace definition, build scripts, Node version constraint
prime-agent.sh	Launcher script with --dist flag handling
packages/coding-agent/docs/development.md	Official developer setup guide
packages/coding-agent/docs/architecture.md	System diagrams and execution flow
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 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 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 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 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 for faster startup. Without --dist, the launcher runs source files through tsx with slower but instant-update behavior.

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