# Prime‑Agent Main Components: A Deep Dive into the PrimeIntellect‑ai/prime‑agent Architecture

> Explore the PrimeIntellect-ai/prime-agent architecture. Discover its core components: tui, agent, ai, and coding-agent, forming a full-stack autonomous coding agent.

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

---

**PrimeIntellect‑ai/prime‑agent is a monorepo containing four loosely‑coupled packages—`tui`, `agent`, `ai`, and `coding-agent`—that together form a full‑stack autonomous coding agent with a terminal UI, unified LLM streaming, and extensible tool orchestration.**

The **PrimeIntellect‑ai/prime‑agent** project implements a modular agent system where each layer handles a distinct concern: user interaction, agent lifecycle, LLM abstraction, and high‑level coding workflows. The architecture emphasizes clean separation between rendering, orchestration, and provider‑specific implementation details.

## The Four Core Packages of Prime‑Agent

The repository organizes functionality into **four primary packages**, each with well‑defined responsibilities and entry points.

### TUI: Terminal User Interface Layer

The **`tui`** package delivers a fully‑featured terminal UI that renders chat, code editors, markdown, image previews, and interactive overlays. This is the surface you interact with when running [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh).

- **[`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts)** – The main renderer that orchestrates view updates, handles user input events, and manages the overall layout.
- **[`packages/tui/src/terminal.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/terminal.ts)** – Low‑level terminal abstraction handling cursor positioning, raw mode, and terminal resize events.

The TUI remains strictly presentation‑focused—it consumes events from the agent layer and renders them, but contains no business logic about LLM providers or tool execution.

### Agent: Core Message Queue and Lifecycle

The **`agent`** package provides the generic **`Agent`** class and the **agent‑loop** that manages request/response cycles, retries with exponential back‑off, and error recovery.

- **[`packages/agent/src/agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/agent.ts)** – Implements the `Agent` class with message queuing and state management.
- **[`packages/agent/src/agent-loop.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/agent-loop.ts)** – Contains the event loop that drives the asynchronous request/response cycle.

This layer abstracts away the complexity of reliable message delivery, allowing higher layers to focus on orchestration rather than connection resilience.

### AI: Unified LLM Provider Engine

The **`ai`** package supplies a **unified streaming API** for multiple large‑language‑model providers including OpenAI, Anthropic, Google, and AWS Bedrock. It handles credential auto‑detection, model catalog generation, and token‑usage diagnostics.

- **[`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)** – Public API exports for the LLM abstraction layer.
- **[`packages/ai/src/stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/stream.ts)** – Core streaming abstraction that normalizes events across all providers.
- **`packages/ai/src/providers/*`** – Provider‑specific implementations (e.g., `openai‑completions.ts`, [`anthropic.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/anthropic.ts)).

The streaming interface emits normalized events: `text`, `tool_call`, `thinking`, `usage`, and `stop`. Provider modules translate these to and from HTTP‑specific formats.

### Coding‑Agent: High‑Level Orchestration Framework

The **`coding-agent`** package is the **top‑level orchestration layer** that runs autonomous coding agents. It manages sessions, tools, skill blocks, slash‑commands, telemetry, and wires the UI to the LLM engine.

- **[`packages/coding-agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/index.ts)** – Top‑level API for creating and running sessions.
- **[`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts)** – Session lifecycle, tool orchestration, and message handling.
- **[`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts)** – Built‑in tool definitions (file system, web search, image generation).

This package bridges all lower layers: it receives user input from the TUI, decides which LLM to call through the `ai` package, manages tool execution, and streams results back to the UI.

## How the Prime‑Agent Components Connect

The data flow through the system follows five sequential stages:

1. **Startup** – [`./prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/./prime-agent.sh) starts the **daemon** (background Node process) and launches the **TUI** in the foreground.

2. **UI → Agent** – [`tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tui.ts) sends user input to the **Agent** ([`agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent.ts)), which queues the message and forwards it to the **Coding‑Agent** runtime.

3. **Agent → LLM** – The **Coding‑Agent** selects a provider, builds the request, and streams through the **AI** layer ([`stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/stream.ts)). Provider modules handle HTTP translation.

4. **LLM → UI** – The **AI** layer normalizes events and pushes them back up: **Coding‑Agent** → **Agent** → **TUI** for live rendering.

5. **Tool Execution** – During processing, **Coding‑Agent** invokes tools from [`core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/core/skills.ts), streaming intermediate results (e.g., image previews) through the same pipeline.

## Using Prime‑Agent Components Programmatically

### Running the Full Application

```bash

# From the repository root

./prime-agent.sh

```

The script internally executes `node ./packages/coding-agent/src/cli-main.ts` before launching the TUI.

### Instantiating the Agent Core

```ts
import { Agent } from '@prime-agent/agent';

const agent = new Agent({
  model: 'gpt-4o',
  temperature: 0.7,
});

await agent.sendMessage('Explain the difference between REST and GraphQL.');

```

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

### Direct LLM Streaming

```ts
import { stream } from '@prime-agent/ai';

await stream({
  api: 'openai-chat',
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a short poem about sunrise.' }],
  onEvent: (event) => console.log(event.text),
});

```

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

### Registering Custom Tools

```ts
import { registerTool } from '@prime-agent/coding-agent';

registerTool('currentDate', async () => {
  return new Date().toISOString();
});

await agent.sendMessage('What is the date today? Use @currentDate.');

```

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

## Support Scripts and Utilities

The `scripts/` directory contains helper tools for development and operations:

- **[`scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/generate-models.ts)** – Generates [`models.generated.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/models.generated.ts) from provider catalogs.
- **`scripts/bench-daemon-startup.mjs`** – Benchmarks daemon startup latency.
- **[`scripts/cost.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/cost.ts)** – Calculates estimated inference costs across providers.

## Summary

- **Prime‑Agent** is structured as a **four‑layer monorepo**: `tui` (UI), `agent` (lifecycle), `ai` (LLM abstraction), and `coding-agent` (orchestration).
- Each package has **clear entry points**: [`tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tui.ts), [`agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent.ts), [`stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/stream.ts), and [`agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session.ts) respectively.
- The **`ai` package** normalizes streaming across **OpenAI, Anthropic, Google, and Bedrock** through a unified event interface.
- **Tool execution** is handled in the **Coding‑Agent layer**, with built‑in skills defined in [`skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/skills.ts) and extensible via `registerTool()`.
- **[`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh)** serves as the thin bootstrap wrapper that wires all layers together.

## Frequently Asked Questions

### What is the difference between the `agent` and `coding-agent` packages?

The **`agent`** package provides a **generic, reusable `Agent` class** that handles message queuing, retries, and back‑off—suitable for any async request/response pattern. The **`coding-agent`** package builds on top of it, adding **session management, tool orchestration, slash‑commands, and telemetry** specifically for autonomous coding workflows. Think of `agent` as infrastructure and `coding-agent` as the application layer.

### How does Prime‑Agent handle multiple LLM providers?

The **`ai` package** abstracts provider differences through a **unified streaming interface** ([`stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/stream.ts)). Provider modules in `packages/ai/src/providers/` translate generic requests into provider‑specific HTTP calls and normalize responses into standard events. This allows the upper layers to switch between OpenAI, Anthropic, or Bedrock by changing a configuration string without code changes.

### Can I use the Prime‑Agent components outside the terminal UI?

Yes. Each package is **loosely coupled** and can be imported independently. The **`Agent`** class from `@prime-agent/agent` can be instantiated programmatically, and the **`ai`** streaming API works in any Node.js context. The TUI is simply one consumer of these lower‑level APIs—you could build a web interface, CLI tool, or background service using the same core components.

### Where are custom tools and skills defined?

Custom tools are registered through the **`registerTool()`** function exported from `@prime-agent/coding-agent`. Built‑in tools (file system, web search, image generation) are defined in **[`packages/coding-agent/src/core/skills.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/skills.ts)**. Both use the same registry mechanism, so custom tools receive identical streaming and error‑handling treatment as first‑party features.