# PrimeAgent Codebase Architecture: How Functionality Is Organized Across Packages

> Discover how PrimeAgent organizes its codebase into loosely coupled TypeScript packages, separating UI, daemon, workers, kernel, and LLM providers for efficient development and maintainability.

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

---

**PrimeAgent splits its functionality into loosely-coupled TypeScript packages that separate the terminal UI, daemon supervisor, session workers, IPython kernel, and LLM providers into distinct layers.**

This modular organization enables PrimeIntellect-ai/prime-agent to maintain a lightweight presentation layer while keeping execution robust and extensible. The architecture follows a clear data flow: user input travels from the **TUI** through a **daemon supervisor** to **session workers**, which interact with an **IPython kernel** and **model providers** through a unified, type-safe API.

## PrimeAgent Package Structure Overview

The codebase divides responsibilities across seven primary layers. Each layer lives in its own package under the `packages/` directory, with clear boundaries between presentation, orchestration, execution, and infrastructure concerns.

| Layer | Package | Core Responsibility |
|-------|---------|---------------------|
| **User Interface** | `packages/tui` | Terminal rendering and keyboard input |
| **Daemon / Supervisor** | `packages/agent` | Process discovery, routing, and crash recovery |
| **Session Worker** | `packages/agent` | Root `AgentSession` execution and scheduling |
| **Model-Facing Runtime (RLM)** | `packages/coding-agent` | IPython kernel hosting and tool exposure |
| **Model Provider Layer** | `packages/ai` | LLM abstraction with unified event streaming |
| **Persistence & Harness** | `packages/ai` | Transcript storage and supplemental prompts |
| **Extensions / Skills** | `packages/coding-agent` | Dynamic plugin loading |

The source analysis reveals this organization in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md), which contains the canonical visual diagram of the system's data flow.

## How the UI Layer Is Organized in PrimeAgent

The **Terminal User Interface** lives in `packages/tui` and remains strictly separated from execution logic.

- **[`src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/tui.ts)** — Main TUI component that renders the interactive terminal interface
- **[`src/keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/keybindings.ts)** — Default keyboard shortcut mappings

This package captures keystrokes and forwards them over a local daemon protocol to the supervisor. It never directly manipulates session state or executes code, maintaining the architectural boundary between presentation and execution.

## PrimeAgent Daemon and Session Worker Organization

The **`packages/agent` package** implements both the supervisor and worker layers through distinct runtime modes.

### Daemon Supervisor Components

- **[`src/agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/agent.ts)** — Entry point for the daemon; handles process discovery, routing, attachments, and worker crash recovery
- **[`src/agent-loop.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/agent-loop.ts)** — Main event loop that processes messages and state transitions

### Session Worker Components

- **[`src/agent-session-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/agent-session-runtime.ts)** — Generated at runtime; hosts a single root `AgentSession`
- **[`src/scheduler.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/scheduler.ts)** — Schedules autonomous execution turns for the agent

The supervisor routes user requests to appropriate workers, while each worker maintains its own `AgentSession`, transcript, scheduler, and reference to an IPython kernel. This design allows multiple independent sessions to run concurrently under a single daemon.

## IPython Kernel and Model Runtime Architecture

The **`packages/coding-agent` package** implements the **RLM (Runtime Language Model)** layer. This is the **only** tool exposed to the LLM—all file operations, shell commands, skill loads, and sub-agent delegation flow through this kernel.

Key source files:

- **[`src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/index.ts)** — Public CLI and runtime entry point exports
- **[`src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/cli.ts)** — Command-line parsing and startup orchestration

The kernel bootstraps an `ipython` tool that exposes functions like `rlm(...)` for spawning recursive sub-agents. When the model needs to execute Python, call system commands, or delegate to child agents, all requests pass through this single, well-typed bridge.

This centralization ensures the TypeScript host maintains complete observability and control over all model-originated actions.

## PrimeAgent Model Provider Layer Organization

The **`packages/ai` package** abstracts all LLM providers behind a unified streaming interface.

Core abstraction files:

- **[`src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/types.ts)** — Shared TypeScript definitions for streams, events, and provider configurations
- **[`src/stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/stream.ts)** — Generic streaming interface consumed by all higher layers
- **[`src/bedrock-provider.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/bedrock-provider.ts)** — Example implementation showing how to add a custom provider

The provider layer streams unified event types: `text`, `tool_call`, `thinking`, and others. This normalization allows `AgentSession` to work with OpenAI, Anthropic, Google, Bedrock, or custom providers without code changes.

Adding a new provider requires implementing the `StreamOptions` interface and registering in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts).

## Persistence and Extension System Design

### Session Resources and Transcripts

Also within **`packages/ai`**:

- **[`src/session-resources.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/session-resources.ts)** — Handles JSONL transcript persistence and "continual harness" state

The harness stores supplemental prompts, memories, and skill descriptions separately from the immutable base system prompt. Users can refine this context with the `/refine` command without rebuilding core behavior.

### Dynamic Extensions and Skills

The **`packages/coding-agent`** package supports runtime extension loading:

- **[`src/extensions.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/extensions.ts)** — Discovery, registration, and lifecycle management of extensions

Extensions are dynamically loadable npm packages that contribute:

- Custom tools accessible through the IPython kernel
- New slash commands
- Additional UI panels
- Theme modifications

Load an extension at startup:

```bash
prime-agent -e ./my-extension.ts

```

The extension exports a `register` function receiving the `ExtensionRegistry`, enabling additive functionality without modifying core source.

## Practical Code Examples

### Launching Sessions

```bash
prime-agent                     # New TUI session with fresh worker

prime-agent -c                  # Continue most recent session

prime-agent --resume 12345      # Resume specific saved session

```

*Source*: [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts)

### Switching Models at Runtime

```text
/model openai/gpt-4o

```

Parsed by the CLI and propagated to the current `AgentSession`'s provider configuration in [`packages/agent/src/agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/agent.ts).

### Spawning Recursive Sub-Agents

```python

# Inside IPython kernel prompt

review = await rlm(
    "Check the security of the current repository and report findings.",
    name="security-reviewer",
)

```

Creates a child `AgentSession` sharing the parent's provider and scheduler. Implementation spans [`packages/agent/src/agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/agent.ts) (child management) and [`packages/coding-agent/src/ipython-tool.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/ipython-tool.ts) (kernel bridge).

### Implementing a Custom Provider

```ts
// ./my-provider.ts
import { stream, StreamOptions } from 'prime-agent/ai';

export async function* streamMyProvider(opts: StreamOptions) {
  // Translate opts to provider-specific HTTP request
  // Yield unified events: { type: 'text', text: '...' }
}

```

Register lazily in the built-in providers registry. Reference [`bedrock-provider.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/bedrock-provider.ts) for complete implementation patterns.

## Summary

PrimeAgent's functionality organization follows these architectural principles:

- **Strict separation of concerns** — UI (`tui`), orchestration (`agent`), execution (`coding-agent`), and infrastructure (`ai`) remain independent packages
- **Single kernel bridge** — The IPython kernel in `coding-agent` is the sole tool exposed to LLMs, centralizing security and observability
- **Unified provider abstraction** — All LLM providers implement the same streaming interface in `packages/ai`
- **Runtime extensibility** — Extensions load dynamically without recompilation via [`packages/coding-agent/src/extensions.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/extensions.ts)
- **Immutable core, mutable harness** — Session transcripts append-only in JSONL; supplemental context refines separately via [`session-resources.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/session-resources.ts)

This package structure enables PrimeAgent to add new model providers, UI components, or execution capabilities without modifying the core runtime loop.

## Frequently Asked Questions

### What is the main entry point for PrimeAgent?

The CLI entry point is [`packages/coding-agent/src/cli.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/cli.ts), which parses arguments and delegates to either the TUI launcher or direct session resumption. The TUI itself lives in [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) and communicates with the daemon supervisor via local protocol.

### How does PrimeAgent isolate the UI from code execution?

The TUI package (`packages/tui`) contains only presentation logic—terminal rendering and input handling. All execution happens in separate worker processes managed by the daemon in `packages/agent`. The TUI never directly accesses the IPython kernel or file system; all actions route through the supervisor's message protocol.

### Can I add support for a new LLM provider without modifying core code?

You can implement a custom provider by creating a module that exports a streaming generator conforming to `StreamOptions` from `packages/ai`, then register it in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/providers/register-builtins.ts). For purely external extensions, the dynamic loading system in [`packages/coding-agent/src/extensions.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/extensions.ts) may also support provider plugins in future versions.

### What is the "continual harness" in PrimeAgent?

The continual harness is mutable context stored alongside the immutable session transcript. It contains refined prompts, accumulated memories, and skill descriptions that evolve during a session. Stored via [`packages/ai/src/session-resources.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/session-resources.ts), it allows the `/refine` command to update agent behavior without altering the base system prompt.