# Pi Agent — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-06-19 --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [what-is-pi](concepts/what-is-pi.md) | pi, toolkit, overview | high | 2026-06-19 | | [pi-ai-unified-llm-api](concepts/pi-ai-unified-llm-api.md) | pi-ai, llm, streaming | high | 2026-06-19 | | [agent-core-and-harness](concepts/agent-core-and-harness.md) | agent-core, harness, turns | high | 2026-06-19 | | [agent-events-and-hooks](concepts/agent-events-and-hooks.md) | events, hooks, observability | high | 2026-06-19 | | [coding-agent-overview](concepts/coding-agent-overview.md) | coding-agent, cli, modes | high | 2026-06-19 | | [quickstart-and-usage](concepts/quickstart-and-usage.md) | quickstart, install, usage | high | 2026-06-19 | | [models-and-providers](concepts/models-and-providers.md) | models, providers, custom | high | 2026-06-19 | | [sessions](concepts/sessions.md) | sessions, fork, sharing | high | 2026-06-19 | | [extensions-and-packages](concepts/extensions-and-packages.md) | extensions, packages, typescript | high | 2026-06-19 | | [skills](concepts/skills.md) | skills, capabilities | high | 2026-06-19 | | [tui-and-customization](concepts/tui-and-customization.md) | tui, themes, settings | high | 2026-06-19 | | [runtime-environments](concepts/runtime-environments.md) | containerization, tmux, windows | high | 2026-06-19 | | [security](concepts/security.md) | security, trust, permissions | high | 2026-06-19 | ## Entities | Page | Tags | Updated | |------|------|---------| | [pi-cli](entities/pi-cli.md) | cli, modes | 2026-06-19 | ## Summaries | Page | Source | Key Topics | Created | |------|--------|------------|---------| | [docs-catalog](summaries/docs-catalog.md) | pi monorepo docs | packages + docs map | 2026-06-19 | ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [integration-modes](syntheses/integration-modes.md) | interactive/print/RPC/SDK | 2026-06-19 | | [compaction-and-context](syntheses/compaction-and-context.md) | compaction + branches + reserveTokens | 2026-06-19 | ## Statistics - **Total pages**: 17 - **Concepts**: 13 - **Entities**: 1 - **Summaries**: 1 - **Syntheses**: 2 - **Sources ingested**: 40 earendil-works/pi docs (READMEs + pi-agent docs + pi-coding-agent docs) - **High confidence**: 17 --- title: "Agent Core & the Harness" type: concept tags: [agent-core, harness, runtime, turns, tools] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-agent-readme-md.md, raw/github_doc-packages-agent-docs-agent-harness-md.md, raw/github_doc-packages-agent-docs-durable-harness-md.md] --- # Agent Core & the Harness **@earendil-works/pi-agent-core** is the agent runtime: it drives the loop of LLM calls + tool executions with managed state, built on [pi-ai](pi-ai-unified-llm-api.md). ## The harness The **harness** owns the full run lifecycle: - **Run lifecycle & turns** — a run is a sequence of **turns**, each "one LLM call + its tool executions." - **Abort controller** — cancel an in-flight run cleanly. - **Queue draining** — messages arriving mid-run are queued and drained in order (no races). - **Provider stream config** — per-turn stream options, headers, metadata, and derived session id are snapshotted per turn. - **Event reduction** — streamed events are reduced into coherent messages. - **Session persistence & pending-write flushing** — state is saved durably with ordered writes and **save-points**. ## Durable harness A **durable harness** variant persists run state so an agent can survive restarts/crashes and resume — important for long-running or background agents (the pattern OpenClaw-style always-on agents need). ## Tool calling & state The core executes tool calls the model requests and manages conversation state across turns. Tools and lifecycle points are extensible via [hooks and events](agent-events-and-hooks.md). This package is model-agnostic (any [pi-ai](pi-ai-unified-llm-api.md) provider) and UI-agnostic — the [coding agent](coding-agent-overview.md) is one consumer; your own app via the [SDK](../syntheses/integration-modes.md) is another. --- title: "Events, Hooks & Observability" type: concept tags: [events, hooks, observability, lifecycle] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-agent-readme-md.md, raw/github_doc-packages-agent-docs-hooks-md.md, raw/github_doc-packages-agent-docs-observability-md.md] --- # Events, Hooks & Observability The [agent harness](agent-core-and-harness.md) emits a structured **event stream** and exposes **hooks**, so you can observe and intervene in a run. ## Event stream Key events: - **`agent_end`** — final event for the run (awaited subscribers still count toward settlement). - **`turn_start` / `turn_end`** — a turn (one LLM call + tool executions) begins/completes (with assistant message and tool results). - **`message_start` / `message_update`** — any message begins; `message_update` (assistant only) carries the streaming `assistantMessageEvent` delta. - **`tool_execution_update`** — streaming progress/output from a running tool. These are the same events surfaced over [RPC](../syntheses/integration-modes.md) and to the [TUI](tui-and-customization.md). ## Hooks **Hooks** let you run logic at lifecycle points — before/after tool calls, around turns, on messages — to add policy (approvals, redaction), inject context, or trigger side effects. Hooks and listeners support **awaited settlement** (the run waits for awaited subscribers before completing), so a hook can reliably gate progress. ## Observability The **observability** docs cover tracing/inspecting runs: following the event stream, logging turns and tool executions, and debugging agent behavior. Because everything flows through the typed event stream, you can build dashboards, audit logs, or eval harnesses by subscribing — no patching internals. This event/hook surface is what makes Pi adaptable "to your workflow" rather than fork-and-modify ([what-is-pi](what-is-pi.md)). --- title: "The Coding Agent" type: concept tags: [coding-agent, cli, harness, modes] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-readme-md.md, raw/github_doc-packages-coding-agent-docs-index-md.md] --- # The Coding Agent **@earendil-works/pi-coding-agent** is Pi's ready-to-use **interactive coding agent** — "a minimal terminal coding harness" you adapt to your workflow rather than the reverse. ## Design stance - **Minimal core, extend with TypeScript** — don't fork pi; add [extensions](extensions-and-packages.md) and install [pi packages](extensions-and-packages.md). - **Powerful defaults, but intentionally omits** sub-agents and plan mode out of the box — you build them or install third-party packages. This keeps the core small and unopinionated. - **Local-first** — runs with your user account's permissions in your project ([security](security.md)). ## Four run modes 1. **Interactive** — the [TUI](tui-and-customization.md) coding session ([usage](quickstart-and-usage.md)). 2. **Print / JSON** — one-shot non-interactive run, plain or structured [JSON](../syntheses/integration-modes.md) output (scripting/CI). 3. **RPC** — long-lived process integration over a JSON-RPC-style protocol ([integration-modes](../syntheses/integration-modes.md)). 4. **SDK** — embed pi's agent in your own app (this is how OpenClaw embeds pi). ## State on disk Settings, credentials, sessions, and installed pi packages live under **`~/.pi/agent/`** (project-local config under `.pi/`). Uninstalling pi leaves these in place. ## Getting going Install and first session: [quickstart-and-usage](quickstart-and-usage.md). Pick models/providers in [models-and-providers](models-and-providers.md). Sessions, forking, sharing: [sessions](sessions.md). The team encourages sharing OSS coding sessions publicly to improve models/prompts/tools. --- title: "Extensions & Pi Packages" type: concept tags: [extensions, packages, typescript, customization] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-extensions-md.md, raw/github_doc-packages-coding-agent-docs-packages-md.md] --- # Extensions & Pi Packages Extending Pi with **TypeScript** — rather than forking — is the core philosophy ([what-is-pi](what-is-pi.md)). Sub-agents and plan mode aren't built in; you add them as extensions or install community **pi packages**. ## Extensions Extensions are TypeScript modules loaded from defined locations: | Location | Scope | |---|---| | `~/.pi/agent/extensions/*.ts` | Global (all projects) | | `~/.pi/agent/extensions/*/index.ts` | Global (subdirectory) | | `.pi/extensions/*/index.ts` | Project-local | An extension uses the **`ExtensionAPI`** / **`ExtensionContext`** types and the agent's **events** ([agent-events-and-hooks](agent-events-and-hooks.md)) from `@earendil-works/pi-coding-agent` to add commands, tools, UI, hooks, sub-agents, or whole modes. Project-local extensions load only in [trusted](security.md) projects. ## Pi packages To **distribute** extensions, publish them as **pi packages** via npm or git. Others install them to get your tools/modes/skills — the ecosystem mechanism (e.g. plan-mode, sub-agent, overlays are shipped this way; the repo's `examples/extensions/` shows plan-mode, subagent, and overlay examples). ## Why this design Keeping the core minimal and pushing capability into TypeScript extensions/packages means: no fork drift, capabilities are shareable and versioned, and you only load what you need. Pi can even **build extensions for you** — ask it to implement the integration you want. Related: [skills](skills.md) (model-facing capability docs) and the [SDK/RPC](../syntheses/integration-modes.md) for embedding. --- title: "Models & Providers" type: concept tags: [models, providers, custom-provider, api] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-models-md.md, raw/github_doc-packages-coding-agent-docs-providers-md.md, raw/github_doc-packages-coding-agent-docs-custom-provider-md.md] --- # Models & Providers Pi talks to any model through [pi-ai](pi-ai-unified-llm-api.md); the coding agent exposes this as configurable **providers** and **models**. ## Providers & API types Each provider declares an **`api`** type that determines the wire protocol, e.g.: - `openai-completions` — OpenAI Chat Completions (the most compatible, works with many OpenAI-compatible endpoints). - Anthropic, Google, and other native APIs. Set `api` at the **provider level** (default for all its models) or override **per model**. ## Configuring a provider Provider/model config (in settings) supports: - **`headers`** — custom request headers (with value resolution, e.g. from env). - **`authHeader: true`** — automatically add `Authorization: Bearer `. - Base URL/endpoint, model list, and per-model overrides. ## Custom & compatible providers Because `openai-completions` is broadly compatible, you can point pi at **any OpenAI-compatible endpoint** (local servers like llama.cpp/vLLM/LM Studio, gateways, or alternative clouds) by configuring a custom provider — the **custom-provider** guide covers adding one end to end, including non-standard auth via headers. ## Choosing models Different models for different jobs (a strong model for hard tasks, a cheap fast one for routine) — selectable per session and configurable as defaults. Model/context limits interact with [compaction](../syntheses/compaction-and-context.md). Credentials are stored under `~/.pi/agent/` ([security](security.md)). --- title: "pi-ai: Unified LLM API" type: concept tags: [pi-ai, llm, providers, streaming] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-ai-readme-md.md] --- # pi-ai: Unified LLM API **@earendil-works/pi-ai** is a **unified, multi-provider LLM API** — one interface to call OpenAI, Anthropic, Google, and other providers, normalizing their differences (auth, request shape, streaming events) behind a consistent contract. It's the foundation layer the [agent core](agent-core-and-harness.md) builds on. ## Streaming event model The defining feature is a rich, normalized **streaming event stream** so your app reacts to model output incrementally, identically across providers: - **`start`** — stream begins (initial assistant message structure). - **`text_start` / `text_delta` / `text_end`** — a text block begins, receives chunks (`delta`), and completes (full `content`), each with a `contentIndex` position. - **`thinking_start` / thinking deltas** — extended-thinking/reasoning blocks (for models that expose them). - Tool-call and completion events follow the same shape. Because every provider is mapped onto these events, switching models is a config change, not a rewrite — and UIs/agents consume one event format. ## Why it matters Provider APIs diverge in streaming formats, thinking/reasoning support, tool-call encodings, and content-block structure. `pi-ai` absorbs that so the rest of Pi (and your code) sees a single model abstraction. Provider/model configuration — including custom and OpenAI-compatible endpoints — is covered in [models-and-providers](models-and-providers.md). --- title: "Quickstart & Usage" type: concept tags: [quickstart, install, usage, tui] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-quickstart-md.md, raw/github_doc-packages-coding-agent-docs-usage-md.md] --- # Quickstart & Usage ## Install Install via your package manager (or the curl installer, which uses global npm). `--ignore-scripts` is safe — pi doesn't require dependency lifecycle scripts for normal installs. Uninstalling with the same manager that installed it leaves your settings, credentials, sessions, and installed pi packages in `~/.pi/agent/`. ## First session After install, run pi in a project directory to start an interactive [TUI](tui-and-customization.md) session, configure a [provider/model](models-and-providers.md), and start prompting. The quickstart takes you "from install to a useful first pi session." ## Interactive usage essentials - **File reference** — type `@` to fuzzy-search and attach project files. - **Shell command** — `!command` runs a shell command and sends its output to the model. - **Multi-line input** — Shift+Enter (Ctrl+Enter on Windows Terminal). - **Images** — paste with Ctrl+V (Alt+V on Windows) or drag into the terminal. - **Slash commands** — `/compact`, `/fork`, `/clone`, `/share`, `/tree`, etc. ([sessions](sessions.md)). ## Where to go next - Configure behavior in [settings/keybindings/themes](tui-and-customization.md). - Add capabilities with [extensions and pi packages](extensions-and-packages.md) and [skills](skills.md). - Run non-interactively (print/JSON/RPC/SDK) via [integration-modes](../syntheses/integration-modes.md). - Terminal/OS setup (tmux, Windows, Termux) in [runtime-environments](runtime-environments.md). --- title: "Runtime Environments & Containerization" type: concept tags: [containerization, tmux, windows, termux, environments] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-containerization-md.md, raw/github_doc-packages-coding-agent-docs-tmux-md.md, raw/github_doc-packages-coding-agent-docs-windows-md.md, raw/github_doc-packages-coding-agent-docs-termux-md.md, raw/github_doc-packages-coding-agent-docs-terminal-setup-md.md] --- # Runtime Environments & Containerization Pi runs across many terminals and platforms; these docs cover making it work well in each. ## Containerization Run pi **inside a container** to sandbox what the agent can touch and to get reproducible environments. Because pi is otherwise local-first and runs with your user's permissions (not a sandbox by itself — [security](security.md)), containerization is the recommended way to bound an autonomous agent's blast radius and to give it an isolated, dependency-complete workspace. ## Platforms - **Windows** — supported with Windows-specific input notes (Ctrl+Enter for newline, Alt+V to paste images). - **Termux** — run pi on Android via Termux. - **macOS/Linux** — first-class. ## Terminal integration - **tmux** — running pi inside tmux (panes, persistence, integration notes). - **Terminal setup** — getting the best experience (true color, key protocols like Kitty for key-release events, fonts) so the [TUI](tui-and-customization.md) renders correctly. - **Shell aliases** — convenience aliases for common pi invocations. ## Why it matters The same agent runs identically whether local, in tmux on a server, in a container in CI, or on a phone — and containerization is the bridge between "local coding agent" and "safely autonomous agent." For non-interactive/embedded runs across these environments, see [integration-modes](../syntheses/integration-modes.md). --- title: "Security & Project Trust" type: concept tags: [security, trust, permissions, sandbox] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-security-md.md, raw/github_doc-security-md.md] --- # Security & Project Trust ## The trust model Pi is a **local coding agent**: it runs with the **permissions of the user account that starts it**, and treats files writable by that user as inside the same local trust boundary. Critically, **pi is not a sandbox** — it does not restrict what the model can do beyond those OS permissions. Bounding the agent is your responsibility (e.g. [containerization](runtime-environments.md), least-privilege accounts). ## Project trust **Project trust** controls whether pi loads **project-local settings, resources, packages, and extensions**. Pi considers a project to require trust when it finds project-local resources (settings/extensions/packages) under the working directory — so opening an untrusted repo won't silently execute its `.pi/` extensions or apply its settings until you trust it. This is the defense against "clone a malicious repo, run pi, get owned." ## Practical guidance - **Review before trusting** an unfamiliar project — its `.pi/extensions` are code that will run. - **Containerize** autonomous or untrusted-input runs to cap blast radius ([runtime-environments](runtime-environments.md)). - **Protect credentials** in `~/.pi/agent/` (provider keys live there — [models-and-providers](models-and-providers.md)). - **Review sessions before `/share`** — they can contain secrets/source ([sessions](sessions.md)). - Treat tool calls and `!shell` commands as running with your full user permissions. When embedding pi via the [SDK](../syntheses/integration-modes.md) (as OpenClaw does), the host application is responsible for sandboxing and approvals around the agent. --- title: "Sessions" type: concept tags: [sessions, fork, branches, sharing] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-sessions-md.md, raw/github_doc-packages-coding-agent-docs-session-format-md.md] --- # Sessions A **session** is a persisted conversation/run with the [coding agent](coding-agent-overview.md), stored under `~/.pi/agent/`. Sessions are first-class: you can branch, fork, resume, and share them. ## Session commands - **`/fork`** — create a new session starting from a previous user message (explore an alternative without losing the original). - **`/clone`** — duplicate the current active branch into a new session. - **`/tree`** — navigate the branch tree (triggers branch summarization to preserve context when switching). - **`/compact [prompt]`** — summarize older context to free the window ([compaction-and-context](../syntheses/compaction-and-context.md)). - **`/share`** — upload the session as a **private GitHub gist** with a shareable HTML link. ## Branching model Sessions form a **tree**: forking/cloning creates branches from any point, so you can try different approaches from the same history and move between them. Switching branches uses branch summarization to keep relevant context. ## Session format Sessions persist in a documented **session format** (the `session-format` doc) — a structured record of messages, tool calls/results, and metadata. Because the format is documented and sessions are plain files, you can inspect, process, or build tooling over them (and the `--json` mode emits compatible structured output — [integration-modes](../syntheses/integration-modes.md)). ## Sharing for OSS The project encourages sharing OSS coding sessions publicly (`/share`): real development workflows help improve models, prompts, tools, and evals ([what-is-pi](what-is-pi.md)). Sessions may contain sensitive content — review before sharing ([security](security.md)). --- title: "Skills" type: concept tags: [skills, capabilities, prompts] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-skills-md.md, raw/github_doc-packages-coding-agent-docs-extensions-md.md, raw/github_doc-packages-coding-agent-docs-packages-md.md] --- # Skills **Skills** are model-facing capability descriptions — focused instructions (and often supporting tools/files) that tell the agent *what a capability does and when to use it*. They're how you teach pi to handle a class of task well. ## Shape A skill carries a **description**: "what this skill does and when to use it — be specific." The model reads the description to decide when to invoke the skill. Examples from the docs: - PDF processing — "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents." - Web search — "Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content." ## Compatibility Pi's skills align with the broader **Anthropic Skills** ecosystem — document processing (docx, pdf, pptx, xlsx), web development, and more — so existing skills can be reused. A skill bundles a clear trigger description with whatever scripts/resources implement it. ## Skills vs extensions - **Skills** are primarily *what the model sees* — capability descriptions that shape when the agent reaches for a tool/workflow. - **[Extensions](extensions-and-packages.md)** are *code* that adds tools, commands, hooks, or modes to the harness. They compose: an extension can register tools, and a skill tells the model when to use them. Both are loaded per project (subject to [trust](security.md)) or globally, and distributable as [pi packages](extensions-and-packages.md). --- title: "TUI, Themes & Customization" type: concept tags: [tui, themes, keybindings, settings, rendering] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-tui-readme-md.md, raw/github_doc-packages-coding-agent-docs-tui-md.md, raw/github_doc-packages-coding-agent-docs-themes-md.md, raw/github_doc-packages-coding-agent-docs-settings-md.md, raw/github_doc-packages-coding-agent-docs-keybindings-md.md] --- # TUI, Themes & Customization ## pi-tui **@earendil-works/pi-tui** is a terminal UI library with **differential rendering** — it only repaints what changed, keeping the interactive coding session smooth. It's a standalone package (usable outside pi) and powers the coding agent's interface. ## The component model TUI components implement a small contract: - **`render(width)`** — return an array of strings (one per line); each line **must not exceed `width`**. - **`handleInput?(data)`** — receive keyboard input when focused. - **`wantsKeyRelease?`** — opt into key-release events (Kitty protocol). - **`invalidate()`** — clear cached render state (called on theme changes). [Extensions](extensions-and-packages.md) can add custom TUI components (overlays, panels) via this API. ## Customization - **Settings** — `~/.pi/agent/settings.json` (global) and `.pi/settings.json` (project): models/providers, `reserveTokens`, behavior toggles. - **Themes** — color themes for the TUI; switching invalidates component render caches. - **Keybindings** — remappable; defaults documented. ## Terminal niceties The coding agent's interactive mode supports `@` file fuzzy-search, `!` shell commands, image paste/drag, and multi-line input ([quickstart-and-usage](quickstart-and-usage.md)). Terminal/OS-specific setup (tmux, Windows Terminal, Termux, shell aliases, terminal-setup) is in [runtime-environments](runtime-environments.md). --- title: "What is Pi" type: concept tags: [pi, agent-toolkit, overview, monorepo] updated: 2026-06-19 confidence: high sources: [raw/github_doc-readme-md.md, raw/github_doc-packages-coding-agent-readme-md.md] --- # What is Pi **Pi** (`earendil-works/pi`) is an **AI agent toolkit** — a set of composable packages for building LLM applications and agents, plus a ready-to-use coding agent CLI. It's a monorepo of four published packages: | Package | What it is | |---|---| | **@earendil-works/pi-ai** | Unified multi-provider LLM API (OpenAI, Anthropic, Google, …) with streaming ([pi-ai-unified-llm-api](pi-ai-unified-llm-api.md)) | | **@earendil-works/pi-agent-core** | Agent runtime with tool calling and state management ([agent-core-and-harness](agent-core-and-harness.md)) | | **@earendil-works/pi-coding-agent** | Interactive coding agent CLI ([coding-agent-overview](coding-agent-overview.md)) | | **@earendil-works/pi-tui** | Terminal UI library with differential rendering ([tui-and-customization](tui-and-customization.md)) | (A separate `earendil-works/pi-chat` adds Slack/chat automation.) ## The philosophy Pi is **"a minimal terminal coding harness. Adapt pi to your workflows, not the other way around"** — extend it with TypeScript rather than forking internals. It ships powerful defaults but deliberately **skips features like sub-agents and plan mode**; instead you ask pi to build them or install a third-party **pi package** ([extensions-and-packages](extensions-and-packages.md)). ## Layered design The packages stack: `pi-ai` (talk to any model) → `pi-agent-core` (run an agent loop with tools) → `pi-coding-agent` (a full coding agent with TUI) — each usable on its own. This is why other products build on Pi: notably **OpenClaw uses pi's SDK** as a real-world embedding. ## Four ways to run the coding agent Interactive, print/JSON (one-shot), RPC (process integration), and SDK (embed in your app) — see [integration-modes](../syntheses/integration-modes.md). Start at [quickstart-and-usage](quickstart-and-usage.md). Full map: [docs-catalog](../summaries/docs-catalog.md). --- title: "The pi CLI" type: entity tags: [cli, pi-command, modes] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-readme-md.md, raw/github_doc-packages-coding-agent-docs-usage-md.md, raw/github_doc-packages-coding-agent-docs-shell-aliases-md.md] --- # The pi CLI `pi` is the command for the [coding agent](../concepts/coding-agent-overview.md) — the primary entry point, runnable in four modes. ## Modes (one CLI, four shapes) - **Interactive** — `pi` in a project starts the [TUI](../concepts/tui-and-customization.md) session. - **Print / JSON** — non-interactive one-shot: pass a prompt, get text or `--json` structured output (scripting/CI). - **RPC** — long-running process speaking a JSON-RPC-style protocol for [integration](../syntheses/integration-modes.md). - **SDK** — not the CLI per se, but the embedding path for apps. ## Interactive essentials `@` fuzzy-find files, `!cmd` run shell and feed output to the model, multi-line via Shift+Enter, image paste/drag, and slash commands (`/compact`, `/fork`, `/clone`, `/share`, `/tree`) — see [sessions](../concepts/sessions.md) and [quickstart-and-usage](../concepts/quickstart-and-usage.md). ## State & config Global state under `~/.pi/agent/` (settings, credentials, sessions, installed packages); project config under `.pi/` (subject to [trust](../concepts/security.md)). **Shell aliases** streamline common invocations. ## Install/uninstall Installed via your package manager or the curl installer (global npm); uninstall with the same manager. Uninstalling leaves `~/.pi/agent/` intact ([quickstart-and-usage](../concepts/quickstart-and-usage.md)). The CLI is one consumer of the underlying [agent core](../concepts/agent-core-and-harness.md) + [pi-ai](../concepts/pi-ai-unified-llm-api.md) packages, which you can also use directly. --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion ### 2026-06-19 00:00 — Initial curation (medium rung) - **Source/Trigger**: 40 earendil-works/pi monorepo docs (per-package fetchers) - **Pages created**: 13 concepts, 1 entity (pi-cli), 1 summary (docs-catalog), 2 syntheses (integration-modes, compaction-and-context) - **Pages updated**: index.md - **Notes**: Pi = AI agent toolkit (pi-ai + pi-agent-core + pi-coding-agent + pi-tui), ~64k stars, no docs site (first-party READMEs+docs only). Post-cutoff; curated strictly from repo. Notable: OpenClaw embeds pi via its SDK. Category: agents. --- title: "Docs Catalog" type: summary tags: [catalog, map, packages, reference] updated: 2026-06-19 confidence: high sources: [raw/github_doc-readme-md.md, raw/github_doc-packages-coding-agent-docs-index-md.md] --- # Docs Catalog Map of the Pi monorepo docs this wiki distills (earendil-works/pi; mirrored in `raw/` as `github_doc-.md`). ## Packages | Package | Raw prefix | Wiki coverage | |---|---|---| | pi-ai | `packages-ai-readme` | [pi-ai-unified-llm-api](../concepts/pi-ai-unified-llm-api.md) | | pi-agent-core | `packages-agent-readme`, `packages-agent-docs-*` (agent-harness, durable-harness, hooks, observability) | [agent-core-and-harness](../concepts/agent-core-and-harness.md), [agent-events-and-hooks](../concepts/agent-events-and-hooks.md) | | pi-coding-agent | `packages-coding-agent-readme`, `packages-coding-agent-docs-*` | most concept pages | | pi-tui | `packages-tui-readme` | [tui-and-customization](../concepts/tui-and-customization.md) | ## coding-agent docs → wiki | Docs | Wiki | |---|---| | quickstart, usage | [quickstart-and-usage](../concepts/quickstart-and-usage.md) | | models, providers, custom-provider | [models-and-providers](../concepts/models-and-providers.md) | | sessions, session-format | [sessions](../concepts/sessions.md) | | extensions, packages | [extensions-and-packages](../concepts/extensions-and-packages.md) | | skills | [skills](../concepts/skills.md) | | tui, themes, keybindings, settings | [tui-and-customization](../concepts/tui-and-customization.md) | | containerization, tmux, windows, termux, terminal-setup, shell-aliases | [runtime-environments](../concepts/runtime-environments.md) | | security | [security](../concepts/security.md) | | sdk, rpc, json | [integration-modes](../syntheses/integration-modes.md) | | compaction | [compaction-and-context](../syntheses/compaction-and-context.md) | ## Not reproduced Exact API signatures for the SDK/RPC, the full settings schema, and per-provider config keys are in the source docs — read the specific `raw/` page. The separate **pi-chat** repo (Slack/chat automation) is out of scope. Pi moves fast — verify version-specific details against the repo. --- title: "Compaction & Context Management" type: synthesis tags: [compaction, context, branches, tokens, synthesis] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-compaction-md.md, raw/github_doc-packages-coding-agent-docs-sessions-md.md, raw/github_doc-packages-coding-agent-docs-settings-md.md] --- # Compaction & Context Management Long coding sessions outgrow any model's context window; Pi manages this with compaction and branch summarization. ## Compaction When **context exceeds a threshold** (or you run **`/compact [prompt]`**), Pi **summarizes older messages** into a structured summary to free up the window while preserving what matters. An optional prompt steers what the summary emphasizes. ## Branch summarization Navigating the session tree with **`/tree`** triggers **branch summarization** to preserve context when switching branches ([sessions](../concepts/sessions.md)). Compaction and branch summarization **use the same structured summary format** and both **track file operations cumulatively** — so the agent doesn't "forget" which files it changed across a compaction. ## reserveTokens A configurable **`reserveTokens`** (default **16384**) is held back to leave room for the LLM's response — set in `~/.pi/agent/settings.json` or `.pi/settings.json` ([tui-and-customization](../concepts/tui-and-customization.md)). Tune it against your chosen [model's](../concepts/models-and-providers.md) context size: too low risks truncated responses, too high triggers compaction sooner. ## Practical implications - **`/compact` proactively** before a big new task to start it with clean, summarized context. - **Fork instead of compact** when you want to keep the full original thread ([sessions](../concepts/sessions.md)). - File-operation tracking means post-compaction the agent still knows the working set — important for multi-step refactors. This is the coding-agent's counterpart to the lower-level context handling in the [agent core](../concepts/agent-core-and-harness.md); both keep runs coherent within token limits. --- title: "Integration Modes: Interactive, Print, RPC, SDK" type: synthesis tags: [sdk, rpc, json, print, embedding, synthesis] updated: 2026-06-19 confidence: high sources: [raw/github_doc-packages-coding-agent-docs-sdk-md.md, raw/github_doc-packages-coding-agent-docs-rpc-md.md, raw/github_doc-packages-coding-agent-docs-json-md.md, raw/github_doc-packages-coding-agent-readme-md.md] --- # Integration Modes: Interactive, Print, RPC, SDK Pi's coding agent runs four ways; pick by how tightly you're integrating. ## 1. Interactive The [TUI](../concepts/tui-and-customization.md) session for a human at a terminal ([quickstart-and-usage](../concepts/quickstart-and-usage.md)). Use for hands-on coding. ## 2. Print / JSON (one-shot) Pass a prompt, get a single result and exit. Plain text for humans/scripts, or **`--json`** for **structured output** (the `json` doc) you can parse in CI or pipelines. Use for: code review bots, batch tasks, git hooks, anything non-interactive and stateless-per-call. ## 3. RPC (process integration) A long-lived pi process speaking a JSON-RPC-style protocol over stdio: you send requests and **subscribe to the event stream** — `agent_end`, `turn_end`, `message_update` (text/thinking/toolcall deltas), `tool_execution_update` (streaming tool output). Use when an external process (editor, daemon, another service) needs a persistent, streaming agent it controls — without embedding TypeScript. ## 4. SDK (embed) Import pi's agent into your **own TypeScript app** for full programmatic control — build custom interfaces, embed agent capabilities, or integrate with automated workflows. This is the deepest integration: you own the loop, UI, and orchestration around pi's [agent core](../concepts/agent-core-and-harness.md). **OpenClaw embeds pi via the SDK** as a real-world example ([what-is-pi](../concepts/what-is-pi.md)). ## Choosing | Need | Mode | |---|---| | Human coding session | Interactive | | One-shot/script/CI | Print or `--json` | | External process drives a persistent agent | RPC | | Full embed in a TS app | SDK | All four share the same [events](../concepts/agent-events-and-hooks.md), [sessions](../concepts/sessions.md), [providers](../concepts/models-and-providers.md), and [extensions](../concepts/extensions-and-packages.md) — you're choosing a transport, not a different agent. Pi can help build the integration itself ("ask it to build an integration for your use case").