6 Context files & sessions
You can steer pi’s behaviour with AGENTS.md and SYSTEM.md, and you can save, resume, branch, and export sessions.
6.1 Telling pi how to work: AGENTS.md
Instead of repeating instructions every run, you put project instructions in an AGENTS.md file. pi discovers these by starting at ~/.pi/agent/ (global) and then walking up from the current directory, concatenating every match it finds. For compatibility it also reads CLAUDE.md.
A small project AGENTS.md:
# Project rules for pi
- This is a Python project managed with `uv`. Use `uv run` to run code.
- Always run `ruff check .` after editing Python files.
- Never touch files under `data/` — they are large and read-only.Because matches are concatenated up the tree, you can keep broad rules in a global ~/.pi/agent/AGENTS.md and project-specific rules in each repo.
6.2 Replacing the system prompt: SYSTEM.md
AGENTS.md adds guidance; SYSTEM.md replaces pi’s built-in system prompt entirely. Place it at ~/.pi/agent/SYSTEM.md (global) or .pi/SYSTEM.md (project). To append to the default prompt instead of replacing it, use APPEND_SYSTEM.md. Most beginners should leave the system prompt alone and use AGENTS.md.
pi treats project-local files (.pi/…, project AGENTS.md) as something to trust before loading. Non-interactive modes (-p, --mode json, --mode rpc) do not show a trust prompt; they follow your global defaultProjectTrust setting. Pass --approve/-a to trust project-local files for one run, or --no-approve/-na to ignore them.
6.3 Sessions: save, continue, resume, branch
pi automatically saves each session as a tree (you can branch and go back). The flags you will use most:
pi -c # continue the most recent session
pi -r # pick a session to resume
pi --fork <id> # branch a new session from an existing one
pi --no-session # ephemeral: don't save this run
pi --name "refactor" # give a session a readable nameSessions can be exported for sharing or documentation:
pi --export session.html # write an HTML transcript and exitThis pairs well with the agent-facing exercises in this book: run a task, then --export the transcript as a record of exactly what the model did.
6.4 Extending pi (briefly)
pi keeps the core tiny on purpose; everything else is an extension (a TypeScript module) or a skill (a reusable prompt/tool bundle), discovered from ~/.pi/agent/ or the project’s .pi/. You do not need any of this to use a local model, but it is where features like permission gates, the Model Context Protocol (MCP), or sub-agents live if you want them later. Manage them with pi install, pi list, and pi remove.
- Add an
AGENTS.mdto a scratch project telling pi to always create aCHANGELOG.mdentry after edits, then give it a small task and check whether it complied. - Run two related tasks with
-c(continue) so the second builds on the first, then--exportthe session and read the transcript. - Use
--forkto try two different approaches from the same starting point.
- Create
AGENTS.mdin the scratch project with a rule such as: “After any edit, add a dated entry toCHANGELOG.mddescribing the change.” Because pi walks up from the current directory and concatenates everyAGENTS.md(andCLAUDE.md) it finds, this project file is picked up automatically. Give pi a small edit task and inspect whetherCHANGELOG.mdgained a matching entry. Compliance is guidance, not a hard guarantee, so the point of the check is to see how reliably the model follows the standing instruction. - Run the first task normally, then run the second with
pi -cto continue the most recent session so its context carries over and the second task can build on the first. Finish withpi --export session.htmlto write an HTML (Hypertext Markup Language) transcript, then open it to read exactly what the model did across both turns. The transcript doubles as a shareable record of the run. - Start from a saved session and run
pi --fork <id>to branch a new session from that point, then pursue approach A. Fork the same<id>again for approach B. Both branches share the identical starting context but evolve independently, so you can compare the two strategies without one polluting the other. (You can also fork the current session interactively; forking from an explicit id is the scriptable form.)