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

> Set up your PrimeAgent development environment easily. Clone the repo, install dependencies with Node.js, and launch the agent using the provided script for seamless coding.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: getting-started
- Published: 2026-08-09

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md).

## Installation and Setup

### Cloning the Repository

Start with a clean checkout of the source code:

```bash
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:

```bash
npm ci

```

This command is documented in the [Development guide](packages/coding-agent/docs/development.md), 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) that preserves the caller’s working directory. Invoke it from any directory to start the full agent stack:

```bash
/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:

```bash
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```bash
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```bash
npm run check

```

This command is required by the contribution rules documented in [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/config.ts). Specifically, use `getPackageDir` and `getThemeDir` to resolve paths safely:

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md).
- **Resolve assets safely** using `getPackageDir` and `getThemeDir` from [`packages/coding-agent/src/config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/development.md) for the exact command syntax and testing patterns used in that workspace.