wikis / Prime Agent / wiki / concepts / packages-overview.md view as markdown report a mistake

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 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 <thinking>-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 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 daemon), sessions (sessions and compaction), settings (settings and customization), skills/extensions/MCP integrations (skills, extensions, 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 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 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/<host>/<path> (global) or .prime/agent/git/<host>/<path> (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 <source> [--local], package remove, package list, package update [source]. -e/--extension <source> 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

• architecture — how agent, ai, coding-agent, and tui fit into Prime Agent's overall runtime architecture
• extensions and skills — the resource types that Prime Agent packages bundle and distribute
• providers and models — the provider catalog implemented in packages/ai
• tui and themes — built on packages/tui
• daemon and sessions and compaction — core coding-agent subsystems
• sdk and rpc — the programmatic SDK surface coding-agent exposes over agent/ai
• 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