# Prime Intellect Prime Agent Project Structure: Complete Architecture Guide

> Understand the Prime Intellect prime-agent project structure. This guide details the architecture of the monorepo, including TypeScript packages, Python daemon, and npm workspace organization for AI, Agent, and TUI.

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

---

**The Prime Intellect prime-agent repository is a monorepo containing three TypeScript packages (AI, Agent, TUI), a Python runtime daemon, and helper scripts, organized as an npm workspace with clear separation between LLM providers, orchestration logic, and terminal UI rendering.**

The **prime-agent** project powers an LLM-driven coding assistant that runs entirely in your terminal. Understanding its project structure is essential for contributors extending the system, developers integrating its components, or operators customizing agent behavior. This guide breaks down every directory and key file based on the actual source code in `PrimeIntellect-ai/prime-agent`.

## Top-Level Directory Layout

The repository root follows standard monorepo conventions with workspace configuration at the top and implementation code nested in `packages/`:

```

prime-agent/
├── README.md                 # Overview and quick-start

├── package.json             # Workspace root configuration

├── tsconfig*.json           # TypeScript project references

├── prime-agent.sh           # CLI entry point

├── scripts/                 # Build, release, and diagnostic utilities

├── packages/
│   ├── ai/                  # LLM provider abstraction

│   ├── agent/               # Agent orchestration and session management

│   └── tui/                 # Terminal user interface

├── prime-agent-runtime/     # Python daemon (MCP, skills, subprocesses)

├── assets/                  # Icons and visual resources

├── AGENTS.md               # Built-in agent documentation

└── .github/                # CI workflows and templates

```

All TypeScript packages share a single npm workspace, enabling cross-package type checking with `npm run check`. The Python runtime remains isolated with its own [`pyproject.toml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/pyproject.toml).

## Core TypeScript Packages

### packages/ai: LLM Provider Abstraction

The **AI package** wraps multiple LLM providers behind a unified streaming API. It handles model discovery, request normalization, and response streaming.

Key files:

- [`/packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/ai/src/types.ts) — Central type definitions for LLM events, model descriptors, and provider options
- [`/packages/ai/src/stream.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/ai/src/stream.ts) — Implements `stream()` and `streamSimple()` functions used across the project
- [`/packages/ai/src/models.generated.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/ai/src/models.generated.ts) — Auto-generated model registry supporting OpenAI, Anthropic, and Bedrock

Usage example:

```typescript
import { stream } from "packages/ai/src/stream";
import { OpenAIProvider } from "packages/ai/src/providers/openai";

const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! });
const opts = { model: "gpt-4o-mini", temperature: 0.7 };

for await (const ev of stream(provider, "Explain recursion in Python.", opts)) {
  if (ev.type === "text") process.stdout.write(ev.text);
}

```

### packages/agent: Session Orchestration

The **Agent package** manages high-level interaction flow: maintaining conversation state, deciding when to call tools, and coordinating with the Python daemon for code execution.

Key files:

- [`/packages/agent/src/agent.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/agent/src/agent.ts) — Core `Agent` class that exposes `run()` and manages session lifecycle
- [`/packages/agent/src/agent-loop.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/agent/src/agent-loop.ts) — Turn-taking logic that processes LLM responses, executes tools, and loops until completion

The agent implements the "coding-agent" workflow where LLM responses may trigger file edits, terminal commands, or skill invocations handled by the Python side.

### packages/tui: Terminal User Interface

The **TUI package** renders the interactive terminal experience using a custom component system. It handles keyboard input, markdown rendering, editor integration, and real-time output streaming.

Key files:

- [`/packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/tui/src/tui.ts) — Main `TUI` class coordinating all UI components
- [`/packages/tui/src/terminal.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//packages/tui/src/terminal.ts) — Low-level terminal control and screen buffer management

The TUI forwards user input to the Agent layer and displays streamed tokens as they arrive from the AI provider.

## Python Runtime: prime-agent-runtime

The **prime-agent-runtime** directory contains a separate Python codebase that runs as a daemon process. It implements:

- **MCP (Multi-Channel Protocol)** — Wire protocol for TypeScript-to-Python communication
- **Skill loading** — Dynamic loading of Python capabilities the agent can invoke
- **Subprocess supervision** — Sandboxed execution of shell commands and code

Key file: [`/prime-agent-runtime/src/rlm/skill.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//prime-agent-runtime/src/rlm/skill.py) — Example skill implementation for file operations and process execution.

When the TypeScript agent needs to perform an action like writing a file, it serializes the request to the Python daemon, which loads the appropriate skill and returns structured results.

## Entry Point and Scripts

### prime-agent.sh

The shell script at [`/prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//prime-agent.sh) serves as the primary CLI entry point. It:

1. Validates environment configuration
2. Launches the Node.js runtime
3. Boots the TUI with the default `coding-agent`

Starting the interactive agent:

```bash

# From repository root

./prime-agent.sh

```

### scripts/ Directory

Contains auxiliary utilities for:

- Build orchestration across the monorepo
- Release automation and versioning
- Cost tracking for LLM API usage
- Browser build smoke testing
- Performance profiling

## Documentation and Configuration

| Path | Purpose |
|------|---------|
| [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) | Catalog of built-in agents, their capabilities, and usage patterns |
| [`packages/ai/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/README.md) | Provider integration guide and model configuration |
| [`packages/tui/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/README.md) | UI customization, keybindings, and component extensions |
| [`.github/workflows/ci.yml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.github/workflows/ci.yml) | Continuous integration pipeline |

## Architectural Data Flow

Understanding how components interact clarifies the project structure:

1. **Entry**: [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) launches Node.js and initializes the TUI
2. **Input**: TUI captures keystrokes and forwards to Agent
3. **Orchestration**: Agent maintains session state, selects AI provider, and calls `stream()` from the AI package
4. **LLM Response**: Tokens stream back through the TUI for display; tool calls route to the Python daemon
5. **Execution**: Python daemon loads skills (e.g., [`/prime-agent-runtime/src/rlm/skill.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main//prime-agent-runtime/src/rlm/skill.py)) and returns results
6. **Loop**: Agent incorporates results and continues the conversation

## Summary

- **Monorepo structure**: Three TypeScript packages (`ai`, `agent`, `tui`) plus Python runtime, managed as npm workspace
- **Clear separation**: LLM providers abstracted in `packages/ai`, orchestration in `packages/agent`, UI in `packages/tui`
- **Polyglot runtime**: TypeScript frontend communicates with Python daemon via MCP for sandboxed code execution
- **Entry point**: [`prime-agent.sh`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/prime-agent.sh) bootstraps the complete system
- **Key extension points**: Add providers in `packages/ai/src/providers/`, skills in `prime-agent-runtime/`, agents via [`AGENTS.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/AGENTS.md) patterns

## Frequently Asked Questions

### What programming languages does prime-agent use?

The project uses **TypeScript** for the client, orchestration, and UI layers, and **Python** for the daemon runtime that handles skill execution and subprocess management. The TypeScript side resides in `packages/` while Python code lives in `prime-agent-runtime/`.

### How do I add a new LLM provider to prime-agent?

Create a new provider class in `packages/ai/src/providers/` following the interface defined in [`packages/ai/src/types.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/types.ts). Register your provider in the model registry and implement `stream()` and `streamSimple()` methods. The AI package normalizes all provider responses to a common event format.

### What is the relationship between the Agent and TUI packages?

The **TUI** (`packages/tui/`) is strictly a presentation layer that renders output and captures input. The **Agent** (`packages/agent/`) contains all business logic for session management, tool selection, and LLM coordination. They communicate through well-defined interfaces, allowing the Agent to function headless if needed.

### How does the Python daemon communicate with the TypeScript side?

The Python runtime implements **MCP (Multi-Channel Protocol)** for structured communication. The TypeScript Agent serializes tool invocation requests over stdio or a socket, the Python daemon loads and executes the requested skill (e.g., [`skill.py`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/skill.py)), and returns JSON results that the Agent incorporates into the conversation state.