How to Set Up PrimeIntellect-ai/prime-agent Locally: Complete Installation Guide

To set up Prime Agent locally, either run the official installer script for a pre-built bundle or clone the repository and launch via the TypeScript CLI using ./prime-agent.sh.

Prime Agent is a self-improving coding assistant built on a persistent IPython kernel, a daemon-backed worker architecture, and a plug-in model provider layer. This guide walks through both methods to install and run PrimeIntellect-ai/prime-agent from source, with complete commands and architecture context drawn directly from the codebase.

---

Prerequisites for Local Setup

Before installing, verify your environment meets these requirements:

• Node.js 22.8+ – Required for running from source (checked in packages/coding-agent/docs/development.md)
• Python 3.8+ – For the IPython kernel environment
• macOS or Linux – Primary supported platforms
• Git – For cloning the repository

Confirm your Node version with:

node --version

---

Method 1: Install Pre-Built Release (Recommended)

The fastest way to set up Prime Agent locally uses the official installer script. This downloads a bundled JavaScript build and installs the prime-agent command globally.

# Download and run the official installer

curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh

After installation, verify the command is available:

prime-agent --version

Navigate to any project directory and launch:

cd /path/to/your/project
prime-agent

---

Method 2: Install From Source

For development or customization, clone the repository and run the TypeScript CLI directly via the launcher script.

Step 1: Clone and Install Dependencies

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

Step 2: Launch With the Development Launcher

The prime-agent.sh script at repository root handles the build-vs-source decision and preserves your current working directory:

./prime-agent.sh

This launcher parses command-line flags, selects between bundled builds or runs the TypeScript CLI via tsx, as implemented in the shell script logic.

---

Configure the IPython Kernel Environment

Prime Agent's core execution relies on a persistent IPython kernel. The helper script scripts/setup-kernel-venv.sh automates virtual environment creation and kernel bootstrap:

# Creates venv and launches kernel bootstrap CLI

scripts/setup-kernel-venv.sh

This step is optional for basic operation—the daemon supervisor spawns kernel processes automatically—but useful for debugging or isolated Python environments.

---

Authentication Setup

Prime Agent supports two authentication modes against provider APIs located in packages/ai.

Option A: Subscription Login (Interactive)

Launch Prime Agent and use the built-in TUI command:

/login

This flow is handled in packages/coding-agent/src/cli.ts, which implements slash command parsing and daemon connection.

Option B: API Key via Environment Variable

export ANTHROPIC_API_KEY=sk-...
export OPENAI_API_KEY=sk-...

# Run with explicit credentials

prime-agent

Use the --no-env flag to clear authentication variables if needed:

prime-agent --no-env

---

Understanding the Startup Architecture

Knowing how components interact helps debug setup issues. The startup flow defined in packages/coding-agent/docs/architecture.md proceeds as follows:

1. Launcher (prime-agent.sh) → decides bundled JS or tsx → starts CLI
2. CLI (packages/coding-agent/src/cli.ts) → opens connection to daemon supervisor
3. Daemon supervisor → spawns session worker if needed
4. Session worker → creates root AgentSessionRuntime → launches IPython kernel
5. Model provider streams (packages/ai) → generate text/tool calls, kernel executes Python
6. Persistence layer → writes transcripts and artifacts to ~/.prime/agent/sessions/

The AgentSessionRuntime class in packages/coding-agent/src/core/agent-session-runtime.ts coordinates the scheduler, kernel, and tool execution loop.

---

Configuration Directory Structure

Prime Agent reads configuration from two locations, as documented in packages/coding-agent/docs/development.md:

Location	Purpose
~/.prime/agent/	User-wide configuration and session storage
.prime/agent/	Project-local overrides (in working directory)

Session transcripts persist under ~/.prime/agent/sessions/ for audit and replay.

---

Managing Persistent Sessions

Prime Agent supports detaching and reattaching to long-running agent processes:

# List all running agents

prime-agent agents

# Reattach to specific agent ID

prime-agent attach <agent-id>

This daemon-backed architecture allows agents to continue execution even when the TUI disconnects.

---

Key Source Files Reference

File	Description
prime-agent.sh	Launcher script with --no-env and --dist flags
packages/coding-agent/src/cli.ts	CLI entry point, TUI, slash command parser
packages/coding-agent/src/core/agent-session-runtime.ts	Root session runtime and scheduler
scripts/setup-kernel-venv.sh	IPython kernel bootstrap helper
packages/coding-agent/docs/architecture.md	Component diagram and responsibilities
packages/coding-agent/docs/development.md	Node version, validation commands, config paths
packages/ai	Provider adapters (Anthropic, OpenAI, Bedrock)
packages/coding-agent/docs/quickstart.md	Extended source installation steps

---

Summary

• Quick install: Use curl -fsSL ... | sh for the pre-built release
• Source setup: Clone, run npm ci, then launch with ./prime-agent.sh
• Kernel setup: Optional scripts/setup-kernel-venv.sh for isolated Python
• Authentication: Interactive /login command or environment variables
• Architecture: Daemon-supervised workers with persistent IPython kernel
• Config locations: ~/.prime/agent/ (global) and .prime/agent/ (project)

---

Frequently Asked Questions

What Node.js version is required to set up Prime Agent locally?

Prime Agent requires Node.js 22.8 or newer when running from source. This requirement is documented in packages/coding-agent/docs/development.md. The pre-built installer bundles its own runtime and does not need Node installed.

How does Prime Agent handle API authentication securely?

Authentication flows through the packages/ai provider layer. You can either use the interactive /login command inside the TUI or export provider-specific API keys as environment variables. The --no-env flag clears these variables for isolated sessions.

Where are Prime Agent sessions and transcripts stored?

All session data persists to ~/.prime/agent/sessions/ by default. This includes conversation transcripts, executed code outputs, and tool call results. The daemon architecture ensures persistence even when the CLI disconnects and reattaches.

Can I run Prime Agent without installing the pre-built bundle?

Yes. Clone the repository, run npm ci to install dependencies, then execute ./prime-agent.sh. This launcher script detects the source environment and runs the TypeScript CLI via tsx rather than the bundled JavaScript build.

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