Pi Agents on AIBussin — AI applications, systems and books

The Loop You Are Writing For

Thu, 01 Oct 2026 09:00:00 +0100

You are going to write an extension. Before that, you need to know what it is extending.

This is the step most people skip. They install Pi, run a task, get something nearly right, and start writing code against a mental model built from observation. The model is usually close enough to work and wrong in a few named places, and those places are where every interesting bug lives.

Why “wrong in a few places” is worse than “wrong everywhere” is worth one sentence of its own, because it explains the shape of the rest of the book. A model that is wrong everywhere fails loudly: you stop and read the documentation. A model that is nearly right fails as a symptom. The model ignores your instructions. Your tool never appears. Your injected content vanishes after a compaction. Your handler fires at the wrong moment. Each of those observations is compatible with several different causes — some in your code, some in Pi’s, some in the way you assembled the request — and the observation alone cannot tell them apart. What tells them apart is knowing the exact mechanism the symptom passed through. That mechanism is the loop.

Install, First Session, First Task

Thu, 01 Oct 2026 09:00:00 +0100

Before you can write for an agent, you have to run one — and running one is really two activities that are easy to blur together. The first is setup: install the tool, point it at a folder, prove it can authenticate. The second is use: give it a task and judge the result. They fail differently. A broken install fails loudly and immediately; a badly specified task fails quietly, as output that looks plausible and is wrong. This chapter does the setup quickly, because setup is short and verifiable, then spends most of its length on the part that is actually hard: giving the agent a first task it can finish.

Models and Thinking Level

Thu, 01 Oct 2026 09:00:00 +0100

Something is not working. The agent is not using your tool. It is ignoring an instruction. It stops halfway. Before you go looking in your extension, check which model is running and what thinking level it is set to.

This is not a joke about blaming the model. It is a description of how the system is layered: model choice and thinking level sit underneath every mechanism in this book, and they change behaviour in ways that look exactly like bugs in the layer above.

The Context Window Is a Budget

Fri, 02 Oct 2026 09:00:00 +0100

You are halfway through a refactor. Pi has read forty files, run the test suite twice, and rewritten the same module three times because each attempt turned out to conflict with the last. The session is still on disk, but the request has grown too large. If Pi compacts it, older messages are represented by a summary rather than sent in full.

Most people meet this as a mood: Pi got worse at the task. It is easier to reason about as a budget. Each request consumes a varying number of tokens within the model’s context window, across components you can inspect and, in several cases, change.

Sessions and Where They Live

Fri, 02 Oct 2026 09:00:00 +0100

When you want to reconstruct what Pi recorded, start with its session file. It is plain JSONL that you can read with a text editor: the first line is a header, and subsequent entries describe messages, settings changes and other session events. Entries with IDs and parent IDs form a tree, but not every recorded entry is a message sent to the model.

That tree is the reason Pi can offer /tree, /fork and /clone, and it carries the book’s most-repeated distinction: a session is a tree; the model’s context is one path through it.

The Built-In Tools

Fri, 02 Oct 2026 09:00:00 +0100

In an interactive session, Pi displays tool activity as it works. Visibility is not restriction: Pi does not require approval before every tool call, and built-in tools ordinarily run with the operating-system permissions of the Pi process. Headless modes expose activity differently, and showing a call does not prevent its effects.

One control is the set of tools made available to the model. settings.md gives defaultTools a default of read, bash, edit, and write. Settings, command-line options and loaded integrations can change the effective set; none of these settings is an operating-system sandbox.

Settings and Where Configuration Comes From

Fri, 02 Oct 2026 09:00:00 +0100

You edit settings.json, run /reload, and the setting does not take effect. Or it takes effect in a way you did not predict. Both come from the same cause: you were reasoning about one file when Pi merges several.

configuration.md gives the shape in one sentence. Pi supports user-level and project configuration. User-level lives in the agent directory, defaulting to ~/.pi/agent. Project configuration lives in .pi under the working directory and loads after project trust is granted — with one exception, sessionDir, which Pi reads before resolving trust so it can locate sessions.

The Project .pi Directory and Trust

Fri, 02 Oct 2026 09:00:00 +0100

You clone a repository. It contains .pi/extensions/migrate-schema.ts, and migrate-schema.ts calls execSync with a string built from a prompt. Pi asks whether you trust the folder. You are being asked a real question: does “yes” merely acknowledge the repository, or does it allow that extension to load and run with your process permissions?

security.md answers it precisely, and the answer has a wrinkle worth knowing before you answer.

What triggers the prompt

Pi requires a project-trust decision when it finds any of these from the current working directory:

Shells, Processes, and Environment Variables

Fri, 02 Oct 2026 09:00:00 +0100

You ask Pi to run ll, and it reports ll: command not found. You try the same command in your interactive terminal, and it works. Pi ran the command in a separate non-interactive shell, where your alias may not be defined or expanded.

shell-aliases.md states the cause in the first line: Pi starts a separate non-interactive shell process for each Bash command. Non-interactive Bash does not expand aliases by default and usually does not load the same startup files as an interactive terminal.

Writing a Task Pi Can Finish

Fri, 02 Oct 2026 09:00:00 +0100

The most common failure is not a bad model. It is a task that never said what “done” meant. You wrote “clean up the auth module”, Pi spent forty turns, and produced something you now have to review as carefully as writing it yourself.

Do not rely on Pi to ask for approval before acting. quickstart.md says Pi shows each file read, search, command, and edit it performs, and that it does not ask before every tool call. State the task, its scope and its acceptance check explicitly rather than assuming the agent will ask for missing constraints.

Four Ways to Change Pi

Fri, 02 Oct 2026 09:00:00 +0100

You keep typing the same three lines before every code review. Then you notice the same file appearing in three repositories. Then someone asks for a /review-tests command and you write forty lines of TypeScript to expand a string.

Every one of those three moves was available. Pi’s documentation gives a one-line rule for choosing between them — quickstart.md says to start with the least powerful mechanism that meets your need — and then leaves the reader to guess what “least powerful” means at three in the afternoon.

Prompt Templates

Fri, 02 Oct 2026 09:00:00 +0100

The /review you typed in chapter 11 was real — it lives at .pi/prompts/review.md, four lines of frontmatter and three of body. This chapter is about everything that file can do and, just as importantly, what it cannot.

The one-line summary from prompt-templates.md: templates turn Markdown files into reusable / commands, and you want one when you would otherwise retype the same prompt without adding executable behaviour or a larger set of supporting instructions.

Skills

Fri, 02 Oct 2026 09:00:00 +0100

/review from chapter 12 expands when you invoke it. The problem it solves has a sibling: work that the model should recognise as relevant to a task without you naming a command first. Skill selection is model-driven, not a guaranteed trigger.

That is a skill, and the entire mechanism turns on one field you are tempted to rush.

What a skill actually is

skills.md opens with the definition: skills give Pi specialized instructions and supporting files for a particular kind of work. Pi advertises each eligible skill by name and description. The model may then read its SKILL.md when it considers the skill relevant; Pi does not automatically execute the skill on a matching task.

Run This Book's Examples

Mon, 01 Jan 0001 00:00:00 +0000

Every typescript block in this book carries a marker naming the file it was taken from, and a script fails the build if a chapter and its source have drifted apart. That is the mechanism behind this book’s method: the code you read is code that ran, at a release the text was checked against.

This page is how you get hold of it.

Get the code

The examples live in this book’s repository, in the examples/ directory:

Skills That Carry Files

Fri, 02 Oct 2026 09:00:00 +0100

The review guard’s checklist is forty items. Three screens of Markdown in SKILL.md would load all forty every time the skill fires, including for the small reviews where only three apply.

skills.md offers a better arrangement: skills can bundle scripts, references, and assets alongside their instructions. The body stays short and names the files; those files are not included automatically in the model context. The agent must explicitly read or execute them when needed.

Your First Extension

Fri, 02 Oct 2026 09:00:00 +0100

The review guard can instruct the model to run scripts/run-checks.sh, but a skill cannot itself register a new model-callable operation, intercept tool execution, or register a status display. Those integrations need an extension; the script a skill asks the model to run is still executable code, but it is not an extension hook.

This chapter builds the smallest extension that does something a skill cannot.

What an extension is

extensions.md: extensions are TypeScript modules loaded into the Pi process, and their factory functions register tools, commands, shortcuts, providers, event handlers, renderers, and terminal UI.

Events and the Extension Lifecycle

Fri, 02 Oct 2026 09:00:00 +0100

The review guard can suggest running the checks. It cannot stop a git push --force that the model decides to run while fixing a conflict.

A tool_call handler can block a matching invocation of a tool before its body runs. That makes it a useful extension-level guard, not an unconditional prohibition: commands can reach the same effect through other tools or paths the handler does not inspect. Getting this right requires knowing the lifecycle, because handlers run in registration order and a return value only matters for events declared to accept one.

Tools in Depth

Fri, 02 Oct 2026 09:00:00 +0100

Chapter 15’s review-scope tool told the model which command to run. That is a tool shaped like a suggestion. This chapter turns it into a tool shaped like a tool: It can execute work, return structured data, publish risk hints, and control how it is exposed to the model.

Five exposures

exposure controls how the model reaches a tool. “Callable” means callable from other tools through ctx.executeTool() — which is what codemode scripts do.

Changing What Pi Knows

Fri, 02 Oct 2026 09:00:00 +0100

The guard works. Pi asks before a force push, run_checks runs the project’s own tests, and the failing-test tool answers with structured data.

What still goes wrong is quieter. Pi reviews a diff using npm test instead of run_checks, despite the tool being declared to the model. The tool description makes it available; it does not guarantee selection. A reminder placed only in conversation history can also disappear from the request after compaction, leaving the model without that guidance on a later turn.

Extension State and Persistence

Fri, 02 Oct 2026 09:00:00 +0100

Your guard extension blocks some writes to protected paths. It works on Monday. On Tuesday you run /reload, and the block count in /guard-blocks reads zero. On Wednesday you resume the session from disk and it reads zero again.

Nothing is broken. The count was never persisted. It lived in a let captured by the extension factory, and a reload or a new process creates a new instance. The fix is not necessarily to invent a separate storage file: Pi already provides a durable, branch-aware place for state in persistent sessions. An ephemeral session, however, does not survive process exit.

Slash Commands and Custom UI

Fri, 02 Oct 2026 09:00:00 +0100

Your guard extension logs blocked writes. The reader wants to see them. The obvious move is a /guard command that opens a picker. You write it, then invoke the command in print mode on a CI machine. There is no UI to show the picker, so a command written only for interactive mode cannot complete that interaction.

The absence of a UI is expected, but silent failure is not a useful design. Handle modes explicitly before opening a dialog. This chapter covers the available UI surfaces and the mode rules that constrain them.

MCP Servers

Fri, 02 Oct 2026 09:00:00 +0100

The guard extension intercepts write and edit. It blocks those calls as intended. Then someone on the team installs a Jira MCP server, and the model closes a ticket through mcp__jira__transition_issue without that guard blocking the call. The MCP call has a different tool name, so a guard limited to write and edit does not match it.

It was not consulted because the guard never claimed that path was its responsibility — and, more importantly, because whether it is covered turns out to be a real question with a documented answer. This chapter is about registering MCP servers, controlling how their tools reach the model, and the one thing a permission extension can and cannot learn from them.

Packages: Shipping an Agent

Fri, 02 Oct 2026 09:00:00 +0100

You have an extension. It registers a tool, a /guard command, and a renderer for its own session entries; a skill tells the model when to use the tool. A colleague wants to install the same setup. Sending a copy of .pi/ may leave them with project-specific paths, missing resources, or unmanaged dependencies. A package gives those resources a single distribution unit, but does not by itself guarantee compatibility or make untrusted code safe.

Compaction

Fri, 02 Oct 2026 09:00:00 +0100

Two hours into a refactor, the footer says you are at 87% context. Nothing is wrong. Then it says the agent compacted, and the model asks you to re-explain the schema it was told about an hour ago.

That re-asking is one possible consequence of compaction, not necessarily a defect in your prompt. The original entries remain in the session file, but the older portion selected for compaction no longer reaches the next model request as individual messages. Pi sends a generated summary in its place and keeps the more recent messages. The summary may be produced by the current model, and it can omit details that the earlier conversation contained.

Branching and Forking

Fri, 02 Oct 2026 09:00:00 +0100

The agent picked a schema you did not want, edited eleven files, and is confidently three steps into an approach you have already decided against. You press Escape. Now what?

There are three answers for the conversation: /tree moves within the current session, /fork starts a new session from an earlier user message, and /clone copies the active branch into a new session. The distinction decides where the conversation history lives and which part of it the model sees next. None of these commands undoes the eleven edits already made on disk. If you also want the repository back in its earlier state, inspect and restore those working-tree changes separately, using version control or a backup.

Steering, Queuing, and Changing Direction

Fri, 02 Oct 2026 09:00:00 +0100

The agent is eleven tool calls into migrating your schema. You can see it is going to be wrong in about three more steps. Aborting would stop the current run, but it would not erase the conversation or undo tool calls that have already completed. You want to preserve the useful investigation while correcting what happens next.

You type. You press Enter. And the message waits — because Pi was not going to interrupt mid-tool-call, and the moment it delivers your instruction is a specific, documented point in the loop.

Message Types

Fri, 02 Oct 2026 09:00:00 +0100

You write an extension that renders tool results. It works with streaming events, fails when replaying a saved session, and fails differently when inspecting a provider request. The difficulty is that a streaming message, a persisted session entry, a projected conversation, and a provider request are not interchangeable representations. One field in particular is not what its name suggests.

This chapter is the reference for the shapes themselves.

One union, four surfaces

“Pi uses AgentMessage values in SDK state, lifecycle events, RPC responses, and persisted session message entries.”

The Session File Format

Fri, 02 Oct 2026 09:00:00 +0100

You open a session file to find out what the agent actually saw. There are four hundred lines. Somewhere in them is the system prompt, most of a conversation that has been summarized away, a branch you abandoned last week, and a custom entry from an extension storing its own counter.

Which of those reached the model is not obvious from the file. This chapter is about the file and the rule that decides.

Context Admission Is Application Policy

Fri, 02 Oct 2026 09:00:00 +0100

Compaction summarized away the schema you explained, and the model asks you to restate it. You will not restate it. The fix is a file, because loaded instructions travel with every request while a conversation gets compressed. Chapter 23 ended there.

But “put it in a file” is the start of the question, not the end. A file on disk can be ignored, replaced, filtered out, or supplied by someone other than you. This chapter is about the four separate facts hiding in the sentence the model read my AGENTS.md, and about who decides each one.

Failures, Retries, and Recovery

Fri, 02 Oct 2026 09:00:00 +0100

The provider returns 529 overloaded. Pi waits two seconds and tries again. Twice more. Then it stops and tells you the model is unavailable.

That is correct — and it is the least interesting failure Pi handles. There are three responses to a failed request, they are not interchangeable, and picking the wrong one is how an agent ends up retrying a request that could never succeed.

Three responses, three meanings

Retry. The failure was transient. The request was fine; the server was not. Repeat it.

Debugging by Layer

Fri, 02 Oct 2026 09:00:00 +0100

The extension worked yesterday. Today the same command does nothing, the transcript looks fine, and there is no error anywhere. You have no stack trace. You have a model that did something, a process that recorded it, and several places it could have gone wrong.

Debugging an agent badly means looking everywhere at once. Debugging it well starts from the architecture you now have. The layers introduced in chapter 1, refined by the tools, extensions, sessions and interfaces covered since then, give you a list of suspects. Controlled substitutions can narrow that list, provided you track what each substitution changes.

The Interface Is Not the Agent

Fri, 02 Oct 2026 09:00:00 +0100

You have spent thirty chapters mostly in a terminal, and it is easy to come away thinking the terminal is Pi. It is not. The terminal is one way to drive the agent, alongside print mode, JSON, RPC and the SDK. Switching interfaces preserves the underlying agent architecture, but can change how work is submitted, what a person can approve, and how results and failures are reported.

That is a claim about architecture, and this part of the book ends by testing it. Chapters 32 to 35 take the interfaces one at a time. This chapter states what they share, shows that the sharing is real, and names the one place where an interface does leak into what an extension is allowed to assume.

Headless Pi

Fri, 02 Oct 2026 09:00:00 +0100

A CI job needs to run a review over a diff. A pre-commit hook needs to summarise what just changed. Neither has a person, and neither wants a terminal.

pi already handles this, and the handling is almost entirely documented in one place: cli-integration.md. But the interesting question is not “how do I print the answer” — it is what is different when the agent has no person attached, because most of what you built in the previous twenty-nine chapters assumed one.

The JSON Event Stream

Fri, 02 Oct 2026 09:00:00 +0100

You piped pi --mode json into a log and now you have four thousand lines and a question: which ones are the answer?

The JSON event stream is the reference for the agent-session events that JSON and RPC mode share. It is a wire format, with deliberate differences from in-process SDK events; RPC also has command responses and protocol-specific events that JSON mode does not. If you build on the stream without understanding those differences, your reconstruction can drift. This chapter takes the JSON stream apart: the framing, the event vocabulary, and the rule that governs message reconstruction.

SDK Sessions

Fri, 02 Oct 2026 09:00:00 +0100

Your integration is written in TypeScript. It parses JSONL records and reconstructs streamed messages. If you use RPC, it also correlates command responses with requests. Much of that protocol handling exists because you chose to communicate with Pi across a subprocess boundary.

@earendil-works/pi-coding-agent embeds Pi directly, and sdk.md opens with the recommendation in its first two lines: use the SDK for in-process TypeScript integration; for a language-independent or isolated subprocess, use CLI integration instead. This chapter is about what the boundary buys you back and what it charges.

RPC

Fri, 02 Oct 2026 09:00:00 +0100

You want to drive Pi from an editor plugin, from a Python service, or from an IDE — without reimplementing the TypeScript SDK in another language or running Pi inside your host process. A subprocess gives the host a separate failure and lifecycle boundary. It does not sandbox the agent: Pi and its tools can still reach whatever files, credentials, and services the child process is permitted to access.

RPC is the fourth interface in this progression and the one that keeps the isolation. This chapter is about the protocol: what flows in each direction, how you correlate, and the subprotocol that almost nobody realises exists.

Model Access Without the Coding Agent

Sun, 04 Oct 2026 09:00:00 +0100

Everything so far has run inside a coding agent. You have been using a tool that reads files, runs commands and keeps a session, and you have been attaching to it. That is the right place to start, because Pi’s host is where most people meet Pi.

It is the wrong place to stop, because most of what an application needs from a model is not an agent. It is one question and one answer: is this claim supported by this evidence? One input, one typed result, nothing to run, nothing to remember.

The Agent Core on Its Own

Sun, 04 Oct 2026 09:00:00 +0100

The claim checker from chapter 36 has a limit. Given the evidence you handed it, it can produce a schema-valid assessment, including insufficient when the evidence is inadequate. It cannot independently fetch more evidence in that single call, and the model may still judge the evidence incorrectly.

Looking for more is a loop: the model asks for something, you run it, you give the result back, and the model decides again. You have seen that loop for thirty-six chapters, from the outside. This chapter runs it from the inside, in about forty lines, using the same class the coding agent is built on.

A Stochastic Step Is a Typed Function

Sun, 04 Oct 2026 09:00:00 +0100

An unconstrained agent may finish with prose, and prose is a fragile interface between software components.

You can pass a paragraph to another function, but branching on its meaning requires interpretation or parsing whose behavior you must define and test. An ordinary agent can stop after deciding it is finished, without producing the structure a downstream function expects. This chapter puts a validated value at that boundary instead.

Chapter 36 fixed this for a single call. This chapter fixes it for a loop. The result is the most reusable idea in the book, and it fits in one function.

Seams, Hooks, and Irreversible Decisions

Sun, 04 Oct 2026 09:00:00 +0100

Chapter 1 ended on a sentence that has been quietly organising the book since:

An extension point is a real architectural seam only for decisions it can intercept before those decisions become irreversible.

It was stated there as a finding about forks of the coding agent, and it was argued from three cases. This chapter tests it on something you can run. The agent core has nine function-shaped options that run around a request or a tool call, and for each one the useful question is not what does it give me but what can I still decide by the time it fires.

Composing Agent Operations

Sun, 04 Oct 2026 09:00:00 +0100

The tempting next move is to make every part of the pipeline an agent. One agent retrieves, another assesses, another summarises, and they talk. That may be useful when the tasks genuinely require independent decisions or work, but it introduces more model calls, coordination and failure paths than this claim checker needs.

This chapter is the argument against doing that by default, made with a pipeline you can run. The rule it demonstrates:

Testing Stochastic Software

Sun, 04 Oct 2026 09:00:00 +0100

The tests in chapters 36 to 40 all passed. They tell you less than you might hope, and it is worth being exact about what.

They show how your code handles the model responses you scripted. They cannot establish how often a real model will produce those responses. A scripted provider can simulate refusals, rambling answers and wrong tool calls, but only when you write those cases into the script. If you stop at green tests, you have not yet measured the stochastic part.

Authority, Isolation, and What Makes an Agent Worth Building

Mon, 05 Oct 2026 09:00:00 +0100

Everything so far has been a mechanism. Tools, extensions, events, sessions, modes, protocols. This chapter is about the one question that turns a set of mechanisms into something you would let near a production repository, and about what you are then able to claim.

Two claims carry the chapter. Capability is not authority: Pi can do almost anything the account that started it can do, and several documented mechanisms bear on whether it should do a particular thing. Those mechanisms matter, but none by itself is a sandbox. And a prohibition on what the agent can reach needs enforcement outside the agent’s ability to override it. That may be an operating-system restriction, a credential with limited scope, or a remote service that independently denies an operation. A prompt, an in-process gate and a tool allowlist can still provide useful controls, but they must not be mistaken for containment of the whole process.

Appendix A — References and Further Reading

Sun, 04 Oct 2026 09:00:00 +0100

This book makes three kinds of statement and keeps them apart: what Pi’s documentation and exported types say (documented), what was run and recorded (observed), and what this book recommends (proposed). A reader who wants to check a claim needs to know which pile it came from, so this page says where the material lives.

External papers and projects do not define Pi’s behaviour. For Pi-specific claims, use the pinned documentation and declarations, inspect implementation where needed, and distinguish those sources from the book’s own recorded tests. The references below provide context and comparisons, not a substitute for that evidence.

Appendix B — The Terminal Interface, in Detail

Sun, 04 Oct 2026 09:00:00 +0100

This is reference material for the pinned Pi 1.0.4 release. Chapter 31 explains why the terminal is an interface to the agent and not part of it. This appendix is what you need if you are building a terminal component, tuning a keybinding or debugging a terminal that will not report a key. Terminal and multiplexer versions matter as well as Pi’s version; verify a reported workaround against the actual terminal path. If you are not doing one of those tasks, you can skip this appendix without losing anything in the main line.

Appendix C — Pi Patch Desk: The Capstone

Wed, 14 Oct 2026 09:00:00 +0100

You have finished the book. Now give its mechanisms one job to do together.

Pi Patch Desk takes a small parser bug through reproduction, investigation, editing, verification and review. At the end you receive a proposed patch and a dossier explaining what happened. You can inspect the change and the recorded checks without trusting the agent’s final prose.

This appendix is a supplement added after the book’s initial publication. The forty-two numbered chapters and Appendices A and B keep their order and paths. The implementation lives in the public pi-agents repository, alongside the book’s executable examples. The Pi Patch Desk solution page is its practical entry point; here you will run the example and connect each decision to the material you have read.