How to Import Components from PrimeAgent's Packages: Complete Guide

PrimeAgent uses npm workspaces to publish three runtime packages—@earendil-works/pi-ai, @earendil-works/pi-agent-core, and @earendil-works/pi-tui—with all public symbols exported through centralized index.ts files for clean, tree-shakable imports.

The PrimeAgent repository is structured as a TypeScript monorepo where each major subsystem lives in its own package under packages/. Every package re-exports its public API through a single entry point, making imports predictable whether you're building AI-powered features, orchestrating agent sessions, or constructing terminal interfaces.

Understanding PrimeAgent's Package Structure

PrimeAgent organizes functionality across three primary packages:

Package	NPM Name	Purpose	Source Entry
AI Layer	@earendil-works/pi-ai	LLM providers, streaming, model registry	[packages/ai/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)
Core Agent	@earendil-works/pi-agent-core	Agent loop, sessions, proxy utilities	[packages/agent/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts)
Terminal UI	@earendil-works/pi-tui	Interactive components, editors, keybindings	[packages/tui/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts)

Each package is declared as a workspace in the root [package.json](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json), enabling npm to resolve cross-package dependencies during development.

Basic Import Patterns

Importing from Package Names

The standard pattern imports directly from the published package name. This works because each package's index.ts re-exports all public symbols.

// AI utilities and types
import { stream, ModelRegistry, type StreamEvent } from "@earendil-works/pi-ai";

// Agent session management
import {
  createAgentSession,
  AgentSession,
  type PromptOptions,
} from "@earendil-works/pi-agent-core";

// Terminal UI components
import { Box, Editor, Loader, Markdown, TUI } from "@earendil-works/pi-tui";

Provider-Specific Sub-Path Imports

The AI package exposes provider-specific option types through sub-path exports defined in [packages/ai/package.json](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json). This keeps the main namespace clean while allowing precise type imports.

// Anthropic provider configuration
import type { AnthropicOptions } from "@earendil-works/pi-ai/anthropic";

// OpenAI completions configuration
import type { OpenAICompletionsOptions } from "@earendil-works/pi-ai/openai-completions";

// Google Vertex configuration
import type { GoogleVertexOptions } from "@earendil-works/pi-ai/google-vertex";

These sub-paths resolve through the exports field in the AI package's package.json, which maps each provider route to its corresponding compiled module.

Practical Code Examples

Streaming LLM Responses

This example demonstrates importing core AI utilities from [packages/ai/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts) to stream a response:

import { stream, ModelRegistry } from "@earendil-works/pi-ai";

async function streamExplanation() {
  const model = ModelRegistry.getModel("openai:gpt-4");

  const response = await stream({
    model,
    messages: [{ role: "user", content: "Explain quantum tunneling." }],
  });

  for await (const event of response) {
    if (event.type === "text") {
      process.stdout.write(event.content);
    }
  }
}

streamExplanation();

Creating and Running an Agent Session

Core agent functionality comes from [packages/agent/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts):

import {
  createAgentSession,
  AgentSession,
  type PromptOptions,
} from "@earendil-works/pi-agent-core";

async function initializeAgent() {
  const session: AgentSession = await createAgentSession({
    model: "openai:gpt-4o-mini",
    promptOptions: { effort: "medium" } as PromptOptions,
  });

  await session.run(); // Starts the interactive agent loop
}

initializeAgent();

Building Terminal Interfaces

UI components export from [packages/tui/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts):

import { Box, Editor, Loader, Markdown, TUI } from "@earendil-works/pi-tui";

function buildInterface() {
  const tui = new TUI({
    components: [
      new Box({ title: "PrimeAgent", content: "Interactive session" }),
      new Editor({ placeholder: "Enter command..." }),
      new Loader(),
      new Markdown({ markdown: "# Status\n**System operational**" }),

    ],
  });

  tui.run();
}

buildInterface();

Using Provider-Specific Types

For compile-time type safety with provider configurations:

import type { OpenAICompletionsOptions } from "@earendil-works/pi-ai/openai-completions";

function configureOpenAI(opts: OpenAICompletionsOptions): void {
  // opts is fully typed according to OpenAI's completions API
  console.log(opts.model, opts.temperature, opts.max_tokens);
}

Key Implementation Files

Understanding these source files helps troubleshoot import issues and explore available APIs:

File	Package	Significance
[packages/ai/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)	@earendil-works/pi-ai	Exports stream, ModelRegistry, and core LLM types
[packages/ai/package.json](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json)	@earendil-works/pi-ai	Defines exports map enabling ./anthropic, ./openai-completions, etc.
[packages/agent/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts)	@earendil-works/pi-agent-core	Exports createAgentSession, AgentSession, and proxy utilities
[packages/tui/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts)	@earendil-works/pi-tui	Exports all UI primitives and terminal helpers
[package.json](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)	Root	Declares workspaces and manages monorepo dependencies

Summary

• Import from package names: Use @earendil-works/pi-ai, @earendil-works/pi-agent-core, and @earendil-works/pi-tui for all public APIs
• Centralized exports: Each package routes through its index.ts, ensuring consistent symbol availability
• Sub-path imports: Provider-specific types import from paths like @earendil-works/pi-ai/anthropic for granular type control
• Workspace resolution: The root package.json workspaces enable local development without publishing

Frequently Asked Questions

Why do some imports use sub-paths like /anthropic instead of the main package?

Sub-path imports reduce bundle size and namespace pollution. The AI package's [package.json](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json) defines exports entries that map these routes to specific modules, so you only load the provider types you actually need.

Can I import directly from source files instead of package names?

During local development with the monorepo cloned, TypeScript path mapping allows direct source imports. However, published code should always import from the package names to ensure compatibility with compiled distributions.

How do I discover all available exports from a package?

Check the index.ts file for each package: [packages/ai/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts), [packages/agent/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts), and [packages/tui/src/index.ts](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts). These files explicitly list all public re-exports, serving as the definitive API reference.

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