Docs

Welcome to the Pi Agent documentation. Pi is a toolkit, not a single product, so the docs are organized around the layers and packages that make it up. Browse by topic — from architecture to hands-on — and we recommend reading the overall architecture first, then diving in as needed. Everything here is derived from the open-source earendil-works/pi repository, which remains the authoritative source.

How the documentation is organized

The reference pages map to Pi's three architectural layers. The interaction layer is what you touch (the terminal UI, the RPC server, or the SDK); the runtime layer is where a session becomes an agent and events start flowing; and the core loop is the stable piece that calls the model, runs your tools, and writes results back. Keeping these separate is the whole point: you can replace a model, swap a UI, or load a new tool without touching the loop.

Common tasks, by page

If you arrived with a specific question, these pointers should get you there fast:

• "How is Pi put together?" → Architecture. Read this first; the rest of the docs assume it.
• "What does each package do?" → Core packages. Use this when deciding what to import.
• "How do messages, tools and sessions work?" → Core concepts. Essential before you write code.
• "How do I run it safely / debug it?" → Running & debugging. Permissions, sandboxes and supply-chain details.
• "Which model can I use?" → Model providers. Connection strings and switching vendors.
• "Is Pi the right tool for me?" → Compare. Pi vs Aider / Claude Code / OpenHands.

Import cheat sheet

When you start coding, these are the packages you will import:

import { Agent, tool } from '@earendil-works/pi-agent-core';
import { createModel } from '@earendil-works/pi-ai';
// pi-coding-agent -> the CLI you launch with ./pi-test.sh
// pi-tui          -> the terminal UI library

Each line maps to one of the four core packages. The Core packages page explains boundaries; the Chinese first-agent tutorial walks through a full example.

Glossary

• Agent — the runtime that holds your tools and a model, and knows how to run the loop.
• Session — one conversation's context: messages, state and branches, persisted as a JSONL tree.
• Tool — a function the agent can call; defined by you and dispatched by the runtime.
• Extension — code loaded at runtime that adds new tools, resources or behavior without a rebuild.

Reading path

Not sure where to begin? Pick the path that matches what you are trying to do:

• Just arriving: start with Quick Start, then Architecture so the rest of the docs make sense.
• Building on top: focus on Core packages and Core concepts, then read Running & debugging before you ship.
• Choosing a tool: open Compare for the Pi vs alternatives breakdown.
• Deploying / troubleshooting: go straight to Running & debugging for permissions and supply-chain details.

Two languages, one site

These docs have a Chinese edition and an English edition. Each page links to its counterpart with hreflang tags, so search engines can serve the right language to the right reader. If you landed here in the wrong language, use the EN switch in the menu, or jump to the Chinese home page. The deep reference pages (architecture, packages, concepts, run, models) live in Chinese; the English edition covers the home, docs hub, compare and quick start entry points.

Staying current

Pi moves fast — 4921+ commits and counting. The most reliable way to stay current is to watch the GitHub repository for releases, and to re-read the architecture page when a major version lands, since the core-loop contract is what we work hard to keep stable.

Not finding what you need? The reference pages are concise by design. If a topic is missing, the source repository and its issues are the best next stop, and the Chinese edition often carries the deepest reference material for the four core packages.