# Overview

> What Prime Agent exposes, primary entry points (CLI, SDK, modes), runtime assumptions, and the first docs routes to follow.

- Repository: PrimeIntellect-ai/prime-agent
- GitHub: https://github.com/PrimeIntellect-ai/prime-agent
- Human docs: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1
- Complete Markdown: https://grok-wiki.com/public/docs/primeintellect-ai-prime-agent-3367c32760b1/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `packages/coding-agent/README.md`
- `packages/agent/src/agent-loop.ts`
- `AGENTS.md`

---

---
title: "Overview"
description: "What Prime Agent exposes, primary entry points (CLI, SDK, modes), runtime assumptions, and the first docs routes to follow."
---

Prime Agent (`prime-agent`) is an open-source coding and research agent monorepo that exposes a terminal harness, multi-provider model access, a persistent IPython control plane, durable harness state, and a programmatic agent loop. Public install installs the `prime-agent` binary; the workspace packages are `packages/ai`, `packages/agent`, `packages/coding-agent`, and `packages/tui` (Node `>=22.8.0`).

## What Prime Agent exposes

| Surface | Role |
|---------|------|
| Interactive CLI / TUI | Default entry: `prime-agent` in a project directory |
| Session lifecycle CLI | Browse, attach, resume, status, doctor, update, shutdown |
| Persistent IPython kernel | Built-in model tool for files, shell, edits, and inspection |
| Continual harness | Durable supplemental prompts, memories, skill descriptions, subagent specs |
| Skills | Importable Python packages; `/skill:name` and skill creator |
| Extensions / prompt templates | Custom commands, tools, UI, and `/templatename` expansion |
| Programmatic agent loop | `agentLoop` / `agentLoopContinue` in `packages/agent` |
| Headless modes | JSON mode and RPC mode (documented under coding-agent docs) |

Prime Agent began as a hard fork of pi-mono and is now distributed independently. Public releases are versioned tarball artifacts installed by the install script; release packaging rewrites the application package and command to `prime-agent`. Do not use inherited npm package identifiers as the public install path.

## Core abstractions

### Recursive Language Model (RLM)

The RLM model treats context as variables (*prompt-as-a-variable*) and tools and recursive subagents as function calls inside a persistent REPL.

| Capability | Behavior |
|------------|----------|
| Control tool | Persistent IPython is the built-in model tool |
| Programmatic surface | File ops, shell, tools, subagents, and context management run as code |
| Subagents | `rlm(...)` spawns real child agents for parallel or background work and returns results programmatically |
| Agent messaging | Running agents can exchange messages and orchestrate one another without routing everything through the user |

### Continual Harness

The Continual Harness stores supplemental prompts, memories, skill descriptions, and reusable subagent specifications as durable state, local to the session by default.

| Constraint | Behavior |
|------------|----------|
| `/refine` | Reviews the current trajectory and may apply small, evidence-backed updates to supplemental harness state |
| Base system prompt | Immutable; refine never rewrites it |
| Snapshots | Recorded refinement history supports rollback |
| Skills boundary | Refine does not replace packaging and reviewing new executable skills |

```text
┌─────────────────────────────────────────────────────────────┐
│  User / editor / automation                                 │
│    prime-agent  |  attach/resume  |  agentLoop(...)         │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  Session runtime (coding-agent TUI / daemon client)         │
│  messages · queue · tree/fork · compact · goals · autonomous│
└────────────────────────────┬────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌───────────────┐   ┌─────────────────┐   ┌──────────────────┐
│ RLM control   │   │ Continual       │   │ packages/agent   │
│ IPython tool  │   │ Harness state   │   │ agentLoop        │
│ rlm(...)      │   │ /refine         │   │ EventStream      │
└───────────────┘   └─────────────────┘   └──────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│ packages/ai — providers, models,      │
│ streamSimple / tool-capable models    │
└───────────────────────────────────────┘
```

## Primary entry points

### Install and first launch

Stable install (macOS or Linux):

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

Beta from latest `main`:

```bash
curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh -s -- beta
```

The installer downloads a versioned release, verifies its SHA-256 checksum, installs the `prime-agent` command, and can prepare the IPython runtime. The Python kernel runtime is also set up automatically on first invocation. Set `PRIME_AGENT_KERNEL_PYTHON` to point at an existing Python environment that provides `ipykernel`.

Start in the directory the agent should work in:

```bash
cd /path/to/project
prime-agent
```

On first launch, run `/login` to choose a subscription or API-key provider, or export a provider key (for example `ANTHROPIC_API_KEY`) before starting.

### Session and service commands

| Command | Purpose |
|---------|---------|
| `prime-agent` | Interactive session in the current directory |
| `prime-agent agents` | Browse running, idle, and saved sessions |
| `prime-agent attach <agent>` | Reattach to a running session |
| `prime-agent --resume <path\|id>` | Resume a saved session |
| `prime-agent status` | Inspect background service state |
| `prime-agent doctor [--fix]` | Inspect or repair background services |
| `prime-agent update [--force]` | Update Prime Agent |
| `prime-agent shutdown [--force]` | Stop every agent, worker, and background service |

### Interactive commands (selected)

Type `/` in the editor. Extensions can register custom commands; skills appear as `/skill:name`; prompt templates expand via `/templatename`.

| Command | Description |
|---------|-------------|
| `/login`, `/logout` | OAuth authentication |
| `/model` | Switch models (also Ctrl+L) |
| `/effort` | Set reasoning / thinking level |
| `/settings` | Thinking level, theme, message delivery, transport |
| `/resume` | Searchable session view |
| `/new`, `/clear` | Start a new session |
| `/tree` | Jump to any point in the session and continue |
| `/fork` | New session from a previous user message |
| `/clone` | Duplicate the active branch into a new session |
| `/compact [prompt]` | Manual context compaction |
| `/reload` | Reload keybindings, extensions, skills, prompts, context files |
| `/quit` | Quit Prime Agent |

Long-running work surfaces (TUI and autonomous runs) also include `/goal`, `/heartbeat` / `rlm_heartbeat`, `prime-agent schedule`, and `/autonomous` with configured turn, token, and time budgets.

### Message queue while the agent works

| Input | Delivery |
|-------|----------|
| Enter | *Steering* message after the current assistant turn finishes its tool calls |
| Alt+Enter | *Follow-up* message after the agent finishes all work |
| Ctrl+C | Interrupt active work; restore queued messages to the editor |
| Escape | Clear input without interrupting active work |
| Alt+Up | Pull queued messages back into the editor |

### Programmatic agent loop

`packages/agent/src/agent-loop.ts` exports a stream-based loop that keeps `AgentMessage` values through the turn and transforms to LLM `Message[]` only at the provider call boundary.

| Export | Use |
|--------|-----|
| `agentLoop(prompts, context, config, signal?, streamFn?)` | Start a loop with new prompt messages |
| `agentLoopContinue(context, config, signal?, streamFn?)` | Continue without adding a prompt (retries); last context message must convert to `user` or `toolResult` |
| `runAgentLoop` / `runAgentLoopContinue` | Async emit-sink variants returning `AgentMessage[]` |

```ts
// packages/agent — stream API shape
export function agentLoop(
  prompts: AgentMessage[],
  context: AgentContext,
  config: AgentLoopConfig,
  signal?: AbortSignal,
  streamFn?: StreamFn,
): EventStream<AgentEvent, AgentMessage[]>;

export function agentLoopContinue(
  context: AgentContext,
  config: AgentLoopConfig,
  signal?: AbortSignal,
  streamFn?: StreamFn,
): EventStream<AgentEvent, AgentMessage[]>;
```

| Constraint | Detail |
|------------|--------|
| Empty context | `agentLoopContinue` throws `"Cannot continue: no messages in context"` |
| Last role assistant | Throws `"Cannot continue from message role: assistant"` |
| Abort | Abort produces assistant messages with `stopReason: "aborted"` and error `"Request was aborted"` |
| Stream completion | Stream ends on `agent_end`; failure ends with `[]` |
| Emitted events (start path) | `agent_start`, `turn_start`, `message_start` / `message_end` per prompt, then the shared turn loop |

Monorepo root also exposes profiling helpers for TUI and RPC modes (`profile:tui`, `profile:rpc`).

## Runtime assumptions

| Assumption | Requirement / default |
|------------|------------------------|
| Host platforms | Installer targets macOS and Linux; coding-agent docs also cover Windows, Termux, tmux, and terminal setup |
| Node (from source / workspaces) | `engines.node`: `>=22.8.0` |
| Working directory | Agent operates in the current directory; can run commands and modify files there |
| Model tool | Default tool is `ipython` (persistent kernel) |
| Kernel Python | Auto-prepared on first use, or `PRIME_AGENT_KERNEL_PYTHON` with `ipykernel` |
| Auth | Subscription OAuth via `/login` or provider API keys (BYOK); multi-provider selection via `/model` |
| User config paths | e.g. `~/.prime/agent/keybindings.json`, `~/.prime/agent/models.json` |
| Continuity | Daemon-backed sessions keep IPython state, schedules, and subagents running across detach/reattach |
| Long tasks | Compaction, goals, heartbeats, schedules, autonomous budgets, retained subagents |

<Warning>
Prime Agent executes model-generated Python and project commands with your user permissions. Worker and kernel processes improve lifecycle isolation and recovery; they are **not** a security sandbox. Review changes and use trusted repositories, instructions, skills, and extensions only. Run untrusted code or instructions in an external sandbox or restricted environment. Prefer a disposable clone, clean worktree, or another checkpoint you can inspect and restore.
</Warning>

## Providers (BYOK / multi-provider)

Authentication is provider-neutral: use subscription OAuth (`/login`) or API keys. Built-in providers maintain lists of tool-capable models updated each release. Custom providers that speak supported APIs (OpenAI, Anthropic, Google) can be added via `~/.prime/agent/models.json`; custom APIs or OAuth use extensions.

**Subscriptions (examples):** Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro (Codex), GitHub Copilot.

**API-key providers (examples):** Anthropic, OpenAI, Prime Inference, Azure OpenAI, DeepSeek, Google Gemini, Google Vertex, Amazon Bedrock, Mistral, Groq, Cerebras, Cloudflare AI Gateway / Workers AI, xAI, OpenRouter, Vercel AI Gateway, ZAI, OpenCode Zen / Go, Hugging Face, Fireworks, Kimi For Coding, MiniMax, Xiaomi MiMo and regional MiMo Token Plan endpoints.

## Monorepo map

| Package / path | Responsibility |
|----------------|----------------|
| `packages/coding-agent` | CLI, TUI harness, docs, examples (extensions, sandbox) |
| `packages/agent` | Agent loop, context, tools, events |
| `packages/ai` | Providers, models, streaming, credential detection |
| `packages/tui` | Terminal UI primitives |
| Root `npm run build` | Builds `tui` → `ai` → `agent` → `coding-agent` |
| Root `npm run check` | Biome, typecheck, installer and browser smoke checks (does not run tests) |

Issue labels used for package ownership: `pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:tui`.

## First route map

Use this order for a first successful session, then deepen by surface.

```text
Install ──► Auth ──► Interactive session ──► RLM / harness
   │            │              │
   │            │              ├── daemon attach / resume
   │            │              ├── skills / extensions
   │            │              └── agentLoop / JSON·RPC
   └── doctor / update when background services misbehave
```

| Goal | Docs route |
|------|------------|
| Install binary, checksum, IPython prep | [Installation](/installation) |
| First project session | [Quickstart](/quickstart) |
| Login, API keys, provider boundaries | [Authentication and providers](/authentication-providers) |
| IPython control plane and `rlm(...)` | [RLM control plane](/rlm-control-plane) |
| Durable harness and refine | [Continual Harness](/continual-harness) |
| Session lifecycle and state | [Sessions and runtime](/sessions-runtime) |
| Background detach / reattach | [Run daemon-backed sessions](/daemon-sessions) |
| Long-running goals and autonomous budgets | [Long-running tasks](/long-running-tasks) |
| Minimal programmatic agent | [Minimal SDK agent](/sdk-minimal) |
| Build from source | [Develop from source](/develop-from-source) |

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Stable install command, release checksum flow, binary placement, IPython runtime prep, first-launch signals.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    Start in a project directory, complete onboarding, run a first task, verify interactive health.
  </Card>
  <Card title="Authentication and providers" href="/authentication-providers">
    Login and API-key paths, multi-provider selection, OAuth, auth recovery, BYOK boundaries.
  </Card>
  <Card title="RLM control plane" href="/rlm-control-plane">
    Persistent IPython, prompt-as-variable context, and `rlm(...)` subagent calls.
  </Card>
  <Card title="Continual Harness" href="/continual-harness">
    Durable prompts, memories, skill and subagent specs; refine boundaries and rollback snapshots.
  </Card>
  <Card title="Minimal SDK agent" href="/sdk-minimal">
    Copy-paste SDK bootstrap, prompt and model wiring, expected first-run output.
  </Card>
</CardGroup>