PrimeAgent Package Modules: Complete Guide to the Monorepo Architecture

PrimeAgent is a TypeScript monorepo containing four core packages—@prime-agent/ai, @prime-agent/agent, @prime-agent/coding-agent, and @prime-agent/tui—each providing distinct capabilities for building AI-powered coding assistants.

This article breaks down the PrimeAgent package modules and their responsibilities based on the source code structure. Whether you're extending the framework or understanding its internals, knowing how these four modules interact is essential.

---

PrimeAgent Package Modules Overview

The repository follows a lock-step versioning strategy where all packages release together. This ensures API compatibility across the entire stack. The four PrimeAgent package modules are organized under the packages/ directory with clear separation of concerns.

Module	Purpose	Key Entry Point
@prime-agent/ai	Language model abstraction and provider implementations	packages/ai/src/index.ts
@prime-agent/agent	High-level agent runtime and orchestration	packages/agent/src/agent.ts
@prime-agent/coding-agent	Code generation and programming-specific tooling	packages/coding-agent/src/index.ts
@prime-agent/tui	Terminal user interface rendering and interaction	packages/tui/src/tui.ts

---

@prime-agent/ai: The Foundation Layer

The @prime-agent/ai package provides the language model abstraction layer that insulates the rest of the system from provider-specific implementations.

Core Capabilities

• Provider implementations for OpenAI, Anthropic, AWS Bedrock, and other LLM services
• Streaming utilities for real-time token delivery
• Model-selection logic for routing requests to appropriate backends

Key Source Files

According to the PrimeAgent source code, the AI package centers on:

• packages/ai/src/index.ts — Main export point for the module
• Provider-specific implementations such as bedrock-provider.js

Usage Example

// Import the AI layer and create a model stream
import { stream } from '@prime-agent/ai';

const modelStream = stream({ model: 'gpt-4o-mini' });

This establishes the base stream that higher-level modules consume.

---

@prime-agent/agent: Runtime Orchestration

The @prime-agent/agent package implements the agent runtime that coordinates tool usage, message handling, and interactive execution loops.

Core Responsibilities

• Tool coordination: Managing when and how the agent invokes external capabilities
• Message handling: Structuring conversation context and history
• Interactive loops: Managing the turn-based conversation flow

Key Source Files

The agent implementation in packages/agent/src/agent.ts serves as the primary orchestrator. Supporting files include:

• agent-loop.ts — Loop controller for managing conversation turns
• proxy.ts — Proxy utilities for intercepting and modifying behavior

Usage Example

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

const modelStream = stream({ model: 'gpt-4o-mini' });
const agent = new Agent({ stream: modelStream });

await agent.runPrompt('Explain the QuickSort algorithm.');

The Agent class consumes the AI stream and provides the high-level interface for prompt execution.

---

@prime-agent/coding-agent: Programming-Specific Capabilities

The @prime-agent/coding-agent package delivers coding assistant functionality built on top of the core agent layer.

Specialized Features

• Code generation with context-aware prompting
• Test harnesses for validating generated code
• Integration with the AI layer for model-powered programming tasks

Key Source Files

• packages/coding-agent/src/index.ts — Generated entry point
• docs/prompt-templates.md — Documented prompt engineering patterns

Usage Example

import { generate } from '@prime-agent/coding-agent';

await generate({
  prompt: 'Write a Jest test for a function that adds two numbers.',
  model: 'claude-3-opus',
});

This module demonstrates how domain-specific capabilities layer cleanly on top of the foundational packages.

---

@prime-agent/tui: Terminal User Interface

The @prime-agent/tui package provides a terminal-based UI for interactive sessions, enabling rich console experiences without leaving the command line.

Interface Components

• Chat rendering with syntax-highlighted code blocks
• Inline editors for modifying content directly in the terminal
• Overlays and modals for layered interface elements
• Key-binding handling for efficient keyboard navigation

Key Source Files

• packages/tui/src/tui.ts — Main TUI implementation
• src/undo-stack.ts — State management for reversible operations
• src/utils.ts — Shared utility functions

Usage Example

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

const agent = new Agent({ stream: modelStream });

runTUI({ agent });

The TUI accepts an agent instance and renders the complete interactive interface.

---

How the PrimeAgent Package Modules Interact

The dependency flow follows a bottom-up architecture:

@prime-agent/ai (foundation)
    ↓
@prime-agent/agent (orchestration)
    ↓
@prime-agent/coding-agent (domain layer) → @prime-agent/tui (presentation)

Each module imports only from layers below it, maintaining strict separation of concerns. The coding-agent and TUI both depend on the agent package but remain independent of each other.

---

Summary

• Four core packages constitute the PrimeAgent monorepo: ai, agent, coding-agent, and tui
• @prime-agent/ai handles all LLM provider abstraction and streaming
• @prime-agent/agent provides the runtime for tool use and conversation management
• @prime-agent/coding-agent adds programming-specific capabilities on top of the core agent
• @prime-agent/tui delivers terminal-based interaction without external dependencies
• Lock-step versioning ensures compatibility across all PrimeAgent package modules

---

Frequently Asked Questions

What is the entry point for each PrimeAgent package module?

Each package exports from a predictable location: @prime-agent/ai uses packages/ai/src/index.ts, @prime-agent/agent centers on packages/agent/src/agent.ts, @prime-agent/coding-agent exports from its generated packages/coding-agent/src/index.ts, and @prime-agent/tui starts at packages/tui/src/tui.ts.

Can I use the @prime-agent/ai package independently?

Yes. The AI package is designed as a standalone foundation layer. You can import stream and other utilities directly without pulling in the agent runtime or TUI components, making it suitable for custom LLM applications.

How does lock-step versioning work in PrimeAgent?

All four packages release together under a single synchronized version number. This eliminates version mismatch issues common in multi-package repositories and guarantees that any combination of packages from the same release will interoperate correctly.

Which PrimeAgent package module should I extend for custom tooling?

Start with @prime-agent/agent for general-purpose extensions or @prime-agent/coding-agent for programming-specific features. The modular architecture allows you to add capabilities without modifying core infrastructure.

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