--- title: "Packages Overview" type: concept tags: [architecture, developer, foundational, well-established] created: 2026-08-05 updated: 2026-08-05 sources: ["raw/github_doc-packages-coding-agent-docs-packages-md.md", "raw/github_doc-packages-agent-readme-md.md", "raw/github_doc-packages-ai-readme-md.md", "raw/github_doc-packages-coding-agent-readme-md.md", "raw/github_doc-packages-tui-readme-md.md"] confidence: high prime_agent_version: "v0.7.0" --- ## Definition Prime Agent's monorepo layers four core npm workspace packages — `agent` (stateful agent runtime), `ai` (LLM provider toolkit), `coding-agent` (the CLI/product itself), and `tui` (terminal UI primitives) — plus a separate, unrelated concept also called "packages": user-installable **Prime Agent packages**, which bundle extensions, skills, prompt templates, and themes for distribution via npm or git. This page covers both: the internal package architecture and the external package-installation system. ## How It Works **`packages/agent` (published as `prime-agent-core`, source name inherited from `pi-mono`)** is the stateful agent runtime. Its `Agent` class wraps a message loop around `AgentMessage[]` state (`systemPrompt`, `model`, `thinkingLevel`, `tools`, `messages`), converting to LLM-native messages via a required `convertToLlm` function and optionally pruning/injecting context via `transformContext`. It emits a structured event sequence per prompt (`agent_start` → `turn_start` → `message_start`/`message_update`/`message_end` → `tool_execution_start`/`update`/`end` → `turn_end` → `agent_end`), supports `parallel` (default) or `sequential` tool execution (overridable per-tool via `executionMode`), `beforeToolCall`/`afterToolCall` hooks, steering and follow-up message queues (`steeringMode`/`followUpMode`, "one-at-a-time" or "all"), custom message types via TypeScript declaration merging, and a low-level `agentLoop`/`agentLoopContinue` API for callers who don't need the `Agent` class's barrier semantics around tool preflight. **`packages/ai` (published as `prime-agent-ai`)** is the unified LLM provider toolkit — "only includes models that support tool calling," since that's essential for agentic workflows. It exposes `stream`/`complete` (full event/provider control) and `streamSimple`/`completeSimple` (unified reasoning interface) over roughly two dozen providers (OpenAI, Anthropic, Google/Vertex, Mistral, Groq, Cerebras, Cloudflare, xAI, OpenRouter, Bedrock, GitHub Copilot, DeepSeek, and more — see [[concepts/providers-and-models]]), TypeBox-schema tool definitions with `validateToolCall`, streaming partial tool-call JSON, image input for vision models, thinking/reasoning content across providers, cross-provider handoff (thinking blocks from a different provider get converted to ``-tagged text), and OAuth flows for Anthropic/OpenAI Codex/GitHub Copilot via the `prime-agent-ai/oauth` entry point. A `registerFauxProvider()` helper registers a scripted in-memory provider for tests, used by `coding-agent`'s regression suite (see [[concepts/development]]). **`packages/coding-agent`** is the CLI product itself — the "RLM-native terminal coding and research harness." It composes `agent` and `ai` into the interactive TUI, the daemon (see [[concepts/daemon]]), sessions ([[concepts/sessions-and-compaction]]), settings ([[concepts/settings-and-customization]]), skills/extensions/MCP integrations ([[concepts/skills]], [[concepts/extensions]], [[concepts/mcp-integrations]]), and every CLI mode (interactive, `-p`/print, `--mode json`, `--mode rpc`, `--mode acp`). It exposes a programmatic SDK (`createAgentSession`, `SessionManager`, `ModelRegistry`, `AuthStorage`) for embedding — see [[concepts/sdk-and-rpc]]. **`packages/tui` (published as `prime-agent-tui`)** is the standalone terminal UI framework `coding-agent` builds its interactive mode on — differential rendering, synchronized output, bracketed paste, and the component/overlay primitives detailed in [[concepts/tui-and-themes]]. It is usable independently of Prime Agent for building other flicker-free terminal apps. All four packages currently retain inherited `@earendil-works/pi-*` source workspace names from the `pi-mono` fork lineage — release docs and public documentation use the Prime Agent package names (`prime-agent-core`, `prime-agent-ai`, `prime-agent-tui`) throughout, and the source names are called out explicitly as an in-progress namespace migration, not the documented public interface. **Prime Agent packages (the installable-bundle system)** are a separate concept: a package declares `extensions`, `skills`, `prompts`, and `themes` resource arrays either under a `pi` key in `package.json` (for compatibility with the inherited extension ecosystem) or via convention directories (`extensions/`, `skills/`, `prompts/`, `themes/`) when no manifest is present. Three source types are accepted: - **npm**: `npm:@scope/pkg@1.2.3` or `npm:pkg`; versioned specs are pinned (skipped by `package update`); global installs use `npm install -g`, project installs go under `.prime/agent/npm/`. - **git**: `git:github.com/user/repo@v1`, `git:git@github.com:user/repo@v1`, or raw `https://`/`ssh://` URLs; refs pin the package; cloned to `~/.prime/agent/git//` (global) or `.prime/agent/git//` (project); runs `npm install` after clone/pull if a `package.json` exists. - **Local paths**: absolute or relative filesystem paths, added to settings without copying; a file path loads as a single extension, a directory loads via package rules. Management commands: `prime-agent package install [--local]`, `package remove`, `package list`, `package update [source]`. `-e`/`--extension ` loads a package temporarily (current run only, to a temp directory) without installing it. Package filtering in settings (object form with `extensions`/`skills`/`prompts`/`themes` glob arrays, `!exclude`, `+forceInclude`, `-forceExclude`) narrows what an installed package actually loads. Third-party runtime dependencies belong in `package.json` `dependencies` (installed automatically); a package that imports Prime Agent's own core libraries (`@earendil-works/pi-ai`, `pi-agent-core`, `pi-coding-agent`, `pi-tui`, `typebox`) must list them as `peerDependencies` with a `"*"` range rather than bundling them, since Prime Agent already provides them at runtime. Packages appearing in both global and project settings dedupe by identity (npm package name, git repo URL sans ref, or resolved local path); on conflict, the project entry wins. ## Key Parameters - **Four core packages**: `agent` (runtime), `ai` (providers), `coding-agent` (product/CLI), `tui` (UI) — each independently publishable, `coding-agent` depending on the other three. - **`Agent` tool execution modes**: `parallel` (default, global or per-tool via `executionMode`) vs. `sequential`; any `sequential` tool in a batch forces the whole batch sequential. - **`ai` faux provider**: `registerFauxProvider({ tokensPerSecond? })` — deterministic scripted responses for tests, not part of the built-in provider set. - **Package source identity for dedup**: npm → package name; git → repo URL without ref; local → resolved absolute path. - **`peerDependencies` requirement**: Prime Agent's own core libraries (`pi-ai`, `pi-agent-core`, `pi-coding-agent`, `pi-tui`, `typebox`) must never be bundled by a third-party package. ## When To Use Consult the internal package breakdown when deciding where a change belongs (agent-loop/event semantics → `agent`; provider/model/streaming behavior → `ai`; CLI/TUI/daemon/session product behavior → `coding-agent`; terminal-rendering primitives → `tui`) or when embedding Prime Agent programmatically via the `agent`/`ai` SDKs directly rather than the CLI. Consult the installable-packages system when distributing a bundle of extensions/skills/prompts/themes to a team (via git or npm, project-local with `--local` for team-shared settings) or when trying a package once without committing to an install (`-e`/`--extension`). ## Risks & Pitfalls - Confusing the two "package" concepts described here — internal monorepo workspace packages (`agent`, `ai`, `coding-agent`, `tui`) versus user-installable Prime Agent packages (npm/git/local bundles of extensions/skills/prompts/themes) — is an easy documentation trap since both use the word "package." - Bundling Prime Agent's own core libraries as regular `dependencies` in a third-party package (instead of `peerDependencies`) risks shipping a duplicate, possibly incompatible copy alongside the host's own runtime instance. - Pinned npm/git package specs (with an explicit version or ref) are silently skipped by `prime-agent package update` — a common source of "why isn't this getting the latest version" confusion. - Package filtering syntax mixes glob exclusion (`!pattern`) with exact-path force-include/exclude (`+path`/`-path`); these operate differently and are easy to conflate. ## Related Concepts - [[concepts/architecture]] — how `agent`, `ai`, `coding-agent`, and `tui` fit into Prime Agent's overall runtime architecture - [[concepts/extensions]] and [[concepts/skills]] — the resource types that Prime Agent packages bundle and distribute - [[concepts/providers-and-models]] — the provider catalog implemented in `packages/ai` - [[concepts/tui-and-themes]] — built on `packages/tui` - [[concepts/daemon]] and [[concepts/sessions-and-compaction]] — core `coding-agent` subsystems - [[concepts/sdk-and-rpc]] — the programmatic SDK surface `coding-agent` exposes over `agent`/`ai` - [[concepts/development]] — building and validating changes across these packages from source ## Sources - raw/github_doc-packages-coding-agent-docs-packages-md.md - raw/github_doc-packages-agent-readme-md.md - raw/github_doc-packages-ai-readme-md.md - raw/github_doc-packages-coding-agent-readme-md.md - raw/github_doc-packages-tui-readme-md.md