packages coding agent

Coding agent

Active contributors: Mario Zechner, kt, Armin Ronacher

packages/coding-agent is @earendil-works/pi-coding-agent, the core package of Prime Agent. It combines the CLI, the programmatic SDK, the daemon, and the session runtime in one package: it owns the AgentSession lifecycle, JSONL session persistence, the IPython kernel tool, compaction, and the typed AgentConnection seam that every interface (terminal UI, web chat, headless clients) drives the runtime through. The sibling core packages are dependencies: @earendil-works/pi-agent-core provides the Agent turn loop, @earendil-works/pi-ai provides model providers and streaming, and @earendil-works/pi-tui provides the terminal UI components.

The package ships two bins (pi and prime-agent) pointing at packages/coding-agent/dist/bundle/cli.js, requires Node >= 22.8.0, and keeps user config under ~/.prime/agent/ (from the piConfig.configDir value .prime/agent in packages/coding-agent/package.json). It is a TypeScript ESM npm workspace package with 270 source files and 315 test files.

Purpose

• Provide one dependency that embeds the whole agent product: CLI argument handling, run modes, daemon protocol, session runtime, tools, and persistence.
• Expose a stable public surface for programmatic use (createAgentSession and friends) and a typed connection seam (AgentConnection) so any front end can drive sessions without touching internals.
• Persist every session as a JSONL transcript under ~/.prime/agent/sessions/ so sessions resume, fork, and rehydrate across processes.

Directory layout

packages/coding-agent/
├── package.json               # @earendil-works/pi-coding-agent, bins pi + prime-agent, exports "." and "./hooks"
├── README.md                  # full user and CLI reference
├── src/
│   ├── cli.ts                 # Node bin entry with version guard, dynamically imports cli-main.ts
│   ├── cli-main.ts            # runCli(), the actual bin dispatch
│   ├── main.ts                # CLI arg parsing, run-mode selection, translate args into createAgentSession options
│   ├── index.ts               # package root re-exports: the public SDK surface
│   ├── config.ts              # paths (~/.prime/agent), install detection, self-update, VERSION
│   ├── cli/                   # args.ts, daemon launch/attach commands, session resolution, file processing
│   ├── core/                  # session runtime, tools, kernel, compaction, extensions, auth, settings
│   ├── modes/                 # run modes: interactive (TUI), print, rpc, acp, daemon, agents-view, agent-connection
│   ├── themes/                # terminal theme definitions (prime-logo.ts)
│   ├── bun/                   # Bun binary entry (cli.ts), register-bedrock.ts, restore-sandbox-env.ts
│   └── utils/                 # shell, git, clipboard, image, file, and child-process helpers
├── docs/                      # user documentation (docs/index.md is the doc hub, see below)
├── skills/                    # built-in markdown and Python skills shipped with the package
├── examples/                  # SDK examples (examples/sdk/)
├── test/                      # 315 vitest files, including test/suite/ and regressions
├── dist/                      # build output (tsgo build + bundle)
└── CHANGELOG.md

Package exports

packages/coding-agent/package.json declares two export entries that point into the built output:

• . -> packages/coding-agent/dist/index.js (types packages/coding-agent/dist/index.d.ts): the root entry compiled from packages/coding-agent/src/index.ts.
• ./hooks -> packages/coding-agent/dist/core/hooks/index.js (types packages/coding-agent/dist/core/hooks/index.d.ts): the extension hooks surface.

The main and types fields point at packages/coding-agent/dist/index.js and packages/coding-agent/dist/index.d.ts. files ships dist, docs, examples, skills, packages/coding-agent/postinstall.cjs, and packages/coding-agent/CHANGELOG.md, which is why the docs/ directory travels with the installed package.

SDK entry points

There is no top-level packages/coding-agent/src/sdk.ts; the SDK entry points are two files:

• packages/coding-agent/src/index.ts is the package root re-export surface. It re-exports everything consumers need: AgentSession, AgentSessionEvent, createAgentSession, SessionManager, AuthStorage, SettingsManager, ModelRegistry, compaction functions, extension types (ExtensionUIContext, ToolDefinition), tool factories (createBashTool, createEditTool, createIpythonTool, IpythonKernelProvisioner), run modes (InteractiveMode, runPrintMode, runRpcMode, daemon types), and UI components for extensions.
• packages/coding-agent/src/core/sdk.ts implements createAgentSession, the single factory that resolves defaults (cwd, agentDir, auth, models, settings, session manager, resource loader) and constructs an AgentSession around an Agent.

Two supporting factories, also exported from the root, separate service creation from session creation:

• createAgentSessionServices in packages/coding-agent/src/core/agent-session-services.ts builds the cwd-bound services bundle without a session.
• createAgentSessionFromServices in the same file builds a session from an existing services bundle, which is what web/server and packages/coding-agent/src/main.ts use.
• createAgentSessionRuntime and AgentSessionRuntime in packages/coding-agent/src/core/agent-session-runtime.ts add session replacement (/new, resume, /fork, import) on top.

Key abstractions

Type / function	Full path	One-line description
createAgentSession	packages/coding-agent/src/core/sdk.ts	Factory that wires defaults and returns { session, extensionsResult, modelFallbackMessage }
AgentSession	packages/coding-agent/src/core/agent-session.ts	The session: turn admission, event emission, persistence hooks, compaction, retry, model and tool control
AgentSessionRuntime	packages/coding-agent/src/core/agent-session-runtime.ts	Owns a session plus cwd-bound services; implements new/resume/fork/import replacement and RLM subagent runtimes
AgentSessionServices	packages/coding-agent/src/core/agent-session-services.ts	cwd-bound bundle: AuthStorage, SettingsManager, ModelRegistry, ResourceLoader, McpManager, diagnostics
SessionManager	packages/coding-agent/src/core/session-manager.ts	JSONL transcript persistence, session entry tree, buildSessionContext, createBranchedSession
Agent	packages/agent/src/agent.ts	The turn loop from @earendil-works/pi-agent-core that AgentSession wraps
IpythonKernelProvisioner	packages/coding-agent/src/core/tools/ipython.ts	Owns lazy create, start, and runtime bootstrap of a session's IPython kernel
AgentConnection	packages/coding-agent/src/modes/agent-connection/	Typed client seam: session state, commands, and events for any front end
InteractiveMode	packages/coding-agent/src/modes/interactive/interactive-mode.ts	The terminal UI run mode
EventBus	packages/coding-agent/src/core/event-bus.ts	Channel-based emitter used to wire UI services

How it works

One package, three interfaces. The bins (pi, prime-agent) enter through packages/coding-agent/src/cli.ts, which dispatches to packages/coding-agent/src/cli-main.ts and packages/coding-agent/src/main.ts. packages/coding-agent/src/main.ts parses args (packages/coding-agent/src/cli/args.ts), picks a run mode, and either connects to a daemon or builds services and a session in process. The web adapter (web/server) calls createAgentSessionFromServices directly in process. Headless clients (print, JSON, RPC, ACP) and the interactive TUI drive the runtime through AgentConnection; the daemon runs the same AgentSessionRuntime in worker processes.

Every path funnels into the same core: AgentSessionRuntime -> AgentSession -> Agent -> model providers, with tools (ipython kernel, bash, edit) and SessionManager persistence attached to the session.

graph TD
    CLI["CLI entry (bins pi, prime-agent)"]
    WEB["web/server adapter (in-process)"]
    DAEMON["daemon modes"]
    RT["AgentSessionRuntime"]
    SVC["AgentSessionServices"]
    AS["AgentSession"]
    AG["Agent (pi-agent-core)"]
    TOOLS["tools: ipython kernel, bash, edit"]
    SM["SessionManager"]
    P["model providers (pi-ai)"]
    JSONL["~/.prime/agent/sessions/*.jsonl"]

    CLI --> RT
    WEB --> SVC
    DAEMON --> RT
    RT --> SVC
    SVC --> AS
    AS --> AG
    AG --> P
    AS --> TOOLS
    AS --> SM
    SM --> JSONL

Loading

The docs/ directory is the user documentation for the package. packages/coding-agent/docs/index.md is the hub: quickstart, usage, sessions, compaction, providers, settings, extensions, skills, SDK, session format, and architecture docs. Because docs/ is shipped in the package files, the same documentation is available to installed consumers.

Integration points

• web/server consumes the public surface listed in the root AGENTS.md: createAgentSession, AgentSessionEvent, ExtensionUIContext, IpythonKernelProvisioner, SessionManager, plus createAgentSessionFromServices, AuthStorage, ModelRegistry, SettingsManager, and DefaultResourceLoader. See Web server.
• packages/agent provides the Agent turn loop and packages/ai provides model providers; see Agent core and LLM provider abstraction and streaming.
• The TUI in this package (packages/coding-agent/src/modes/interactive/) is the reference client for the runtime; the packaged @earendil-works/pi-tui dependency provides the terminal primitives.
• User-facing session workflow (resume, fork, tree navigation) is described in Sessions and branching; terms such as compaction, kernel, and SessionView are defined in Glossary.

Entry points for modification

• CLI flags and commands: packages/coding-agent/src/cli/args.ts and packages/coding-agent/src/main.ts.
• Session lifecycle and turn behavior: packages/coding-agent/src/core/agent-session.ts, packages/coding-agent/src/core/agent-session-runtime.ts.
• New built-in tool: register in packages/coding-agent/src/core/tools/index.ts and wire the factory in _buildRuntime in packages/coding-agent/src/core/agent-session.ts.
• Event surface for clients: AgentSessionEvent in packages/coding-agent/src/core/agent-session.ts; keep the web event mapper in web/server in sync.
• Session persistence format: packages/coding-agent/src/core/session-manager.ts and packages/coding-agent/docs/session-format.md.
• User documentation: packages/coding-agent/docs/.

Key source files

File	Purpose
packages/coding-agent/src/index.ts	Package root re-exports; the public SDK surface
packages/coding-agent/src/core/sdk.ts	createAgentSession factory
packages/coding-agent/src/core/agent-session.ts	AgentSession class, AgentSessionEvent, turn and tool hooks
packages/coding-agent/src/core/agent-session-runtime.ts	AgentSessionRuntime, session replacement flows
packages/coding-agent/src/core/agent-session-services.ts	Services creation and diagnostics
packages/coding-agent/src/core/session-manager.ts	SessionManager and session entry types
packages/coding-agent/src/main.ts	CLI entry: arg parsing and run-mode dispatch
packages/coding-agent/package.json	Name, bins, exports, files, engines

Related pages

• Session runtime - the AgentSession lifecycle, persistence, compaction, and event bus
• Agent tools - the ipython kernel tool, bash, edit, and the tool-call event flow
• CLI - command line flags and subcommands
• Daemon - the background daemon, worker processes, and protocol
• Interactive mode - the terminal UI run mode
• Skills - markdown and Python-backed skills
• Extensions - TypeScript modules for tools, commands, events, and custom UI
• Refinement - the self-improving refine harness
• RLM runtime - recursive subagents and the ZeroMQ kernel transport