How to Set Up a Local Development Environment for PrimeAgent: A Complete Guide

PrimeAgent requires Node.js ≥22.8.0 and uses npm ci to install workspace dependencies, then launches via ./prime-agent.sh with optional environment variables for isolated configuration.

PrimeAgent is an open-source AI coding agent developed by Prime Intellect. It combines a TypeScript TUI, a Node.js supervisor daemon, and a Python IPython runtime for executing LLM-driven tasks. This guide walks you through configuring a PrimeAgent local development environment that mirrors production behavior while keeping your development work isolated from daily usage.

Prerequisites and System Requirements

Before you begin, ensure your system meets the minimum requirements defined in the PrimeAgent source code.

• Node.js ≥22.8.0 — This is a hard requirement for the monorepo's workspace packages.
• No system-wide Python packages — The repository automatically builds a virtual environment for the IPython kernel on first run, so manual Python setup is unnecessary.

Verify your Node version:

node --version

If your version is below 22.8.0, upgrade via Node Version Manager (nvm) or your system's package manager.

Clone the Repository and Install Dependencies

PrimeAgent uses a monorepo structure with exact lock-file versions. The officially supported installation method is npm ci, not npm install.

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

This command installs all workspace dependencies as specified in the lock file, ensuring reproducible builds across environments. The setup is documented in the Development guide.

Run PrimeAgent from Source

The repository provides prime-agent.sh, a thin wrapper script that preserves your current working directory when launching the agent stack.

Basic Execution

From any directory, invoke the wrapper:

/path/to/prime-agent/prime-agent.sh

This is the same entry point used by the packaged installer, as noted in the installer documentation.

Isolated Development Configuration

To prevent collision with your regular PrimeAgent usage, override the default configuration directory via environment variable:

PRIME_AGENT_CODING_AGENT_DIR=/tmp/prime-agent-dev \
/path/to/prime-agent/prime-agent.sh

The PRIME_AGENT_CODING_AGENT_DIR variable redirects all runtime data — transcripts, artifacts, and session state — to your specified path. This technique is detailed in the Local Configuration section of the development docs.

Understand the Architecture

PrimeAgent's three-layer architecture explains why the local development environment setup follows this specific pattern:

• Client layer — The interactive TUI or headless JSON/RPC clients
• Supervisor daemon — A local Node.js process managing system state
• Worker processes — Per-session hosts for AgentSessionRuntime, each containing a root AgentSession, scheduler, IPython kernel, and optional child RLM runtimes

Model providers are invoked from both root sessions and child runtimes. All transcripts and artifacts persist as JSONL files. See the full diagram in the Architecture Overview.

Daemon Interaction Commands

Once your PrimeAgent local development environment is running, use built-in CLI commands to inspect and control the supervisor:

prime-agent status          # Display supervisor and worker health

prime-agent doctor --fix    # Diagnose and auto-repair services

prime-agent shutdown        # Stop all workers and the supervisor

These utilities are listed under Useful service commands in the development documentation.

Validate Your Changes

Before submitting contributions, run the repository-wide validation suite. The npm run check command enforces:

• Code formatting
• Linting rules
• Type-checking across packages
• Installer rendering checks
• Browser smoke tests

npm run check

For focused testing, navigate to a specific package and run individual Vitest files with tsx:

cd packages/coding-agent
npx tsx vitest run src/path/to/test.ts

This approach is faster than the full suite when iterating on specific components.

Package Asset Resolution

When modifying code that references themes, icons, or other static assets, use the helper functions exported from packages/coding-agent/src/config.ts:

Function	Purpose
getPackageDir()	Resolve package root directory safely
getThemeDir()	Locate theme assets correctly

Direct __dirname usage is discouraged and documented under Package Asset Resolution. Following this convention ensures your changes work correctly in both source and packaged builds.

Summary

• Node.js ≥22.8.0 is the only system prerequisite; Python environment is auto-provisioned.
• Clone with git clone and install exact dependencies via npm ci.
• Launch from source using ./prime-agent.sh, the same entry point as production installers.
• Isolate development sessions with PRIME_AGENT_CODING_AGENT_DIR environment variable.
• Control the daemon using prime-agent status, doctor, and shutdown commands.
• Validate all changes with npm run check before contributing.
• Use getPackageDir and getThemeDir from src/config.ts for asset resolution.

Frequently Asked Questions

What Node.js version does PrimeAgent require?

PrimeAgent requires Node.js ≥22.8.0 as documented in the source repository. No additional Python installation is needed because the system automatically builds a virtual environment for its IPython kernel on first run.

How do I prevent development work from interfering with my regular PrimeAgent usage?

Set the PRIME_AGENT_CODING_AGENT_DIR environment variable to a temporary path before launching. This overrides the default ~/.prime/agent/ directory and isolates transcripts, artifacts, and session state to your specified location.

What is the difference between npm install and npm ci for PrimeAgent?

Always use npm ci for PrimeAgent local development. This command installs exact versions from the lock file, matching the reproducible build process used in production. npm install may upgrade dependencies and introduce version mismatches.

Where can I find the architecture documentation for PrimeAgent?

The complete architecture diagram and description are located at packages/coding-agent/docs/architecture.md. This document explains the relationship between the client TUI, supervisor daemon, worker processes, and the AgentSessionRuntime that hosts the IPython kernel.

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