[Pi Series 3] Manage sessions and project context

In the previous post, we installed pi and started the first session. This post covers the management features you need when you use pi for real work over more than one short turn.

The difference between LLM coding tools often appears after the first run. Sessions get longer, project rules grow, and old conversation can start interfering with current work. That is when context management matters.

---

What this post covers

• Understand how pi saves sessions
• Continue the most recent session
• Select a previous session
• Distinguish /tree, /fork, and /compact
• Pass project rules through AGENTS.md and CLAUDE.md
• Keep long sessions from becoming heavy

---

Sessions are saved automatically

pi saves sessions automatically. By default, session files are stored under ~/.pi/agent/sessions/, organized by working directory.

To continue the most recent session, use:

pi -c

To browse and choose a saved session, use:

pi -r

If you want a one-off session without saving history, disable session saving.

pi --no-session

For quick questions or small summaries, --no-session can be cleaner. If every conversation is saved, the session list can become noisy.

---

What happens when a session gets too long

Long sessions are convenient because they carry previous context. But when they grow too long, they can become heavy.

Common symptoms are:

• Old files get mixed into the current task.
• The model treats old decisions as if they are still valid.
• Small edits become slower.
• The assistant repeats summaries or explanations.
• Tool calls unrelated to the current task increase.

This is not unique to pi. Most LLM tools show similar behavior when context grows too large. pi addresses this with explicit session tools such as /tree, /fork, and /compact.

---

/tree: go back to an earlier point

/tree shows the conversation tree and lets you return to an earlier point to continue in a different direction.

/tree

For example, suppose you tried a refactor and did not like the direction. Instead of throwing away the whole session, you can return to the user message before the refactor and try a different approach.

This is useful for experimental work.

• Try approach A.
• Return to an earlier point.
• Try approach B.
• Compare the results.

The session becomes a branching work record, not just a linear log.

---

/fork: create a new session from a point

/fork creates a new session from a selected previous user message.

/fork

If /tree feels like branching inside the current session, /fork feels like copying the relevant history into a new session file.

It is useful when:

• the current session has become too long,
• one task splits into another task,
• you want to retry the same requirement with a different model or strategy,
• you want to keep the old conversation but continue in a lighter new file.

Instead of pushing every task into one long session, split it at natural boundaries.

---

/compact: compress a long conversation

/compact summarizes a long conversation and reduces context.

/compact

You can also provide custom instructions.

/compact Keep only implementation decisions, remaining TODOs, and validation commands.

Compaction is not magic. If the summary drops important details, later turns can lose context. Before compacting important work, it helps to make the following explicit:

• final decisions,
• modified files,
• remaining TODOs,
• validation commands that passed or failed,
• approaches that were tried and abandoned.

With a clear summary target, /compact is much safer.

---

Pass project rules through AGENTS.md

pi reads AGENTS.md or CLAUDE.md at startup and uses them as project instructions. According to the official docs, it loads global files, the current working directory, and parent directories. The discovered instruction files are concatenated and sent to the model.

Typical locations are:

• global rules: ~/.pi/agent/AGENTS.md
• project and parent directories: AGENTS.md or CLAUDE.md

For a blog project, AGENTS.md might include rules such as:

# Blog writing rules

- Before writing a new blog post, read docs/content/blog-writing-guide.md.
- Include workflowStatus, readerReview, expertReview, humanReview, and publishReady in frontmatter.
- Do not use a body # H1; start headings from ##.
- After substantial edits, run npm run check.

This prevents you from repeating the same instructions in every prompt. Run pi inside the project, and the rules are loaded automatically.

---

When you want to disable context files

Project rules are not always helpful. Sometimes you only want to inspect one file, or global instructions make a small task heavier than necessary.

In that case, disable context file loading.

pi --no-context-files

This is useful when:

• the question is unrelated to project rules,
• you want to review one file independently,
• your global AGENTS.md contains too many instructions,
• you want the model's direct code interpretation without extra workflow rules.

More context is not always better. Keeping only the necessary rules is part of using pi well.

---

My basic operating rules

If I keep using pi regularly, I would operate it with these rules.

1. Start small tasks in new sessions.
   Do not pile everything into one long session.

2. Put project rules in AGENTS.md.
   Repeated rules belong in files, not repeated prompts.

3. Use /fork for major direction changes.
   Do not mix unrelated work in one session.

4. Give /compact a clear summary target.
   “Keep decisions, TODOs, and validation results” is safer than “summarize everything.”

5. Do not enable unnecessary extensions by default.
   If the goal is lightness, attach extensions one by one when they are needed.

---

Summary

Feature	Purpose
pi -c	Continue the most recent session
pi -r	Choose a saved session
pi --no-session	Run without saving a session
/tree	Return to an earlier point and branch inside the session
/fork	Create a new session from a selected point
/compact	Compress long conversation context
AGENTS.md	Pass project rules automatically
--no-context-files	Disable instruction file loading

pi's point is not to enable every feature by default. It is to keep only the context you need so you can iterate quickly.