Understanding the `packages` Directory in PrimeIntellect-ai/prime-agent: A Complete Architecture Guide

The packages directory in PrimeIntellect-ai/prime-agent contains three independent, publishable TypeScript packages—ai, agent, and tui—that together implement a complete LLM-powered agent system with modular AI providers, runtime orchestration, and terminal UI rendering.

This guide explains how these packages interlock, what each one exposes, and how to use them based on the actual source code structure from the Prime Intellect repository.

---

Package Structure Overview

The packages/ folder follows a monorepo workspace pattern with lockstep versioning. Each package maintains its own package.json, tsconfig.build.json, and source tree, but they are designed to be consumed together via the root prime-agent.sh entry script.

The Three Core Packages

Package	Purpose	Key Responsibilities
ai	LLM abstraction layer	Unified streaming API, provider implementations (OpenAI, Anthropic, Bedrock), model discovery, caching, and credential handling
agent	Agent runtime orchestration	MCP protocol handling, CLI entry points, tool registry, and session-wide resources
tui	Terminal user interface	Virtual terminal rendering, input handling, undo/redo stack, and theming

---

The ai Package: Unified LLM Interface

All model interactions flow through packages/ai. This package shields consumers from provider-specific details by normalizing streaming events into a common format.

Core Streaming API

The main entry point is stream() in packages/ai/src/stream.ts. It returns an AssistantMessageEventStream that emits normalized events:

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

await stream({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explain quantum tunnelling.' }],
  onEvent: (event) => {
    if (event.type === 'text') {
      process.stdout.write(event.text);
    }
    if (event.type === 'tool_call') {
      console.log('\n[Tool call]', event.name);
    }
  },
});

Event types include text, tool_call, thinking, usage, and stop—enabling consistent handling across OpenAI, Anthropic, and AWS Bedrock providers.

Provider Architecture

Each LLM provider implements a common interface. The Bedrock implementation in packages/ai/src/bedrock-provider.ts demonstrates how non-OpenAI services integrate:

• Credential detection via packages/ai/src/env-api-keys.ts
• Model enumeration from packages/ai/src/models.ts
• Response normalization to the standard event stream

Model metadata is auto-generated in packages/ai/src/models.generated.ts by the generate-models.ts script, ensuring pricing and capability data stays current.

---

The agent Package: Runtime and Protocol

While ai handles model communication, agent manages session lifecycle, tool execution, and the Model Context Protocol (MCP).

MCP Protocol Handling

The packages/agent/src/mcp.ts file implements the multiplexed client protocol that connects the TUI frontend to backend agent processes. MCP enables:

• Streaming message exchange between UI and agent
• Tool result propagation
• Session state synchronization

CLI Entry Point

Interactive sessions boot through packages/agent/src/cli.ts:

import { runAgent } from '@prime-agent/agent';

runAgent({
  onMessage: (msg) => console.log('[Agent]', msg.content),
  onToolCall: (tool) => console.log('[Tool]', tool.name, tool.args),
});

This function orchestrates model selection (delegating to packages/ai), tool registry initialization, and MCP server startup.

---

The tui Package: Terminal Rendering Engine

The tui package provides a full-screen terminal interface built on virtual terminal principles, not simple line-based output.

High-Level UI API

Start the interface via packages/tui/src/utils.ts:

import { startTUI } from '@prime-agent/tui';

startTUI({
  title: 'Prime Agent Demo',
  onExit: () => process.exit(0),
});

Internal Architecture

Component	File	Function
Rendering engine	src/ (multiple render modules)	Virtual terminal buffer management
Input handling	src/utils.ts	Key event translation to MCP commands
Undo system	src/undo-stack.ts	Editable buffer history management

The tui package includes extensive test coverage (files like tui-render.test.ts) validating rendering correctness, edge cases, and key handling across terminal emulators.

---

How the Packages Wire Together

The root prime-agent.sh script demonstrates the integration pattern:

1. Boot the daemon and configuration loader
2. Load the ai package to resolve API keys and models via packages/ai/src/env-api-keys.ts
3. Start the MCP server from packages/agent/src/mcp.ts
4. Attach the TUI frontend, which connects via MCP and renders events from packages/ai/src/stream.ts

This separation allows independent evolution: adding Claude 4 support modifies only packages/ai; building a web UI replacement requires only a new frontend that speaks MCP.

---

Key Files Reference

Package	File	Purpose
ai	src/index.ts	Public API exports (stream, modelInfo)
ai	src/stream.ts	Core streaming implementation
ai	src/env-api-keys.ts	Credential detection from environment
ai	src/models.generated.ts	Auto-generated model catalog
ai	src/bedrock-provider.ts	AWS Bedrock provider example
agent	src/mcp.ts	MCP protocol implementation
agent	src/cli.ts	CLI session entry
tui	src/utils.ts	UI startup and input handling
tui	src/undo-stack.ts	Buffer history management

---

Summary

• packages/ai provides a provider-agnostic streaming interface for LLM interactions with normalized events and auto-generated model metadata
• packages/agent implements the MCP protocol and session orchestration, bridging AI capabilities with tool execution
• packages/tui delivers a virtual terminal UI with rendering, input handling, and comprehensive test coverage
• The monorepo structure enables independent package versioning while the root prime-agent.sh script coordinates them into a cohesive application
• Source files like packages/ai/src/stream.ts, packages/agent/src/mcp.ts, and packages/tui/src/utils.ts define the public APIs for each layer

---

Frequently Asked Questions

What is the purpose of the packages directory in prime-agent?

The packages directory organizes the codebase into three modular, publishable TypeScript packages: ai for LLM abstraction, agent for runtime orchestration, and tui for terminal UI. This separation enables independent development, testing, and versioning of each subsystem while maintaining clean architectural boundaries between model interaction, protocol handling, and user interface concerns.

How does the ai package handle multiple LLM providers?

The ai package uses a provider pattern where each service (OpenAI, Anthropic, Bedrock) implements a common interface. The stream() function in packages/ai/src/stream.ts normalizes all responses into a unified AssistantMessageEventStream with standard event types. Provider-specific logic for credentials, model discovery, and response parsing is encapsulated in individual files like packages/ai/src/bedrock-provider.ts.

What is MCP and where is it implemented?

MCP (Model Context Protocol) is a multiplexed communication protocol that connects the terminal UI to the agent backend. It is implemented in packages/agent/src/mcp.ts. MCP enables streaming message exchange, tool result propagation, and session state synchronization between the tui frontend and the orchestration logic in the agent package.

Can I use the ai package without the TUI?

Yes. The ai package is designed for standalone usage. Import stream or streamSimple from packages/ai/src/index.ts and provide your own message handling logic. The agent and tui packages are optional dependencies for building interactive sessions; headless automation scripts can consume ai directly with no terminal UI overhead.

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