Prime Intellect Prime Agent Project Structure: Complete Architecture Guide

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.

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 — Central type definitions for LLM events, model descriptors, and provider options
• /packages/ai/src/stream.ts — Implements stream() and streamSimple() functions used across the project
• /packages/ai/src/models.generated.ts — Auto-generated model registry supporting OpenAI, Anthropic, and Bedrock

Usage example:

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 — Core Agent class that exposes run() and manages session lifecycle
• /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 — Main TUI class coordinating all UI components
• /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 — 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 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:

# 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	Catalog of built-in agents, their capabilities, and usage patterns
packages/ai/README.md	Provider integration guide and model configuration
packages/tui/README.md	UI customization, keybindings, and component extensions
.github/workflows/ci.yml	Continuous integration pipeline

Architectural Data Flow

Understanding how components interact clarifies the project structure:

1. Entry: 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) 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 bootstraps the complete system
• Key extension points: Add providers in packages/ai/src/providers/, skills in prime-agent-runtime/, agents via 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. 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), and returns JSON results that the Agent incorporates into the conversation state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}