The tiny prompt, and why

You now have a way to print the literal system prompt behind any given turn. Go do it on stash and the first thing that’ll strike you is how short it is - the default template is compact, although its exact size changes with the active tools, skills, context files, and Pi version. You’ve likely used agents whose standing instructions run into the thousands of tokens before you’ve typed a single word to them. Pi’s isn’t thin because someone forgot to write the rest of it. It’s thin on purpose, and the purpose is worth understanding before you start editing it yourself in a later chapter.

What’s actually in there

The prompt isn’t a static block of text sitting in a file somewhere - it’s assembled fresh, every turn, by a small template builder. In the order it gets built:

1. One identity line - something to the effect of “You are an expert coding assistant operating inside pi, a coding agent harness.” No persona essay, no list of virtues.
2. The available tools - whichever ones are actually active for this session. If a tool isn’t enabled, it simply doesn’t appear; there’s no boilerplate describing capabilities you don’t have.
3. Guidelines, conditionally included based on what’s active. This is the part worth sitting with, because it’s not one fixed paragraph - it changes shape depending on your tool set. With read and edit both active, it adds a line like “use read to examine files before editing.” If bash is your only way to explore the filesystem, it tells the model to lean on bash for ls/rg/find-style work; if dedicated grep/find/ls tools are present instead, the guidance flips to prefer those over bash for exploration. write gets its own note steering it toward new files and full rewrites, reinforcing what you already saw edit enforce structurally in the last module.
4. A pointer to Pi’s own docs - file paths the model can read itself if it needs more detail, rather than that detail being inlined into every single turn whether it’s relevant or not.
5. Project context, injected inside <project_context> tags - this is where an AGENTS.md file’s contents show up, which matters enough to get its own module next chapter.
6. Skills, as metadata only - name, description, and file path for each one, never the full skill body. The model reads a skill’s actual instructions only when a task matches it. This is the same lazy-loading instinct as read’s truncation from two lessons ago, applied to prompt construction itself: don’t spend tokens on something until it’s actually needed.
7. Runtime metadata - today’s date and the current working directory, so the model isn’t reasoning from a training cutoff when either one matters.

That’s the whole shape. No fifty-line list of edge-case reminders, no repeated safety disclaimers, no verbose description of a tool that isn’t even turned on.

Context files layer in automatically, and you can watch it happen

Before any of that project context lands in <project_context> tags, Pi walks the directory tree collecting AGENTS.md-style files - global first (~/.pi/agent/AGENTS.md), then every parent directory on the way down to your current one. All matching files are concatenated; closer files appear later in the assembled context, but Pi does not apply a formal “closest wins” override rule. You can disable the whole mechanism with --no-context-files if you ever need Pi reasoning with zero project context at all - useful for isolating whether a weird behavior is coming from your rules file or from the model itself.

AGENTS.md is this course’s APPEND_SYSTEM.md moment waiting to happen, not something to fully unpack here - you’ll write one for stash next chapter. What matters now is just this: it’s not magic, it’s a walk up the filesystem, and you already know how to go check exactly what landed in the prompt because of it.

The prompt is meant to be replaced, not just read

Every piece of this is overridable, and Pi gives you several levels of override rather than one blunt switch:

• .pi/SYSTEM.md (project) or ~/.pi/agent/SYSTEM.md (global) replaces the default template wholesale - context files and appended sections still get layered on top, but the base identity/tools/guidelines text is gone, swapped for whatever you write instead.
• APPEND_SYSTEM.md at either scope adds to the default without replacing it - the gentler option when you just want to bolt on a house rule or two.
• CLI flags - --system-prompt <text> and --append-system-prompt <text> do the same two things for a single invocation, no file required.
• A before_agent_start extension hook can rewrite the prompt for that turn only - the base template resets right after, and if more than one extension hooks this event, each one sees the previous extension’s already-modified version before adding its own. You’ll build one of these in the extensions chapter.

And when a custom tool registers its own promptSnippet and promptGuidelines, those get spliced into the assembled prompt the same way the built-in tools’ guidance does - and disappear automatically the moment that tool is disabled. The whole thing is rebuilt from scratch every time, never left stale from a config that changed three sessions ago.

Why bet on “thin”

The argument behind all of this, in its author’s own words: frontier models have been “RL-trained up the wazoo” and already understand what a coding agent is and how to drive read/write/edit/bash without three paragraphs of hand-holding per tool. A bloated system prompt, on that view, is “unnecessary overhead” - tokens spent every single turn restating things the model already knows, that could instead go toward your actual project context, or just not be spent at all. The guiding line for what makes it into the template is blunt: if it isn’t needed, it doesn’t get built.

That’s a bet, not a law of nature - it assumes you’re pointing Pi at a genuinely capable model, and it trades away some of the guardrail-by-verbose-instruction style you’ll find in more opinionated agents. But it’s a bet you can now personally audit rather than take on faith, because two lessons ago you learned exactly how to go print the real thing and see for yourself whether it’s holding up on stash.

You can now see everything: the exact tools, the loop with no hidden ceiling, the live context, and the tiny prompt underneath all of it. Seeing isn’t the same as controlling, though - right now stash’s conventions live in your head, and you’re re-explaining them to Pi every session because nothing durable has been written down yet. Next: turn what you know about stash into context Pi carries automatically.