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

> Easily set up a local development environment for PrimeAgent. Follow our complete guide using Node.js and npm ci for seamless installation and launch.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-10

---

**PrimeAgent requires Node.js ≥22.8.0 and uses `npm ci` to install workspace dependencies, then launches via [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./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:

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

```bash
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](packages/coding-agent/docs/development.md).

## Run PrimeAgent from Source

The repository provides [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

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

```

This is the same entry point used by the packaged installer, as noted in the [installer documentation](README.md#install-the-latest-stable-release).

### Isolated Development Configuration

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

```bash
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](packages/coding-agent/docs/architecture.md).

## Daemon Interaction Commands

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

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

```bash
npm run check

```

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

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