Pi Agent proposes an alternative to coding agents that have steadily accumulated features, tools and automation. Its approach is straightforward: keep the agent’s core small, make the context received by the model visible, and let developers add only the capabilities they need through extensions, skills and prompt templates.
The project, created by Mario Zechner and released as open source, has built a significant community on GitHub. Its design revolves around four basic tools, a compact system prompt and an extensible architecture that can add everything from subagents and planning modes to MCP (Model Context Protocol) integrations and custom permission controls.
The key points about Pi Agent in 30 seconds
- Pi keeps the agent’s core to a small set of tools and keeps the system prompt below 1,000 tokens.
- Sessions are stored as JSONL files in a tree structure, allowing developers to revisit earlier points and create new branches.
- The model can be switched during the same session without losing the working context.
- Extensions, Skills and prompt templates can add capabilities that other agents include directly in their core.
- The project does not include its own sandbox. Isolation is left to the operating system, containers or virtual machines.
The approach responds to a growing concern among developers who use coding agents every day: what is the agent actually doing, and what information is the model receiving before each request?
Tools such as Claude Code, Codex and OpenCode have gradually added subagents, background execution, MCP, planning modes and other capabilities. These features can simplify certain tasks, but they also introduce components that users cannot always see directly.
Pi takes the opposite approach. Instead of building all those capabilities into the core, it leaves them out and provides mechanisms for adding them when they are needed.
An agent designed to keep context visible
One of Pi’s central design decisions concerns the prompt and the tools available to the model.
The project keeps the system prompt below 1,000 tokens and exposes its contents. The goal is to reduce the amount of instruction that is automatically added to the context and give developers a clearer view of what the model is actually receiving.
The creator also questions the cost of permanently loading MCP tool definitions. According to Zechner’s analysis, some integrations can introduce dozens of tools and consume thousands of tokens before a task even begins.
Pi’s alternative is to use command-line tools and load additional instructions only when they are needed. Skills follow the same philosophy: they are SKILL.md files that describe procedures and can be brought into the context when a task requires them.
The goal is not to eliminate extensions, but to put the decision in the hands of the user.
Visible subagents instead of hidden processes
The same principle applies to subagents.
Instead of running secondary agents and presenting only a summary of their work, Pi can use independent sessions displayed through tmux. This allows the developer to observe the interactions between the different agents.
It is primarily a design choice rather than a question of capability. Pi does not aim to make agents less capable, but rather to avoid making those capabilities mandatory parts of the core.
According to the source material, the idea was partly inspired by Terminus, a harness used in agent evaluations. Its approach was particularly simple: provide the model with a tool for interacting with a tmux session, requiring it to work with keyboard input and the ANSI sequences returned by the terminal.
For Pi, this demonstrates that current models can work effectively within a programming environment without necessarily requiring a large abstraction layer on top.
Switching models without abandoning the session
One of the more interesting features for developers is the ability to switch providers during the same session.
Pi serializes its context in a provider-independent format. As a result, according to the material provided, a session started with Anthropic can later continue with an OpenAI or Google model without having to start from scratch.
The switch can be made using /model or Ctrl+L.
Pi also standardizes how reasoning levels are presented. Capabilities that each provider names differently, such as Anthropic’s extended thinking or OpenAI’s reasoning levels, are presented through a common five-level scale ranging from minimal to xhigh.
The project supports more than 15 providers and allows custom providers to be added through ~/.pi/agent/models.json. It can also connect to OpenAI- or Anthropic-compatible APIs and local models through systems such as llama.cpp.
This architecture reduces dependence on a specific provider and allows developers to change models within the same workflow.
Sessions work like a tree
Pi uses JSONL (JSON Lines) to store sessions. Each entry has an identifier and a parentId, creating a tree structure.
The difference from a linear conversation becomes apparent when a developer wants to revisit an earlier decision. With /tree, they can return to a specific point in the session and continue from there using a new branch.
The system keeps the complete history in the file, while /compact can summarize older messages to reduce the active context. Automatic compaction can also take effect when the context reaches its limit.
The separation is straightforward: the session history preserves what happened, while files such as AGENTS.md or CLAUDE.md can store project instructions and conventions that should remain available.
Advanced features are added through extensions
Pi is designed so that many features included by default in other coding agents can be added later.
Extensions are written in TypeScript and can add tools, commands, shortcuts, interface elements and event handlers. They can also intercept tool calls.
For example, developers can create an extension that blocks potentially destructive commands or asks for confirmation before executing them. Extensions can also implement Git checkpoints, automatic commits, custom subagents, planning modes or MCP integrations.
Above that layer are Skills, written in Markdown and compatible with the Agent Skills standard, and Prompt Templates, which allow reusable instructions to be stored.
Packages can be distributed through npm or Git and managed from the agent itself using commands such as pi install, pi list and pi update.
The result is that two Pi installations can have very different capabilities while using the same core.
Pi Web brings sessions to the browser
The project also includes a web interface called Pi Web. According to the source material, it allows users to browse, resume, rename and delete sessions, as well as create branches from existing conversations.
The interface can display project files and Git diffs, switch between worktrees, and manage providers, models, packages and Skills.
Because it shares configuration and session files with the terminal version, the browser acts as another interface to the same working environment.
Security depends on the execution environment
There is an important difference between Pi and some projects that integrate isolation mechanisms directly: Pi does not include its own sandbox.
Read, write, edit and command-execution operations run with the permissions of the user who launches the agent. Extensions have the same privileges.
The project’s approach is that genuine isolation should be provided through the operating system, containers or virtual machines. For untrusted repositories and unattended execution, the supplied material recommends using an isolated environment.
Pi also has a project trust mechanism that asks for confirmation when working with unverified projects before allowing certain configuration changes. However, this protection does not completely eliminate the risk of prompt injection.
That decision fits the project’s broader philosophy: keep the agent small and move certain responsibilities to the environment in which it runs.
Pi Agent does not remove the capabilities offered by other coding agents. It places them at a different level. The core remains small, while additional capabilities become components that developers can install, write or remove according to their needs.
For developers working with coding agents who want greater visibility into which tools, instructions and context are involved in each execution, this approach offers a concrete alternative to increasingly automated agent designs. Its main proposition is not to add another feature to the list, but to give the user more control over what goes into that list.
Frequently asked questions
What is Pi Agent?
Pi is a terminal-based coding agent designed around a small core that can be extended through extensions, Skills and prompt templates.
Can you switch models during a session?
Yes. Pi uses a provider-independent context format and allows users to switch models with /model or Ctrl+L without leaving the session.
How does Pi store sessions?
Sessions are stored as JSONL files with identifiers and parentId relationships. This structure allows /tree to return to earlier points and create new branches.
Does Pi have a built-in sandbox?
No. Its tools run with the user’s permissions. To isolate untrusted code, the project recommends external mechanisms such as containers or virtual machines.