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

To set up a PrimeAgent development environment, clone the repository, run npm ci with Node.js ≥ 22.8.0, and launch the agent using the ./prime-agent.sh wrapper script while isolating your config with the PRIME_AGENT_CODING_AGENT_DIR environment variable.

PrimeAgent is a sophisticated monorepo that combines a TypeScript-based TUI, a Node.js daemon/supervisor, and a Python runtime (IPython) that drives large language models. Setting up a proper development environment requires understanding its architecture as a client-supervisor-worker system. This guide walks you through cloning the repository, installing dependencies, and running the full stack from source while maintaining isolation from production data.

Prerequisites and System Requirements

PrimeAgent requires Node.js ≥ 22.8.0 to build and run correctly. Unlike many Python-heavy projects, you do not need to install system-wide Python packages manually. The repository ships with a script that automatically builds a virtual environment for the IPython kernel on first run, ensuring consistent Python dependencies across all development machines.

Understanding the Architecture

Before installing, it helps to understand how the components interact. PrimeAgent splits functionality across three layers:

• Client: The interactive TUI or headless JSON/RPC clients
• Supervisor: A local daemon that manages the lifecycle of agent sessions
• Workers: Per-session processes that host an AgentSessionRuntime, which owns a root AgentSession, scheduler, IPython kernel, and any child RLM runtimes

Model providers are called from both the root session and its children, with all transcripts and artifacts persisted as JSONL files. For the complete architecture diagram and component descriptions, see packages/coding-agent/docs/architecture.md.

Installation and Setup

Cloning the Repository

Start with a clean checkout of the source code:

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

Installing Dependencies

Use npm ci to install exact lock-file versions of all workspace packages. This ensures reproducible builds across the TypeScript TUI, Node.js daemon, and shared libraries:

npm ci

This command is documented in the Development guide, which also specifies that npm install should be avoided in favor of npm ci to prevent lock-file drift.

Running PrimeAgent from Source

Using the Wrapper Script

The repository provides a thin wrapper script prime-agent.sh that preserves the caller’s working directory. Invoke it from any directory to start the full agent stack:

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

This script serves as the same entry point used by the packaged installer, ensuring your development environment mirrors production behavior. The script is located at the repository root and handles the complex orchestration of starting the supervisor daemon and worker processes.

Isolating Development Configuration

Development sessions should avoid colliding with your normal usage data stored in ~/.prime/agent/. Override the default configuration directory using the PRIME_AGENT_CODING_AGENT_DIR environment variable:

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

This isolation technique is described in the Local Configuration section of packages/coding-agent/docs/development.md and is essential for safely testing configuration changes or experimental features.

Managing the Daemon and Workers

After the agent starts, you can use built-in CLI commands to inspect or control the daemon. These utilities communicate with the supervisor process to manage the health of your development environment:

prime-agent status          # show supervisor/worker health

prime-agent doctor --fix   # diagnose and repair services

prime-agent shutdown        # stop all workers and the supervisor

These commands are listed under Useful service commands in packages/coding-agent/docs/development.md and provide essential tooling for debugging worker states or recovering from hung processes during development.

Validation and Testing

Before committing code, run the repository-wide validation suite to enforce formatting, linting, type-checking, installer rendering checks, and a browser-smoke test:

npm run check

This command is required by the contribution rules documented in AGENTS.md. For focused test work on specific packages, navigate to the package directory (e.g., packages/coding-agent) and execute specific Vitest files using tsx as shown in the development documentation.

Development Best Practices

Package Asset Resolution

When referencing assets such as themes or icons from code, always use the helpers exported from packages/coding-agent/src/config.ts. Specifically, use getPackageDir and getThemeDir to resolve paths safely:

import { getPackageDir, getThemeDir } from './config.js';

const themePath = getThemeDir();
const packageRoot = getPackageDir();

Direct __dirname usage is discouraged because it breaks when the code is bundled or moved. The asset resolution utilities ensure your code works correctly both in development and in packaged releases.

Summary

• PrimeAgent requires Node.js ≥ 22.8.0 and automatically manages Python dependencies via an embedded virtual environment builder.
• Use npm ci, not npm install, to install dependencies from the lock file in the monorepo root.
• Launch from source using the ./prime-agent.sh wrapper script, which preserves your working directory and matches the production entry point.
• Isolate configurations by setting PRIME_AGENT_CODING_AGENT_DIR to prevent development sessions from corrupting your personal agent data in ~/.prime/agent/.
• Manage the daemon using prime-agent status, prime-agent doctor, and prime-agent shutdown commands.
• Validate changes with npm run check before submitting pull requests, as required by AGENTS.md.
• Resolve assets safely using getPackageDir and getThemeDir from packages/coding-agent/src/config.ts rather than hardcoding paths.

Frequently Asked Questions

What Node.js version is required for PrimeAgent development?

PrimeAgent requires Node.js ≥ 22.8.0. The project uses modern Node.js features for the daemon and TUI components, and earlier versions may fail during the npm ci installation or runtime phases. Check your version with node --version before cloning the repository.

How do I prevent my development environment from interfering with my production PrimeAgent data?

Set the PRIME_AGENT_CODING_AGENT_DIR environment variable to a temporary or project-specific directory before running ./prime-agent.sh. For example: PRIME_AGENT_CODING_AGENT_DIR=/tmp/prime-agent-dev ./prime-agent.sh. This overrides the default ~/.prime/agent/ location, keeping your development transcripts and artifacts separate from your personal usage data.

Why does PrimeAgent use a wrapper script instead of running npm start directly?

The prime-agent.sh wrapper script preserves the caller’s working directory, which is crucial for the agent to correctly resolve relative paths for user projects. It also mirrors the entry point used by the packaged installer documented in README.md, ensuring that behavior tested in development matches production deployments exactly.

How do I run tests for a specific package in the PrimeAgent monorepo?

Navigate to the specific package directory (such as packages/coding-agent) and execute the Vitest test files using tsx. While npm run check validates the entire repository, package-specific testing allows for rapid iteration during feature development. Refer to packages/coding-agent/docs/development.md for the exact command syntax and testing patterns used in that workspace.

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