Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 45 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,42 @@
# pi-context-kit

Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi). It keeps the context of long Pi sessions small: pi-context-kit removes old file copies and old tool outputs from the model's context, and prepares the summary before Pi needs it. The session keeps the original text, and the model can read it again with `recall`.
[![npm version](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit) [![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml) [![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org) [![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)

**Long Pi sessions that stay sharp.**

Pi compaction and context management for the [Pi coding agent](https://github.com/earendil-works/pi). pi-context-kit clears stale file reads and old tool outputs out of the context window, writes the handoff summary in the background before Pi needs it, and keeps the original text of the current branch one `recall` search away.

```sh
pi install npm:pi-context-kit
```

Restart Pi after the install. The defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.
Restart Pi. That is all: the defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.

## Why pi-context-kit

- **A cleaner context window.** Above the threshold, old copies of files and old tool outputs become one-line notices. The newest tool outputs stay.
- **Summaries written ahead of time.** The session model writes the handoff note in the background, while it continues to work. When a ready note still fits at the threshold, compaction does not wait for a new summary.
- **Nothing is deleted.** The session keeps the original text. The model searches and reads it again with the `recall` tool.
- **Free where possible.** Replacing old reads, pruning and shaking do not call the model.
- **Cache-friendly.** Context edits happen only above the threshold, in one batch. The provider's prompt cache breaks once per maintenance step, not at each turn.
- **Zero setup.** Install, restart, work. Tune it later if you want.

## What the model sees

Above the threshold, large old content becomes a one-line notice. The full text stays in the session. Example (the sizes and IDs are illustrative; the last notice appears only when shaking runs, see [`methodOrder`](#methodorder)):

```diff
- <first read of src/app.ts, about 5,000 tokens>
+ [Superseded by a newer read of this file]

- <output of npm test from one hour ago, about 12,000 tokens>
+ [Output pruned: about 12000 tokens. Call recall with entryId "a1b2c3d4" to read it.]

- <a large code block in an old reply, about 2,000 tokens>
+ [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.]
```

These notices never change your messages or the model's tool calls. The model's reasoning also stays, with one exception for Anthropic. Compaction still replaces older messages with a summary. See [What maintenance preserves](#what-maintenance-preserves).

## Pi alone, and Pi with pi-context-kit

Expand All @@ -19,24 +49,16 @@ Restart Pi after the install. The defaults work without configuration. Requireme

The original session entries never change. Only the context that Pi sends to the model becomes smaller.

This extension is for Pi users with long sessions: many file reads, long command outputs, or many compactions. In a short session, the context rarely reaches the threshold. Then the context does not change at the end of a turn. A background handoff note can still start near the threshold, and `/compact` uses a handoff note instead of Pi's summary.

## The problem
pi-context-kit is for long Pi sessions: many file reads, long command outputs, or many compactions. In a short session, the context rarely reaches the threshold. Then the context does not change at the end of a turn. A background handoff note can still start near the threshold, and `/compact` tries a handoff note first, with Pi's summary as the fallback.

An AI model can read only a limited amount of text at one time. This limit is the **context window**.
Text is measured in **tokens**. One token is approximately 3 to 4 characters of English text.
## Why long Pi sessions need context management

In a long session, the conversation fills the context window. File reads and command outputs are usually the largest parts.
When the window is almost full, Pi does a **compaction**: it replaces the old conversation with a summary.
A summary can lose details, and it costs time and money.
An AI model can read only a limited amount of text at one time. This limit is the **context window**. Text is measured in **tokens**. Pi counts approximately 4 characters as one token.

pi-context-kit does three things:
In a long session, the conversation fills the context window. File reads and command outputs are usually the largest parts. When the window is almost full, Pi does a **compaction**: it replaces the old conversation with a summary. A summary can lose details, and it costs time and money.

1. It replaces repeated file reads and old tool outputs in the model's context.
2. When a summary is necessary, it can prepare a handoff note in advance.
3. It leaves the original session entries unchanged. The model can retrieve earlier text on the current branch with `recall`.

## Words used in this document
<details>
<summary>Words used in this document</summary>

| Word | Meaning |
| --- | --- |
Expand All @@ -50,6 +72,8 @@ pi-context-kit does three things:
| Handoff note | A summary that pi-context-kit writes with the same model as your session. |
| Pi's summary | The summary that Pi writes when no handoff note is available. |

</details>

## Install

1. Open a terminal.
Expand Down Expand Up @@ -90,30 +114,27 @@ If a value is incorrect, Pi shows a warning that starts with `pi-context-kit: in

To use a setting only in one project, put the same block in the file `.pi/settings.json` in that project folder. Project settings replace global settings.

## What happens during a session
## How it works during a session

```text
Every turn ends
|
v
1. Remove old file reads that a newer read replaced
|
v
Context near the threshold? --yes--> 2. Start a handoff note in the background
Context near the threshold? --yes--> Start a handoff note in the background
|
v
Context above the threshold? --no--> continue to work
|
yes
v
3. Prune old tool outputs
Replace old file reads, and prune old tool outputs
|
v
Small enough now? --yes--> continue to work
|
no
v
4. Try each method in "methodOrder": handoff, shake, soft
Try each method in "methodOrder": handoff, shake, soft
```

### 1. Old file reads are replaced
Expand Down Expand Up @@ -530,7 +551,7 @@ To combine recipes, put all the settings in one `contextKit` block:
- **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
- **Subagents** use their own settings. They show no warnings, because they have no screen.

## Questions
## FAQ

**Does it slow down my work?**
Usually not. The handoff note is written in the background, and pruning and shaking do not use the model.
Expand Down
Loading