How Pi Works: Agent Architecture, Tools, Interactive UI, and Skills

Two‑Layer Structure

Pi separates the system into an Agent Core that drives the autonomous loop—reading context, invoking the language model, parsing output, executing tools, and writing results back—and a surrounding Pi Interactive layer that presents the terminal UI, input box, streaming output, session switching, and command panel.

Agent Loop

Each iteration follows a fixed process: assemble the current context and send it to the model; the model either returns a final answer or a tool‑call request; if a tool is needed, Pi executes it, appends the result to the dialogue, and calls the model again. This repeats until the task completes. Pi limits the system prompt to under 1,000 tokens because the context window is finite.

Layered Context Construction

The context is built in five stacked layers:

Base System Prompt – a concise description that the model is a programming agent with specific tools.

Global user preferences – e.g., preferred code style.

Project‑specific directives – a config file in the project root can enforce commands such as using uv for Python or running a linter before commit.

Skill instructions – structured commands that guide the model for particular tasks.

User message – the actual request from the user.

Three Major Extension Mechanisms

Tools : Pi ships with four built‑in tools – read (read file), write (write file), edit (edit file), and bash (execute command).

Extensions : A mechanism to inject new capabilities without altering the core. Extensions can add tools, modify prompts, persist state to session files, and even let the agent write, hot‑load, test, and iterate its own extensions.

Skills : A Skill is a piece of structured instruction that tells the model how to act on a specific task—what files to read, which commands to run, where to pause for human confirmation. Skills are loaded into the context only when needed and discarded afterward, keeping the dialogue clean.

Why This Architecture Works

Pi demonstrates that an agent’s capability ceiling is determined by the clarity of its architecture rather than the sheer number of tools. By composing simple, well‑defined modules—core loop, context builder, tool system, sessions, extensions, TUI, and compaction + Skills—the system remains powerful yet easy to understand.

Key Components Overview

Core Loop – communication with the model.

Context Builder – assembles prompts and history.

Tool System – enables the model to act.

Sessions – preserve state across loops.

Extensions – add optional abilities.

TUI – wraps functionality into a usable interface.

Compaction + Skills – support long‑running workflows.