How to Set Up PrimeAgent Locally: Complete Installation and Configuration Guide

PrimeAgent is a self-improving coding assistant built on a modular architecture that separates the terminal UI, daemon supervision, session workers, and an IPython kernel for model-driven tool execution.

Setting up PrimeAgent locally involves choosing between a pre-built release or building from source, then authenticating with a model provider to enable AI-powered coding assistance. This guide walks through both installation methods, explains the underlying architecture, and covers the detach/reattatch workflow that makes long-running autonomous tasks possible.

PrimeAgent Architecture Overview

Understanding how the components interact helps explain why PrimeAgent can survive client restarts and handle background tasks. According to the PrimeIntellect-ai/prime-agent source code, the system consists of four main layers:

• Interactive TUI / Headless Clients — The front-end that renders output and accepts keystrokes. Run prime-agent for the interactive interface or prime-agent -p for headless execution. These clients communicate with the daemon via a local protocol.

• Daemon Supervisor — Routes commands, manages worker processes, and maintains a catalog of saved sessions. It isolates execution from the client but does not sandbox OS permissions. See packages/coding-agent/docs/architecture.md for implementation details.

• Session Worker — Owns a single root AgentSessionRuntime, a scheduler, and a persistent IPython kernel. The root session can spawn recursive subagents that run in their own child runtimes, sharing the same provider and tool stack.

• Model Providers — Abstracted behind a unified streaming interface. Providers are selected via /login or environment-variable API keys. Supported providers are documented in packages/coding-agent/docs/providers.md.

Session persistence stores all transcript events and generated artifacts as JSONL files under ~/.prime/agent/sessions/, enabling detach/reattach semantics and replay of prior work.

Installation Method 1: Pre-Built Release (Recommended)

The fastest way to set up PrimeAgent locally uses the official install script. This works on macOS and Linux systems.

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

After installation, the prime-agent binary becomes available in your PATH. Restart your terminal or run source ~/.bashrc (or equivalent) to refresh your environment.

Installation Method 2: Build from Source

Building from source requires Node 22 or newer. This method is preferred for contributors or users needing the latest unreleased features.

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

./prime-agent.sh  # launches the agent from the source tree

The ./prime-agent.sh launcher script sets up the Node workspace and starts the daemon. This script is the recommended entry point when running from source rather than invoking Node directly.

Authenticating with Model Providers

PrimeAgent requires a valid model provider to function. Two authentication methods are supported:

Option A: Interactive Subscription Login

cd /path/to/your/project
prime-agent       # opens the interactive TUI

/login            # built-in authentication UI

Option B: Environment Variable API Key

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

# or other supported provider keys

prime-agent

See packages/coding-agent/docs/providers.md for the complete list of supported providers and their required environment variable names.

Basic Usage Patterns

Interactive TUI Sessions

Launch PrimeAgent in your project directory to start an interactive session:

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

The TUI provides real-time output rendering and accepts natural language commands alongside standard shell input.

Non-Interactive One-Shot Prompts

Execute single prompts without entering the interactive interface:

prime-agent -p "Summarize the codebase"
prime-agent -p @src/main.ts "Explain this module"

The @file syntax attaches file context to your prompt. This is useful in CI/CD pipelines or when scripting PrimeAgent operations.

Detach/Reattach Workflow

Because the session worker runs as a separate process from the client, you can detach and reattach to running sessions:

prime-agent agents          # list running sessions with IDs

prime-agent attach <id>    # re-attach to a specific background session

prime-agent --resume       # continue the most recent session

This architecture enables long-running autonomous tasks that survive terminal closures and system sleep/wake cycles.

Project-Specific Configuration

PrimeAgent reads custom behavior instructions from an AGENTS.md file in your project root. Create this file to define:

• Project-specific coding conventions
• Preferred tool usage patterns
• Context about your codebase structure

The daemon checks for AGENTS.md on session startup and incorporates its contents into the system prompt.

Key Configuration Files Reference

File	Purpose
README.md	High-level description and quick install commands
packages/coding-agent/docs/quickstart.md	Step-by-step first session instructions
packages/coding-agent/docs/architecture.md	Component diagrams and execution flow details
prime-agent.sh	Source tree launcher script
packages/coding-agent/docs/providers.md	Provider credentials and environment variables
AGENTS.md	Project-specific instruction file (user-created)

Summary

• Two installation paths: Pre-built release via install script, or source build with Node 22+ and npm ci
• Authentication options: Interactive /login command or environment variable API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
• Modular architecture: Client, daemon, and worker processes enable detach/reattach and background task persistence
• Session storage: JSONL files in ~/.prime/agent/sessions/ preserve transcript history and generated artifacts
• Project customization: Create AGENTS.md in project roots to tailor behavior to your codebase

Frequently Asked Questions

What are the system requirements for running PrimeAgent locally?

PrimeAgent requires macOS or Linux for the pre-built release, or Node 22+ for source builds. The daemon and worker processes consume moderate memory; 4GB RAM is sufficient for most coding tasks. No GPU is required as inference runs against remote model providers.

How do I switch between different model providers?

Use the /login command in an interactive session to reauthenticate with a different provider, or set the corresponding environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, etc.) before launching. The active provider is determined at session startup and persists for that session's lifetime.

Can I run PrimeAgent without the interactive TUI?

Yes. Use the prime-agent -p "your prompt" syntax for headless execution. This returns results to stdout and exits, making it suitable for scripts and automation. File context can be attached with @path/to/file syntax.

Where are my session histories stored if I want to back them up or delete them?

All session data lives in ~/.prime/agent/sessions/ as JSONL files. Each session has its own subdirectory containing transcript events, generated artifacts, and kernel state. Delete specific session directories to remove history, or back up the entire folder to preserve your work across machines.

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