From 78c07de3875860296a0f1a46d457cdae78f91301 Mon Sep 17 00:00:00 2001 From: HugoLopes45 Date: Wed, 11 Nov 2026 22:46:18 +0100 Subject: [PATCH 1/2] Open the README with benefits, real notices and badges Visitors had to read a glossary before they saw what the extension does. The first screen now shows the promise, the install command, the benefits, and the exact notices that replace old content, under headings that use the search terms. --- README.md | 60 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 71cdce4..3c7a46a 100644 --- a/README.md +++ b/README.md @@ -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 every original line of text one `recall` 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.** Old copies of files and old command outputs leave the model's context. The model works with what is current. +- **Summaries written ahead of time.** The session model writes the handoff note in the background, while it continues to work. When the note is ready 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): + +```diff +- ++ [Superseded by a newer read of this file] + +- ++ [Output pruned: about 12000 tokens. Call recall with entryId "a1b2c3d4" to read it.] + +- ++ [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.] +``` + +Your messages and the model's tool calls stay in the context. The model's reasoning also stays, with one exception for Anthropic. See [What maintenance preserves](#what-maintenance-preserves). ## Pi alone, and Pi with pi-context-kit @@ -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. +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` uses a handoff note instead of Pi's summary. -## The problem +## Why long Pi sessions need context management -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. +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. -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. +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. -pi-context-kit does three things: - -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 +
+Words used in this document | Word | Meaning | | --- | --- | @@ -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. | +
+ ## Install 1. Open a terminal. @@ -90,7 +114,7 @@ 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 @@ -530,7 +554,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. From fa1f7e28279057afb314ff840a9f66ade3ac3658 Mon Sep 17 00:00:00 2001 From: HugoLopes45 Date: Wed, 11 Nov 2026 22:51:46 +0100 Subject: [PATCH 2/2] Scope README claims to the threshold, the branch and the fallbacks A fact-check found five overpromises in the new top section and a diagram that showed read replacement at every turn, although it happens only above the threshold. --- README.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 3c7a46a..0f92e06 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ **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 every original line of text one `recall` away. +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 @@ -14,8 +14,8 @@ Restart Pi. That is all: the defaults work without configuration. Requirements: ## Why pi-context-kit -- **A cleaner context window.** Old copies of files and old command outputs leave the model's context. The model works with what is current. -- **Summaries written ahead of time.** The session model writes the handoff note in the background, while it continues to work. When the note is ready at the threshold, compaction does not wait for a new summary. +- **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. @@ -23,7 +23,7 @@ Restart Pi. That is all: the defaults work without configuration. Requirements: ## 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): +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 - @@ -36,7 +36,7 @@ Above the threshold, large old content becomes a one-line notice. The full text + [Elided block: about 2000 tokens. Call recall with entryId "e5f6a7b8" to read it.] ``` -Your messages and the model's tool calls stay in the context. The model's reasoning also stays, with one exception for Anthropic. See [What maintenance preserves](#what-maintenance-preserves). +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 @@ -49,11 +49,11 @@ Your messages and the model's tool calls stay in the context. The model's reason The original session entries never change. Only the context that Pi sends to the model becomes smaller. -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` uses a handoff note instead of Pi's summary. +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. ## Why long Pi sessions need context management -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. +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. 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. @@ -120,24 +120,21 @@ To use a setting only in one project, put the same block in the file `.pi/settin 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