2 Preface

2.1 Why This Book

Pi is a terminal coding harness that takes a different approach from most AI coding assistants. Where other tools continuously add features to their core, Pi deliberately stays small and pushes functionality into composable extensions. This design philosophy produces a tool that is:

Minimal — the core is easy to understand and audit
Extensible — every workflow beyond the basics is opt-in
Transparent — sessions are plain JSONL files you can inspect with standard tools
Open — the entire codebase is open source under the MIT License

This book exists because Pi’s documentation, while comprehensive, is structured as a reference. A reference tells you what each feature does. This book tells you how the features fit together, when to use each one, and how to think about building with Pi.

2.2 Pi’s Design Philosophy

2.2.1 Minimal Kernel, Maximum Extension

Pi is built on the conviction that a coding assistant should not be a monolith. The core provides four tools—read, write, edit, and bash—and a robust extension system. Everything else is a choice.

This means Pi does not include:

A built-in MCP server
Sub-agents
Permission popups (beyond project trust)
Plan mode or to-dos
Background bash

Each of these can be added as extensions, skills, or external tools. The difference is that you choose what to install, rather than having every feature baked into a binary you cannot inspect.

2.2.2 Local-First, No False Security

Pi operates on your local source tree with your permissions. It does not pretend to sandbox what it cannot truly isolate. Instead, it provides honest documentation about running untrusted work in containers, VMs, or policy-controlled sandboxes.

2.2.3 Open Standards

Pi implements the Agent Skills standard for cross-harness compatibility. Skills written for Pi can work in other harnesses. Sessions are stored as JSONL, not proprietary databases. Configuration is JSON, not opaque binary formats.

2.3 Who This Book Is For

This book is written for:

Developers who want to use Pi as their daily AI coding assistant
Power users who want to write extensions, skills, and custom providers
Teams who want to standardize their AI-assisted development workflow
Integrators who want to embed Pi’s capabilities into other tools via the SDK, RPC mode, or JSON event stream
Forks who want to build on Pi’s foundation with their own branding

2.4 Book Structure

The book is organized into four sections:

2.4.1 Getting Started (Chapters 1–3)

Chapter 1: Pi Overview — What Pi is, design philosophy, core features
Chapter 2: Quickstart — Installation, authentication, first session
Chapter 3: Using Pi — Interactive mode, commands, CLI reference

2.4.2 Configuration (Chapters 4–8)

Chapter 4: Providers — Authentication and model setup
Chapter 5: Security — Project trust, sandboxing approach, safe practices
Chapter 6: Containerization — Running Pi in isolated environments
Chapter 7: Settings — Global and project configuration
Chapter 8: Keybindings — Keyboard shortcuts and customization

2.4.3 Sessions and Context (Chapters 9–10)

Chapter 9: Sessions — Session management, tree structure, branching
Chapter 10: Compaction & Branch Summarization — Managing context growth

2.4.4 Customization (Chapters 11–17)

Chapter 11: Extensions — TypeScript modules for custom behavior
Chapter 12: Skills — Reusable capability packages
Chapter 13: Prompt Templates — Reusable prompt patterns
Chapter 14: Themes — Visual customization
Chapter 15: Pi Packages — Distributable resource bundles
Chapter 16: Custom Models — Adding providers via configuration
Chapter 17: Custom Providers — Adding providers via extensions

2.4.5 Reference (Chapters 18–23)

Chapter 18: SDK — Programmatic API
Chapter 19: RPC Mode — Bidirectional process communication
Chapter 20: JSON Event Stream Mode — One-way event output
Chapter 21: TUI Components — Terminal UI component system
Chapter 22: Session File Format — JSONL format specification
Chapter 23: Development — Building, forking, and contributing

2.5 How to Read This Book

2.5.1 For New Users

Read chapters 1–3 in order. This gives you enough to start using Pi productively. Then jump to chapter 7 (Settings) and chapter 8 (Keybindings) to customize your setup.

2.5.2 For Power Users

After the getting started chapters, focus on chapters 11–17. The extensions chapter (11) is the most important—it unlocks everything from custom tools to permission gates to full custom UIs.

2.5.3 For Integrators

Chapters 18–20 cover the SDK, RPC mode, and JSON event stream mode. These are the programmatic interfaces for embedding Pi into other applications.

2.5.4 For Fork Maintainers

Chapter 23 (Development) covers the essentials: building from source, forking and rebranding, and the project structure.

2.6 Conventions

2.6.1 Code Examples

# Shell commands are shown with a $ prompt
$ pi --version

// TypeScript examples are complete and runnable
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // Extension code
}

// JSON configuration examples use standard formatting
{
  "key": "value"
}

2.6.2 Callouts

Tip

Tips highlight useful techniques and best practices.

Note

Notes provide additional context or clarification.

Warning

Warnings indicate potential pitfalls or security considerations.

2.6.3 Terminology

Term	Definition
Harness	An AI coding assistant that wraps an LLM with tool execution
Extension	TypeScript module that extends Pi’s behavior
Skill	Self-contained capability package for specific tasks
Provider	An LLM API endpoint (Anthropic, OpenAI, etc.)
Session	A conversation tree stored as a JSONL file
Context	The information sent to the model (system prompt + messages)
Compaction	Summarizing older messages to free context space
Pi Package	A distributable bundle of Pi resources

2.7 Acknowledgments

Pi is developed by Earendil Inc. and the open source community. The project is hosted at github.com/earendil-works/pi-mono.

This book is based on the official Pi documentation at pi.dev/docs, expanded with additional context, examples, and explanations.