Pi Agents on Programmer.ie: Modern AI programming

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.

So this chapter is one turn of Pi, described exactly, with the places you can attach to it named.

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. This chapter gets you from nothing to a session with real work in it, and then spends most of its length on the part that is actually hard: giving the agent a task it can finish.

Install

On macOS or Linux, Pi has an installer:

curl -fsSL https://pi.dev/install.sh | sh

Or install from npm, which requires Node.js 22.19 or newer:

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. Nothing is wrong. The transcript simply filled up, and the oldest parts of it stopped being sent to the model.

Most people meet this as a mood: Pi got worse at the task. It is easier to reason about as arithmetic. Every model request costs a fixed slice of a fixed window, and Pi spends that slice in named places you can read, count, and change.

Sessions and Where They Live

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

You want to know what Pi actually did. Not what it summarised in the final message — what it did. That means opening the session file, and it turns out the file is plain JSONL you can read with any text editor, and every line is a node in a tree.

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

Pi shows every tool call and result while it works. That is a promise about visibility, not about restriction: it does not ask before every tool call, and the tools run with the operating-system permissions of the process.

What you can control is the set. settings.md defaults defaultTools to read, bash, edit, and write. Every run starts from that list unless you change it.

The eight

cli.md lists the built-in tools and their purpose:

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, and the honest answer is that the prompt is ambiguous about what “yes” buys you.

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 press up in your own terminal and ll works. Nothing is broken. Pi started a different shell.

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.

Pi does not help you here by asking. quickstart.md says Pi shows each file read, search, command, and edit it performs, and that it does not ask before every tool call. The specification of the task is entirely in your prompt.

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 only runs when you type it. The problem it solves has a sibling: work that should begin the moment Pi recognises the kind of task, without you naming the command first.

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 available skill by name and description, then loads its full instructions only when the task calls for them.

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; the files load only when the instructions say to read them.

The layout

review-guard/
├── SKILL.md
├── scripts/
│   ├── run-checks.sh
│   └── collect-diff.sh
├── references/
│   ├── checklist.md
│   └── severity-rubric.md
└── assets/
    └── finding-template.md

The four directory names are not enforced. skills.md shows exactly this shape in its own example — scripts/, references/, assets/ — and the convention is what makes a skill legible to the next person. Nothing stops you adding templates/ or data/; nothing encourages you either.

Your First Extension

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

The review guard can ask the model to run scripts/run-checks.sh. It cannot offer a new operation, block a dangerous command, or show a status line. Those need code, and quickstart.md is unambiguous: executable tools, commands, or event handlers means an extension.

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.

Only a tool_call handler can do that, because tool_call fires before the call runs. Getting that right requires knowing the lifecycle, because handlers run in registration order and a return value only matters for events declared to accept one.

How events dispatch

extensions.md states three rules:

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 executes, it returns structured data, it declares its risk, and it knows whether it is even visible 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, because nothing in its context said that tool existed. Then compaction happens, the summary drops the mention, and the next turn does it again.

This chapter is about the four surfaces that change what the model knows, and which one to reach for.

Extension State and Persistence

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

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

Nothing is broken. The count was never stored anywhere that survives a process. It lived in a module-level let that the factory closed over, and the factory runs again on every load. The fix is not “save it to disk somewhere sensible”. The fix is to understand that Pi already hands your extension a durable, branch-aware place to put state: the session file.

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, run pi --print on a CI machine, and the command silently does nothing because print mode has no UI at all.

That silence is not a bug. It is the rule you must design around before you write the command, not after. This chapter is about that rule, and about the three levels of interface Pi actually offers an extension.

MCP Servers

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

The guard extension intercepts write and edit. It works beautifully. Then someone on the team installs a Jira MCP server, and the model closes a ticket through mcp__jira__transition_issue without the guard ever being consulted.

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, a renderer for its own session entries, and a skill that tells the model when to use the tool. A colleague wants it. You send them a zip of your .pi folder, and it breaks: their guard package is a different copy of the same dependencies, their skill paths resolve against their own project, and the entry renderer never fires because the custom entry types do not match.

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 the real behaviour of compaction, not a bug in your prompt. The old messages were not deleted — they are all still in the session file — but they are no longer in the next request. What the model now has instead is a paragraph written by another model about what those messages said.

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, and choosing the wrong one costs you the work you actually wanted. /tree moves within the session. /fork starts a new session from an earlier message. /clone copies the current branch into a new session. The distinction is not cosmetic — it decides whether the abandoned attempt is still there when you come back.

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, and stopping it now would waste everything it has already learned about the database layer.

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 on the streaming events, fails on the saved session, and fails differently on the model request. The three surfaces use the same types — but not the same values, and 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 Files and Project Instructions

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

Compaction summarized away the schema you explained. The model asks you to restate it. You will not restate it.

The fix is not a better prompt. It is a file. Chapter 23’s last paragraph pointed at this: durable facts belong on disk, where they are read fresh on every request instead of travelling through a history that gets compressed.

This chapter is about that mechanism — which files, in which order, and under what conditions.

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 Pi

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 three things you can look at, and none of them is a stack trace: /debug, /bug, and /session.

That is not a gap in the tooling — it is a shape. Pi is a long-lived process with an event pipeline, an extension runtime that can be replaced mid-session, and a model that produces whatever it produces. Most failures here are not crashes. They are a lifecycle rule violated, a mode guard missing, or a message that is not where you expected it. This chapter is about reaching for the right artefact for each class, and about the small number of extension rules that explain most of what goes wrong.

The Terminal Interface

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

Shift+Enter submits instead of inserting a line. Your custom theme is unreadable in someone else’s terminal. A click handler works for you and not for the person who filed the bug.

None of these is a Pi bug, and each has a documented cause. The terminal interface is not one thing — it is a stack, and at every layer there is a contract that can be satisfied or not. Knowing which layer failed is most of the work.

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 event stream is the canonical reference for everything JSON and RPC mode share, and json.md is unusually honest about one thing — it is a wire format, deliberately reduced from the in-process one. If you build on it without reading that reduction, your reconstruction will drift. This chapter takes the stream apart: the framing, the vocabulary, and the one rule that governs reconstruction.

SDK Sessions

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

Your integration is written in TypeScript. It parses JSON, reconstructs deltas, and correlates nothing because there are no commands. All of that work exists only because of a process boundary you chose.

@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 — but you do not want to reimplement the SDK’s event types in another language, and you do not want the agent living inside your process where a bad tool call can take your server with it.

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.

Authority, Isolation, and What Makes an Agent Worth Building

Fri, 02 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. None of them is a sandbox, and all of them are real. And almost nothing in this book is an authority boundary except an operating-system boundary. Everything else is a procedure, a gate, or a convention — and a procedure can be designed well while remaining a procedure.