# wht981/pi architecture

> Architecture diagram of the GitHub repository wht981/pi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wht981/pi
- Repository: https://github.com/wht981/pi

## Overview

Pi is a self-extensible coding-agent project: users interact through a CLI, which coordinates agent sessions, model access, tools, and session state. The agent runtime supplies tool-calling and state management; the AI package provides a unified interface to multiple model providers. The tree also shows extension and remote-session capabilities. Several subsystem links are based on package descriptions and module layout rather than sampled call sites, so the graph omits uncertain wiring; persistence alternatives are shown as separate backends.

Main entry points: [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/agent-session.ts) (Agent session), [`packages/coding-agent/src/cli.ts`](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/cli.ts) (Coding-agent CLI), [`packages/coding-agent/src/core/model-runtime.ts`](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/model-runtime.ts) (Model runtime), [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/session-manager.ts) (Session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_cli["Coding-agent CLI<br/>[cli.ts]"]
  node_interactive["Interactive mode"]
  node_rpc_client["RPC client<br/>[client.ts]"]
end

subgraph group_orchestration["Agent runtime"]
  node_agent_session["Agent session<br/>[agent-session.ts]"]
  node_agent_runtime["Agent runtime"]
  node_remote_sessions["Remote sessions<br/>[session-router.ts]"]
end

subgraph group_models["Models and auth"]
  node_model_runtime["Model runtime<br/>[model-runtime.ts]"]
  node_ai_api["Unified AI API"]
  node_provider["Model providers"]
  node_auth["Provider auth"]
end

subgraph group_state["Session state"]
  node_session_manager["Session manager<br/>[session-manager.ts]"]
  node_jsonl[("JSONL storage<br/>[storage.ts]")]
  node_sqlite[("SQLite storage<br/>[storage.ts]")]
end

subgraph group_integration["Tools and extensions"]
  node_tool_registry["Agent tools<br/>[index.ts]"]
  node_extensions["Extensions"]
end

node_user(("User"))
node_model_service{{"External model services"}}
node_filesystem[("Project files")]
node_shell{{"Shell process"}}

node_user -->|"invokes"| node_cli
node_cli -->|"starts"| node_interactive
node_cli -->|"creates session"| node_agent_session
node_interactive -->|"sends input"| node_agent_session
node_agent_session -->|"runs agent"| node_agent_runtime
node_agent_session -->|"uses models"| node_model_runtime
node_model_runtime -->|"requests completion"| node_ai_api
node_ai_api -->|"dispatches"| node_provider
node_provider -->|"calls model"| node_model_service
node_model_runtime -->|"resolves credentials"| node_auth
node_agent_runtime -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"reads and writes"| node_filesystem
node_tool_registry -->|"executes commands"| node_shell
node_agent_session -->|"loads extensions"| node_extensions
node_agent_session -->|"manages state"| node_session_manager
node_session_manager -->|"persists session"| node_jsonl
node_session_manager -.->|"persists session"| node_sqlite
node_rpc_client -.->|"routes session calls"| node_remote_sessions

click node_cli "https://github.com/wht981/pi/blob/main/packages/coding-agent/src/cli.ts"
click node_interactive "https://github.com/wht981/pi/tree/main/packages/coding-agent/src/modes/interactive"
click node_agent_session "https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/agent-session.ts"
click node_agent_runtime "https://github.com/wht981/pi/tree/main/packages/agent/src/harness/runtime"
click node_model_runtime "https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/model-runtime.ts"
click node_ai_api "https://github.com/wht981/pi/tree/main/packages/ai/src"
click node_provider "https://github.com/wht981/pi/tree/main/packages/ai/src/providers"
click node_auth "https://github.com/wht981/pi/tree/main/packages/ai/src/auth"
click node_tool_registry "https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/tools/index.ts"
click node_extensions "https://github.com/wht981/pi/tree/main/packages/coding-agent/src/core/extensions"
click node_session_manager "https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/session-manager.ts"
click node_jsonl "https://github.com/wht981/pi/blob/main/packages/agent/src/harness/session/jsonl/storage.ts"
click node_sqlite "https://github.com/wht981/pi/blob/main/packages/session-backends/sqlite-node/src/sqlite/storage.ts"
click node_remote_sessions "https://github.com/wht981/pi/blob/main/packages/server/src/session-router.ts"
click node_rpc_client "https://github.com/wht981/pi/blob/main/packages/client/src/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_interactive,node_rpc_client,node_user toneBlue
class node_agent_session,node_agent_runtime,node_remote_sessions,node_filesystem toneAmber
class node_model_runtime,node_ai_api,node_provider,node_auth toneMint
class node_session_manager,node_jsonl,node_sqlite toneRose
class node_tool_registry,node_extensions,node_model_service,node_shell toneIndigo
```

## Components

### User interface

- [Coding-agent CLI](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/cli.ts): `packages/coding-agent/src/cli.ts`
- [Interactive mode](https://github.com/wht981/pi/tree/main/packages/coding-agent/src/modes/interactive): `packages/coding-agent/src/modes/interactive`
- [RPC client](https://github.com/wht981/pi/blob/main/packages/client/src/client.ts): `packages/client/src/client.ts`

### Agent runtime

- [Agent session](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/agent-session.ts): `packages/coding-agent/src/core/agent-session.ts`
- [Agent runtime](https://github.com/wht981/pi/tree/main/packages/agent/src/harness/runtime): `packages/agent/src/harness/runtime`
- [Remote sessions](https://github.com/wht981/pi/blob/main/packages/server/src/session-router.ts): `packages/server/src/session-router.ts`

### Models and auth

- [Model runtime](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/model-runtime.ts): `packages/coding-agent/src/core/model-runtime.ts`
- [Unified AI API](https://github.com/wht981/pi/tree/main/packages/ai/src): `packages/ai/src`
- [Model providers](https://github.com/wht981/pi/tree/main/packages/ai/src/providers): `packages/ai/src/providers`
- [Provider auth](https://github.com/wht981/pi/tree/main/packages/ai/src/auth): `packages/ai/src/auth`

### Session state

- [Session manager](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/session-manager.ts): `packages/coding-agent/src/core/session-manager.ts`
- [JSONL storage](https://github.com/wht981/pi/blob/main/packages/agent/src/harness/session/jsonl/storage.ts): `packages/agent/src/harness/session/jsonl/storage.ts`
- [SQLite storage](https://github.com/wht981/pi/blob/main/packages/session-backends/sqlite-node/src/sqlite/storage.ts): `packages/session-backends/sqlite-node/src/sqlite/storage.ts`

### Tools and extensions

- [Agent tools](https://github.com/wht981/pi/blob/main/packages/coding-agent/src/core/tools/index.ts): `packages/coding-agent/src/core/tools/index.ts`
- [Extensions](https://github.com/wht981/pi/tree/main/packages/coding-agent/src/core/extensions): `packages/coding-agent/src/core/extensions`

### Other components

- **User**
- **External model services**
- **Project files**
- **Shell process**

## Connections

- User → Coding-agent CLI: invokes
- Coding-agent CLI → Interactive mode: starts
- Coding-agent CLI → Agent session: creates session
- Interactive mode → Agent session: sends input
- Agent session → Agent runtime: runs agent
- Agent session → Model runtime: uses models
- Model runtime → Unified AI API: requests completion
- Unified AI API → Model providers: dispatches
- Model providers → External model services: calls model
- Model runtime → Provider auth: resolves credentials
- Agent runtime → Agent tools: dispatches tools
- Agent tools → Project files: reads and writes
- Agent tools → Shell process: executes commands
- Agent session → Extensions: loads extensions
- Agent session → Session manager: manages state
- Session manager → JSONL storage: persists session
- Session manager → SQLite storage: persists session
- RPC client → Remote sessions: routes session calls