$ pi –explain-yourself

Pi is deliberately a small core with sharp edges. Understanding a handful of concepts — the agent loop, tools, context files, models, and sessions — explains almost everything the CLI does. Everything else (permissions, plan mode, sub-agents, MCP) is intentionally left to extensions.

The agent loop

At runtime Pi is an instance of @earendil-works/pi-agent-core: a stateful agent with tool execution and event streaming, built on @earendil-works/pi-ai (a unified multi-provider LLM API covering OpenAI, Anthropic, Google, and more).

When you send a prompt, the loop runs:

Your message is appended to the session state.
The context — system prompt, context files, conversation history — is assembled and sent to the model.
The model streams a response. It may end the turn with text, or request tool calls.
Each tool call executes (reading a file, running a command), and its result is appended to the conversation.
Steps 2–4 repeat — this is one “turn” cycling — until the model responds without calling tools.

Internally, the agent emits a typed event stream (agent_start, turn_start, message_start, message_update, tool_execution_start, tool_result, turn_end, agent_end, …). The TUI renders these events; extensions subscribe to the same stream to intercept or augment behavior.

Internally the agent distinguishes AgentMessage (which can carry UI-only or custom message types) from the plain user / assistant / toolResult messages an LLM understands. A convertToLlm step filters and transforms history before each model call.

Built-in tools

By default the model gets four tools:

read — read files
write — create or overwrite files
edit — patch files
bash — run shell commands

Additional read-only tools — grep, find, ls — are available through tool options. You control the tool surface from the CLI:

pi --tools read,grep,find,ls -p "Review the code"   # read-only run
pi --exclude-tools bash                              # everything except bash
pi --no-builtin-tools                                # extensions/custom tools only
pi --no-tools                                        # pure chat

Extensions can register their own tools and even override built-ins by registering a tool with the same name.

Context files (AGENTS.md)

Pi loads context files at startup to learn how to work in your project:

~/.pi/agent/AGENTS.md — global instructions, always loaded
AGENTS.md or CLAUDE.md — from parent directories (walking up from the cwd) and the current directory

A typical project file:

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Disable loading with --no-context-files (-nc). After editing context files, restart Pi or run /reload.

You can also replace the system prompt entirely with .pi/SYSTEM.md (project) or ~/.pi/agent/SYSTEM.md (global), or append to it with APPEND_SYSTEM.md in either location.

@-file references and shell escape

Two editor features bridge your filesystem and the conversation:

Type @ to fuzzy-search project files and attach them to your message. On the command line: pi @src/app.ts @src/app.test.ts "Review these together". Images work too: pi -p @screenshot.png "What's in this image?".
!command runs a shell command and injects its output into the model context; !!command runs it without polluting context.

Models and providers

Pi ships with built-in provider catalogs (cached in ~/.pi/agent/models-store.json for offline use). Credentials come from OAuth subscriptions (/login), environment variables, or ~/.pi/agent/auth.json — Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, xAI, OpenRouter, Mistral, Cerebras, and many more; cloud providers (Bedrock, Azure, Vertex) and local models via llama.cpp are also supported. Extensions can register entirely custom providers with pi.registerProvider().

Switching models is a first-class operation:

/model or Ctrl+L — open the model picker
Ctrl+P / Shift+Ctrl+P — cycle through your scoped models (configure with /scoped-models or --models "claude-*,gpt-4o")
Shift+Tab — cycle the thinking level (off, minimal, low, medium, high, xhigh, max)

From the CLI:

pi --model openai/gpt-4o "Help me refactor"
pi --model sonnet:high "Solve this complex problem"
pi --list-models anthropic

Set defaults with defaultProvider, defaultModel, and defaultThinkingLevel in ~/.pi/agent/settings.json.

Sessions

Sessions auto-save to ~/.pi/agent/sessions/, organized by working directory. Each session is a JSONL file structured as a tree: every entry has an id and parentId, and your current position is the active leaf. This enables branching workflows:

/tree — jump to any earlier point and continue from there; abandoned branches can be summarized
/fork — create a new session file from a previous user message
/clone — duplicate the current active branch into a new session
/compact [prompt] — summarize older messages to free context (auto-compaction is enabled by default; tune it via compaction.reserveTokens and compaction.keepRecentTokens)

From the shell: pi -c continues the most recent session, pi -r opens a session picker (with rename, delete, and search), --no-session runs ephemerally, and --name labels a session for later retrieval. /export writes a session to HTML; /share uploads a private GitHub gist.

Interfaces: TUI and beyond

The default interface is a TUI built on @earendil-works/pi-tui, a terminal UI library with differential rendering. It has four areas: a startup header (shortcuts, loaded context files, skills, extensions), the message stream, the editor (border color shows the thinking level), and a footer (cwd, session name, token/cache usage, cost, context usage, current model).

But the TUI is only one consumer of the same agent core:

pi -p "..." — print mode: one-shot, non-interactive
--mode json — every event as a JSON line, for scripting
--mode rpc — RPC over stdin/stdout, for embedding Pi in other processes
@earendil-works/pi-agent-core — the runtime as an npm library, for building your own agent apps

What Pi deliberately does not include

No built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. The design philosophy is a minimal core plus an extension system; the rationale is in the author’s blog post.

Core Concepts