6  Context files & sessions

NoteLearning objective

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.

NoteProject trust in non-interactive mode

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 name

Sessions can be exported for sharing or documentation:

pi --export session.html   # write an HTML transcript and exit

This 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.

TipExercises
  1. Add an AGENTS.md to a scratch project telling pi to always create a CHANGELOG.md entry after edits, then give it a small task and check whether it complied.
  2. Run two related tasks with -c (continue) so the second builds on the first, then --export the session and read the transcript.
  3. Use --fork to try two different approaches from the same starting point.
  1. Create AGENTS.md in the scratch project with a rule such as: “After any edit, add a dated entry to CHANGELOG.md describing the change.” Because pi walks up from the current directory and concatenates every AGENTS.md (and CLAUDE.md) it finds, this project file is picked up automatically. Give pi a small edit task and inspect whether CHANGELOG.md gained 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.
  2. Run the first task normally, then run the second with pi -c to continue the most recent session so its context carries over and the second task can build on the first. Finish with pi --export session.html to 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.
  3. 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.)