# Technical Orientation

> What the repo is, how the four packages fit together, the main entry points, and how to navigate the rest of the developer reference.

- Repository: earendil-works/pi
- GitHub: https://github.com/earendil-works/pi
- Human wiki: https://grok-wiki.com/public/wiki/earendil-works-pi-121d322b171c
- Complete Markdown: https://grok-wiki.com/public/wiki/earendil-works-pi-121d322b171c/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `packages/ai/package.json`
- `packages/agent/package.json`
- `packages/coding-agent/package.json`
- `packages/tui/package.json`
- `packages/coding-agent/src/main.ts`
- `packages/agent/src/index.ts`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [README.md](README.md)
- [package.json](package.json)
- [packages/ai/package.json](packages/ai/package.json)
- [packages/agent/package.json](packages/agent/package.json)
- [packages/coding-agent/package.json](packages/coding-agent/package.json)
- [packages/tui/package.json](packages/tui/package.json)
- [packages/coding-agent/src/main.ts](packages/coding-agent/src/main.ts)
- [packages/coding-agent/src/index.ts](packages/coding-agent/src/index.ts)
- [packages/coding-agent/src/core/sdk.ts](packages/coding-agent/src/core/sdk.ts)
- [packages/coding-agent/src/core/agent-session.ts](packages/coding-agent/src/core/agent-session.ts)
- [packages/agent/src/index.ts](packages/agent/src/index.ts)
- [packages/agent/src/agent.ts](packages/agent/src/agent.ts)
- [packages/agent/src/agent-loop.ts](packages/agent/src/agent-loop.ts)
- [packages/ai/src/index.ts](packages/ai/src/index.ts)
- [packages/ai/src/models.ts](packages/ai/src/models.ts)
- [packages/ai/src/api-registry.ts](packages/ai/src/api-registry.ts)
- [packages/tui/src/index.ts](packages/tui/src/index.ts)
- [packages/tui/src/tui.ts](packages/tui/src/tui.ts)
- [packages/coding-agent/README.md](packages/coding-agent/README.md)
- [packages/agent/README.md](packages/agent/README.md)
- [packages/ai/README.md](packages/ai/README.md)
- [packages/tui/README.md](packages/tui/README.md)
</details>

# Technical Orientation

This page explains what `earendil-works/pi` contains, how its four packages fit together, where runtime control enters the system, and which files to open next when working on CLI behavior, agent runtime behavior, provider support, or terminal UI.

The repository is a TypeScript monorepo for the Pi agent harness. Its top-level README names the three core agent packages and the package table adds the terminal UI package; the root workspace configuration includes `packages/*` plus coding-agent examples as workspaces.  
Sources: [README.md:19-25](), [README.md:52-55](), [package.json:5-15]()

## Package map

| Package | Primary responsibility | Main evidence |
|---|---|---|
| `@earendil-works/pi-coding-agent` | User-facing `pi` CLI, SDK exports, sessions, tools, resources, modes, extensions. | Package description and `bin.pi`; dependency on all three library packages. |
| `@earendil-works/pi-agent-core` | Stateful agent runtime, event streaming, tool execution loop, message conversion boundary. | Package description and dependency on `pi-ai`; `Agent` and `agent-loop` exports. |
| `@earendil-works/pi-ai` | Provider/model abstraction, model registry, streaming APIs, TypeBox helper exports, provider registration. | Package description, provider exports, model registry, API registry. |
| `@earendil-works/pi-tui` | Terminal UI primitives used by interactive mode: `TUI`, terminal abstraction, components, keybindings, rendering. | Package description and exported components/classes. |

Sources: [packages/coding-agent/package.json:2-14](), [packages/coding-agent/package.json:41-44](), [packages/agent/package.json:2-8](), [packages/agent/package.json:31-33](), [packages/ai/package.json:2-8](), [packages/tui/package.json:2-4]()

## Runtime dependency shape

```mermaid
flowchart TD
  subgraph App["packages/coding-agent"]
    CLI["src/main.ts\nCLI args, modes, services"]
    SDK["src/core/sdk.ts\ncreateAgentSession()"]
    Session["src/core/agent-session.ts\nsessions, tools, extensions, compaction"]
  end

  subgraph Core["packages/agent"]
    Agent["Agent"]
    Loop["agent-loop"]
  end

  subgraph Provider["packages/ai"]
    Models["models.ts"]
    ApiRegistry["api-registry.ts"]
    Stream["stream / streamSimple"]
  end

  subgraph UI["packages/tui"]
    TUI["TUI"]
    Components["Editor, Input, Markdown, SelectList, ..."]
  end

  CLI --> SDK
  SDK --> Session
  SDK --> Agent
  Agent --> Loop
  Loop --> Stream
  Stream --> ApiRegistry
  SDK --> Models
  CLI --> TUI
  TUI --> Components
```

The build script also reflects the dependency order: `tui`, then `ai`, then `agent`, then `coding-agent`.  
Sources: [package.json:13-15](), [packages/coding-agent/src/main.ts:8-44](), [packages/coding-agent/src/core/sdk.ts:1-32](), [packages/agent/src/index.ts:2-44](), [packages/ai/src/index.ts:1-47](), [packages/tui/src/index.ts:12-106]()

## Main entry points

### CLI entry: `packages/coding-agent/src/main.ts`

`main(args, options)` is the CLI orchestration point. It handles offline flags, package/config subcommands, argument parsing, stdout handling for non-interactive modes, export, migrations, session selection, runtime service creation, model listing, piped stdin, initial message preparation, theme initialization, diagnostics, and final dispatch to RPC, interactive, or print/JSON mode.

```ts
if (appMode === "rpc") {
  await runRpcMode(runtime);
} else if (appMode === "interactive") {
  const interactiveMode = new InteractiveMode(runtime, { /* ... */ });
  await interactiveMode.run();
} else {
  const exitCode = await runPrintMode(runtime, { /* ... */ });
}
```

Sources: [packages/coding-agent/src/main.ts:424-455](), [packages/coding-agent/src/main.ts:533-614](), [packages/coding-agent/src/main.ts:630-709]()

### SDK surface: `packages/coding-agent/src/index.ts` and `core/sdk.ts`

The coding-agent package re-exports the programmatic API: `AgentSession`, auth storage, model registry, resource loaders, settings, skills, extensions, session manager, compaction helpers, and tool factories. The `createAgentSession()` SDK function creates or accepts `AuthStorage`, `ModelRegistry`, `SettingsManager`, `SessionManager`, and `ResourceLoader`, picks/restores the model, configures default tools, constructs an `Agent`, then wraps it in `AgentSession`.

Default built-in tools are `read`, `bash`, `edit`, and `write`; callers can suppress or allowlist tools via `noTools` and `tools`.

Sources: [packages/coding-agent/src/index.ts:1-260](), [packages/coding-agent/src/core/sdk.ts:34-78](), [packages/coding-agent/src/core/sdk.ts:202-218](), [packages/coding-agent/src/core/sdk.ts:280-417]()

### Session layer: `packages/coding-agent/src/core/agent-session.ts`

`AgentSession` is the shared abstraction above all CLI run modes. Its header states that it is used by interactive, print, and RPC modes and encapsulates agent state access, event subscription with session persistence, model/thinking management, compaction, bash execution, and session switching/branching. It subscribes to core agent events for persistence, extensions, auto-compaction, and retry logic.

Sources: [packages/coding-agent/src/core/agent-session.ts:1-12](), [packages/coding-agent/src/core/agent-session.ts:123-150](), [packages/coding-agent/src/core/agent-session.ts:156-194](), [packages/coding-agent/src/core/agent-session.ts:252-336](), [packages/coding-agent/src/core/agent-session.ts:962-1043](), [packages/coding-agent/src/core/agent-session.ts:1611-1723]()

## Agent core boundary

`@earendil-works/pi-agent-core` exports the `Agent`, low-level loop functions, harness utilities, compaction/session helpers, proxy utilities, and shared types. `Agent` owns transcript state, lifecycle event subscribers, steering and follow-up queues, the provider stream function, API-key lookup hooks, pre/post tool hooks, and transport/thinking/tool-execution settings.

The lower-level loop transforms application-facing `AgentMessage[]` to provider-facing `Message[]` only at the LLM call boundary, then streams assistant events, executes tool calls, appends tool results, checks stop conditions, and drains steering/follow-up queues. Tool execution can be sequential or parallel depending on config and per-tool settings.

Sources: [packages/agent/src/index.ts:2-44](), [packages/agent/src/agent.ts:155-268](), [packages/agent/src/agent-loop.ts:155-268](), [packages/agent/src/agent-loop.ts:273-387](), [packages/agent/README.md:36-54](), [packages/agent/README.md:102-157]()

## Provider and model layer

`@earendil-works/pi-ai` is provider-neutral: the code exposes registries and typed provider/model APIs rather than assuming a single hosted service. `models.ts` initializes an in-memory registry from generated model metadata and exposes `getModel`, `getProviders`, `getModels`, cost calculation, thinking-level support, and model equality helpers. `api-registry.ts` stores stream implementations by API name and allows providers to be registered and unregistered, including source-scoped unregistration.

The package README lists many supported providers and explicitly includes OpenAI-compatible APIs such as Ollama, vLLM, and LM Studio, which keeps the architecture BYOK/BYOC-friendly.

Sources: [packages/ai/src/index.ts:1-47](), [packages/ai/src/models.ts:1-39](), [packages/ai/src/models.ts:50-90](), [packages/ai/src/api-registry.ts:23-98](), [packages/ai/README.md:51-77](), [packages/ai/README.md:85-112]()

## Terminal UI layer

`@earendil-works/pi-tui` is a small terminal UI framework. Its exports include components (`Editor`, `Input`, `Markdown`, `SelectList`, `SettingsList`, `Text`, `Image`, `Box`), terminal abstractions, key parsing/keybindings, autocomplete, image rendering, and the `TUI` container. The core `Component` interface renders to lines for a viewport width, can handle focused input, and can invalidate cached rendering. `TUI` extends `Container`, manages focus, overlays, terminal lifecycle, and render requests.

Sources: [packages/tui/src/index.ts:12-106](), [packages/tui/src/tui.ts:39-77](), [packages/tui/src/tui.ts:200-239](), [packages/tui/src/tui.ts:329-408](), [packages/tui/src/tui.ts:443-449](), [packages/tui/src/tui.ts:495-515](), [packages/tui/README.md:3-13]()

## How to navigate the developer reference

| Task | Start here | Why |
|---|---|---|
| Understand user-facing CLI behavior | `packages/coding-agent/README.md`, then `packages/coding-agent/src/main.ts` | README lists modes, providers, sessions, settings, customization, SDK, and CLI reference; `main.ts` wires them together. |
| Change session, compaction, model switching, or prompt behavior | `packages/coding-agent/src/core/agent-session.ts` | This is the mode-shared session lifecycle layer. |
| Embed Pi in another app | `packages/coding-agent/src/core/sdk.ts` and exported symbols in `packages/coding-agent/src/index.ts` | `createAgentSession()` is the programmatic construction path. |
| Change agent event/tool loop behavior | `packages/agent/src/agent.ts` and `packages/agent/src/agent-loop.ts` | These own stateful event emission and tool-call loop semantics. |
| Add or modify providers/models | `packages/ai/src/api-registry.ts`, `packages/ai/src/models.ts`, provider exports in `packages/ai/src/index.ts` | Provider implementations are registered behind API/model registries. |
| Work on interactive terminal UI | `packages/tui/src/tui.ts`, `packages/tui/src/index.ts`, and coding-agent interactive mode files | `pi-tui` owns reusable UI primitives; coding-agent composes them for Pi. |

Sources: [packages/coding-agent/README.md:20-24](), [packages/coding-agent/README.md:43-64](), [packages/coding-agent/README.md:96-104](), [packages/coding-agent/README.md:140-173](), [packages/coding-agent/README.md:230-236](), [packages/coding-agent/README.md:315-434](), [packages/coding-agent/README.md:490-492]()

## Development commands and checks

The root development workflow is workspace-oriented. The README documents `npm install --ignore-scripts`, `npm run build`, `npm run check`, `./test.sh`, and `./pi-test.sh`. The root scripts define `build`, `check`, workspace `test`, release/version commands, pinned-dependency checks, shrinkwrap checks, TypeScript checking, and browser smoke checks.

Sources: [README.md:63-69](), [package.json:13-22](), [package.json:49-50]()

## Closing summary

At a high level, `packages/coding-agent` is the application and SDK layer, `packages/agent` is the stateful event/tool loop, `packages/ai` is the provider-neutral model/streaming abstraction, and `packages/tui` is the interactive terminal UI toolkit. Start from `packages/coding-agent/src/main.ts` for runtime behavior, then move downward into `core/sdk.ts`, `AgentSession`, `Agent`, and `pi-ai` or `pi-tui` depending on whether the change is about sessions/tools/providers or terminal interaction.  
Sources: [packages/coding-agent/src/main.ts:424-709](), [packages/coding-agent/src/core/sdk.ts:202-417](), [packages/agent/src/agent-loop.ts:155-387]()

Generation note: no `STRATEGY.md` or `docs/solutions/**` files were found in this checkout; this page uses repository code and README/package metadata as source of truth, with page-shape guidance from the bundled Compound Engineering profile described in the request.