# PrimeAgent Packages Explained: A Deep Dive into the Monorepo Architecture

> Explore the PrimeAgent monorepo architecture. Understand the distinct role of each of its four packages: LLM abstraction, agent runtime, coding tools, and terminal UI. Learn how they work together.

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

---

**PrimeAgent is organized as a four-package monorepo where each layer handles a distinct responsibility: LLM abstraction, agent runtime, coding tools, and terminal UI.**

PrimeAgent's modular architecture separates concerns into well-defined packages that compose into a complete agentic system. Understanding the role of each package helps developers extend, debug, and deploy the framework effectively. This article examines the four core packages in `PrimeIntellect-ai/prime-agent`, their source files, and how they integrate.

## The Four Core Packages in PrimeAgent

The repository uses a monorepo structure with four primary packages under the `packages/` directory. Each builds upon the layers below it, creating a clean dependency hierarchy from low-level LLM calls to high-level user interfaces.

### @earendil-works/pi-ai: Unified LLM API Layer

**`packages/ai`** provides the **unified LLM client** that all higher-level agents consume. This package abstracts provider-specific implementations behind a common interface for model discovery, streaming, tool calls, and multimodal inputs.

Key capabilities include:

- **Automatic model discovery** via [`scripts/generate-models.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/scripts/generate-models.ts), which builds the model registry at build time
- **Cross-provider hand-offs** for failover and routing between services like Anthropic, OpenAI, Google, and AWS Bedrock
- **Streaming and non-streaming completions** through `getModel`, `stream`, and `complete` functions
- **Native tool-call handling** with structured output parsing
- **Multimodal support** for image inputs and reasoning/thinking modes

The provider implementations live in `src/providers/` with dedicated folders for each service. Each provider folder contains adapter code that normalizes the native SDK responses into the package's internal format. The [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) documents the public API surface, while [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) declares the optional peer dependencies for each supported provider.

This package has no dependencies on the other PrimeAgent packages, making it suitable as a standalone LLM client for external projects.

### prime-agent-core: Stateful Agent Runtime

**`packages/agent`** implements the **core agent execution engine**. It transforms raw LLM calls into a managed conversation loop with persistent state, tool execution, and rich event emission.

The runtime centers on the `Agent` class exported from [`src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/index.ts). This class maintains:

- An array of `AgentMessage` objects representing the conversation history
- The tool execution loop that interleaves LLM calls with function invocations
- A comprehensive event stream for observability

The event system emits granular lifecycle signals: `agent_start`, `turn_start`, `message_update`, `tool_execution_start`, `tool_execution_complete`, and terminal states. UI layers subscribe to these events to render progress and state changes.

Key exports from [`src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/index.ts) include:

- `Agent` – the configurable agent instance
- `agentLoop` – runs a complete conversation from start to finish
- `agentLoopContinue` – resumes an existing conversation from saved state

The [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) details configuration options for max turns, timeout handling, and error recovery strategies. This package depends only on `@earendil-works/pi-ai` for LLM access.

### prime-agent-coding: Coding Assistant Extensions

**`packages/coding-agent`** adds **domain-specific tooling for software development tasks**. It extends the core agent with language-aware utilities, planning modes, and test-driven workflows.

This package is what powers the VS Code extension and the CLI `prime-agent` command when invoked with `coding` mode. Its responsibilities include:

- **File system operations**: read, write, edit, and refactor code files
- **Test execution integration**: run test suites and feed results back into the agent loop
- **Sub-agent spawning**: delegate tasks to specialized child agents for parallel work
- **Planning modes**: structured reasoning before code generation

The `examples/` subdirectory demonstrates extension patterns:

- `plan-mode/` – iterative planning before implementation
- `doom-overlay/` – gamified task management interface
- `subagent/` – hierarchical agent delegation

The [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) covers entry points for embedding the coding agent into IDEs or custom CLI tools. This package depends on `prime-agent-core` and `@earendil-works/pi-ai`.

### prime-agent-tui: Terminal User Interface

**`packages/tui`** delivers a **rich terminal interface** for interactive agent sessions. It renders the event stream from `prime-agent-core` into a navigable, keyboard-driven experience.

Core UI modules under `src/` include:

| Module | Function |
|--------|----------|
| [`tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/tui.ts) | Main application coordinator and layout manager |
| [`terminal.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/terminal.ts) | Low-level terminal control and rendering |
| [`keybindings.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/keybindings.ts) | Configurable keyboard shortcuts |
| [`undo-stack.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/undo-stack.ts) | Conversation history navigation with undo/redo |

Features include fuzzy-search through message history, inline image rendering using terminal graphics protocols, and real-time streaming display. The TUI subscribes to the core agent's event stream and maps each event type to appropriate visual updates.

The [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md) documents startup options and environment variables for customizing the interface. This package sits at the top of the dependency stack, consuming `prime-agent-core`.

## How the PrimeAgent Packages Work Together

The dependency flow follows a strict upward direction:

1. **`@earendil-works/pi-ai`** – Foundation layer with no internal PrimeAgent dependencies
2. **`prime-agent-core`** – Builds on the AI client to add conversation state and orchestration
3. **`prime-agent-coding`** – Adds domain logic for code tasks atop the core runtime
4. **`prime-agent-tui`** – Presents the complete stack through an interactive terminal

This architecture enables flexible deployment configurations. You can use:

- **Just the AI client** for custom agent implementations
- **Core + AI** for headless automation scripts
- **Full stack with TUI** for interactive development workflows
- **Coding agent in an IDE** through the VS Code extension entry point

## Summary

- **`@earendil-works/pi-ai`** in `packages/ai` abstracts multiple LLM providers behind a unified API with automatic model discovery
- **`prime-agent-core`** in `packages/agent` implements the stateful `Agent` class with message management, tool execution, and event emission
- **`prime-agent-coding`** in `packages/coding-agent/` extends the core with file operations, test integration, and sub-agent delegation for software tasks
- **`prime-agent-tui`** in `packages/tui` provides a keyboard-driven terminal interface with streaming display and conversation navigation
- Each package maintains clean boundaries with explicit exports in [`src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/index.ts) and documentation in [`README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/README.md)

## Frequently Asked Questions

### What package should I install to use PrimeAgent as a library?

Install **`prime-agent-core`** for the agent runtime or **`@earendil-works/pi-ai`** if you only need the LLM client. The coding agent and TUI are application-layer packages with heavier dependencies.

### How does the TUI receive updates from the agent?

The TUI subscribes to the event stream emitted by `prime-agent-core`. Events like `message_update` and `tool_execution_start` are mapped to screen updates in [`src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/tui.ts), enabling real-time rendering without polling.

### Can I add a new LLM provider without modifying other packages?

Yes. Add a new folder under `packages/ai/src/providers/` implementing the provider interface, then register it in the model generation script. The core agent and coding tools consume providers through the unified API and require no changes.

### What is the difference between `agentLoop` and `agentLoopContinue`?

`agentLoop` in [`packages/agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts) initializes a fresh conversation and runs to completion. `agentLoopContinue` accepts saved state to resume a previous session, enabling persistent conversations across process restarts.