Pi is a minimal, terminal-based coding harness designed for aggressive extensibility, allowing users to adapt it to their workflows rather than conforming to a fixed set of features. Its core philosophy emphasizes a small, composable core that prioritizes user control and customization via a robust extension system, rather than baking in complex features like sub-agents or plan modes. These advanced functionalities are instead intended to be built by the user as extensions or installed as community-contributed packages.

The system operates in four primary modes: an interactive TUI (Text User Interface), a print/JSON mode for scripting and event streams (pi -p "query", --mode json), an RPC mode using a JSON protocol over stdin/stdout for non-Node integrations, and an SDK for embedding pi directly into applications.

Context management is a key aspect, designed to facilitate precise "context engineering." Pi employs a minimal default system prompt, which can be augmented or replaced per-project via SYSTEM.md files located hierarchically (current directory, parent directories, ~/.pi/agent/). Project-specific instructions are loaded from AGENTS.md following a similar hierarchy. To manage token limits and maintain contextual relevance, pi includes an auto-summarization feature called "compaction," which processes older messages. This compaction mechanism is fully customizable through extensions, enabling sophisticated strategies such as topic-based summarization or the use of different summarization models. Dynamic context injection is also supported, where extensions can programmatically inject messages before each turn, filter message history, implement Retrieval-Augmented Generation (RAG), or manage long-term memory.

Extensibility is achieved through several mechanisms:

1. Extensions: These are the primary primitive for customization, implemented as TypeScript modules. They provide access to the agent's internal tools, commands, keyboard shortcuts, events, and the full TUI, allowing users to build highly integrated features. Examples include custom sub-agents, plan modes, permission gates, custom editors, and status bars.
2. Skills: Representing capability packages, skills bundle instructions and tools. They are loaded on-demand, enabling progressive disclosure of functionalities and optimizing prompt cache utilization by avoiding pre-loading capabilities not immediately required.
3. Prompt Templates: Reusable Markdown files that can be expanded into messages or instructions by typing a command like /name.
4. Packages: Extensions, skills, prompt templates, and themes can be bundled into "pi packages" and shared or installed from public registries like npm (__INLINE_FORMULA_0__ pi install git:github.com/badlogic/pi-doom). Version pinning is supported, and packages can be tested without installation using the -e flag.

Pi supports a wide range of LLM providers and models (over 15 providers and hundreds of models, including Anthropic, OpenAI, Google, Azure, Mistral, Groq, etc.), authenticated via API keys or OAuth. Users can switch models mid-session or cycle through favorites. Custom providers and models can be added via a models.json configuration file or extensions.

Session management is robust, featuring a tree-structured history where all branches are stored in a single file. Users can navigate to any previous point using /tree and continue from there, effectively branching conversations. Messages can be filtered by type and labeled as bookmarks. Sessions can be exported to HTML with /export or shared as GitHub gists via /share, which generates a shareable URL for rendering the session.

The design consciously omits certain features found in other agents, such as multi-agent communication protocols (MCP), built-in sub-agents, permission popups, integrated plan modes, or to-do lists. The rationale is that these can be implemented as extensions or external tools, promoting modularity and preventing vendor lock-in, allowing users to tailor the system precisely to their specific security, workflow, and interaction preferences. For instance, sub-agents can be managed by spawning multiple pi instances via tmux, or by custom extensions, while planning can involve writing plans to external files or building an extension for a dedicated plan mode.