PrimeAgent Packages Explained: A Deep Dive into the Monorepo Architecture

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, 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 documents the public API surface, while 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. 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 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 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 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	Main application coordinator and layout manager
terminal.ts	Low-level terminal control and rendering
keybindings.ts	Configurable keyboard shortcuts
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 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 and documentation in 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, 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 initializes a fresh conversation and runs to completion. agentLoopContinue accepts saved state to resume a previous session, enabling persistent conversations across process restarts.

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