How to Build Prime Agent from Source for Development

To build Prime Agent from source for development, install Node.js 22.8 or newer, clone the monorepo, run npm ci and npm run build, then launch the agent using ./prime-agent.sh from the repository root.

Prime Agent is a TypeScript-based monorepo developed by PrimeIntellect-ai that combines a coding agent, AI provider layer, and terminal UI into a unified development environment. Building from source allows you to modify the core logic in packages/coding-agent, extend the AI abstractions in packages/ai, or customize the TUI in packages/tui while testing changes immediately. This guide covers the complete workflow to compile Prime Agent locally, including optional native binary generation.

Install Prerequisites

Building Prime Agent from source requires Node.js 22.8 or newer. This version is mandatory because the workspace relies on modern Node features for the native module bindings and the build toolchain. You can verify your version with node --version before proceeding.

Clone and Configure the Workspace

Clone the repository and install all workspace dependencies using npm ci. This command installs both common dev dependencies and the optional native bindings required for the bundled pi binary across all packages.

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

The monorepo structure places the core application in packages/coding-agent, the AI provider layer in packages/ai, and the terminal UI in packages/tui. Running npm ci from the root installs dependencies for all workspaces defined in the respective package.json files.

Build TypeScript Sources

Compile the TypeScript sources using the workspace-wide build script. This generates JavaScript in each package’s dist folder and prepares the source for execution.

npm run build

According to the source code in packages/coding-agent/src/config.ts, the build process centralizes asset location helpers that both source and binary builds rely on to resolve package paths correctly.

Build Native Binaries (Optional)

To create the self-contained pi executable for distribution, use the helper script at scripts/build-binaries.sh. The script installs cross-platform native bindings, runs the workspace build, and uses bun build to produce executables for each supported OS.

# Build for all platforms

./scripts/build-binaries.sh

# Build only for the current platform

./scripts/build-binaries.sh --platform $(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)

This step is only necessary if you need to test the final binary artifacts or distribute the pi command locally. For most development tasks, running from the TypeScript source is sufficient.

Run Prime Agent from Source

Launch the development version using the launcher script prime-agent.sh. The script preserves your current working directory, allowing you to test the agent against any project without installing a global package.

./prime-agent.sh

To run the agent with an isolated configuration—useful when iterating on daemon behavior or testing file system interactions—set the environment variables before launching:

PRIME_AGENT_CODING_AGENT_DIR=/tmp/prime-agent-dev \
PRIME_AGENT_SESSION_DIR=/tmp/prime-agent-session \
./prime-agent.sh

This configuration overrides the default paths defined in packages/coding-agent/src/config.ts, ensuring your development instance does not interfere with existing Prime Agent installations.

Summary

• Node.js 22.8+ is required to compile Prime Agent from source.
• Run npm ci followed by npm run build from the repository root to compile all workspace packages.
• The prime-agent.sh launcher script runs the agent directly from the source tree without global installation.
• Use scripts/build-binaries.sh to generate platform-specific pi binaries when needed.
• Configuration paths can be overridden using PRIME_AGENT_CODING_AGENT_DIR and PRIME_AGENT_SESSION_DIR environment variables.

Frequently Asked Questions

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

Node.js 22.8 or newer is mandatory. The build system and native module bindings rely on features introduced in this version, as documented in packages/coding-agent/docs/development.md.

How do I build the pi binary for only my current platform?

Pass the --platform flag to the build script with your OS and architecture. For example: ./scripts/build-binaries.sh --platform linux-x64 or use the dynamic uname command substitution shown in the build section to detect your system automatically.

Where are the compiled JavaScript files located after building?

The npm run build command outputs compiled JavaScript to the dist folder within each workspace package, such as packages/coding-agent/dist, packages/ai/dist, and packages/tui/dist.

Can I run Prime Agent without installing it globally or building binaries?

Yes. After running npm run build, execute ./prime-agent.sh from the repository root. This launcher script runs the TypeScript-compiled code directly without requiring a global npm installation or the compiled pi binary.

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