pi-context-kit 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +22 -8
  2. package/LICENSE +1 -1
  3. package/README.md +162 -151
  4. package/context-kit.schema.json +62 -78
  5. package/extensions/index.ts +279 -256
  6. package/node_modules/pi-hl-utils/LICENSE +21 -0
  7. package/node_modules/pi-hl-utils/package.json +47 -0
  8. package/node_modules/pi-hl-utils/src/errors.ts +9 -0
  9. package/node_modules/pi-hl-utils/src/evidence.ts +363 -0
  10. package/node_modules/pi-hl-utils/src/expand-on-click.ts +90 -0
  11. package/node_modules/pi-hl-utils/src/layered-settings.ts +513 -0
  12. package/node_modules/pi-hl-utils/src/null-optional-arguments.ts +147 -0
  13. package/node_modules/pi-hl-utils/src/pi-agent-session-discovery.ts +48 -0
  14. package/node_modules/pi-hl-utils/src/record.ts +3 -0
  15. package/node_modules/pi-hl-utils/src/settings-command.ts +213 -0
  16. package/node_modules/pi-hl-utils/src/settings-menu.ts +477 -0
  17. package/node_modules/pi-hl-utils/src/token-calibration.ts +39 -0
  18. package/node_modules/pi-hl-utils/src/ui.ts +355 -0
  19. package/package.json +42 -44
  20. package/src/background.ts +2 -3
  21. package/src/command.ts +17 -0
  22. package/src/config.ts +3 -207
  23. package/src/context-kit-settings.ts +152 -0
  24. package/src/context.ts +43 -16
  25. package/src/files.ts +6 -13
  26. package/src/handoff.ts +3 -7
  27. package/src/maintain.ts +6 -19
  28. package/src/menu.ts +159 -0
  29. package/src/migrate.ts +99 -19
  30. package/src/note.ts +5 -6
  31. package/src/prune.ts +2 -1
  32. package/src/recall.ts +14 -37
  33. package/src/settings-file.ts +13 -101
  34. package/src/shake.ts +6 -12
  35. package/src/stale.ts +22 -26
  36. package/src/status.ts +2 -6
  37. package/src/tool-calls.ts +2 -3
  38. package/README.zh-CN.md +0 -387
  39. package/src/panel.ts +0 -89
package/CHANGELOG.md CHANGED
@@ -2,30 +2,44 @@
2
2
 
3
3
  Pi shows the entries newer than your installed version after `pi update`.
4
4
 
5
- ## [0.4.2] - 2026-11-13
5
+ ## 0.4.4
6
+
7
+ ### Patch Changes
8
+
9
+ - Settings now live in the `context-kit` entry of Pi's `settings.json`, globally and per project, with a session layer changed by `/context-kit`. On first start, each layer without a `context-kit` entry is imported once: its `context-kit.json` when that file exists, which is then renamed to `context-kit.json.migrated`, otherwise the 0.3 `contextKit` block of `settings.json`. The `/context-kit` menu lists every setting. Per-layer validation now ignores a whole layer when one key is invalid or unknown, so the other layers still apply.
10
+
11
+ ## 0.4.3
12
+
13
+ ### Patch Changes
14
+
15
+ - An early summary can no longer be longer than the room left under the threshold. Before, Pi could generate a longer summary that pi-context-kit then rejected.
16
+ - The documentation is in English only. The Simplified Chinese translation is removed.
17
+ - The README states that handoff notes and summaries skip the `context` and `before_provider_request` hooks of other extensions, as Pi's own compaction summaries do.
18
+
19
+ ## 0.4.2 - 2026-11-13
6
20
 
7
21
  - Documentation in Simplified Chinese: README, contribution guide and security policy. No change to the extension.
8
22
 
9
- ## [0.4.1] - 2026-11-13
23
+ ## 0.4.1 - 2026-11-13
10
24
 
11
25
  - The README has a quick start and a troubleshooting section. No change to the extension.
12
26
 
13
- ## [0.4.0] - 2026-11-13
27
+ ## 0.4.0 - 2026-11-13
14
28
 
15
29
  - The footer shows how full the context is and when cleanup starts, for example `Context 62% · cleanup at 75%`.
16
30
  - `/context-kit` opens a panel to turn cleanup on or off, and to choose when and how to clean up.
17
31
  - Settings move to their own file: `~/.pi/agent/context-kit.json`, and `.pi/context-kit.json` in a trusted project. At the first start, the `contextKit` entry of Pi's `settings.json` moves there with the same behavior.
18
32
  - The default threshold is now `75%`. Set `"threshold": "pi"` to wait for Pi's limit as before.
19
33
 
20
- ## [0.3.2] - 2026-11-11
34
+ ## 0.3.2 - 2026-11-11
21
35
 
22
36
  - Documentation only.
23
37
 
24
- ## [0.3.1] - 2026-11-11
38
+ ## 0.3.1 - 2026-11-11
25
39
 
26
40
  - Documentation and package metadata only.
27
41
 
28
- ## [0.3.0] - 2026-11-11
42
+ ## 0.3.0 - 2026-11-11
29
43
 
30
44
  - Breaking: the `staleSuffixTokens` setting is removed. Remove it from your settings.
31
45
  - Supports Pi 1.5. Pi 1.0.3 is still the oldest supported version.
@@ -35,11 +49,11 @@ Pi shows the entries newer than your installed version after `pi update`.
35
49
  - With Pi's compaction off, pi-context-kit changes the context only on `/compact`.
36
50
  - Background handoff notes are cancelled after session-tree navigation.
37
51
 
38
- ## [0.2.1] - 2026-10-06
52
+ ## 0.2.1 - 2026-10-06
39
53
 
40
54
  - The README explains each term, the steps of a session, and each setting.
41
55
 
42
- ## [0.2.0] - 2026-10-06
56
+ ## 0.2.0 - 2026-10-06
43
57
 
44
58
  - Handoff notes use the session's thinking level and tool choice, so Anthropic can reuse the cached conversation.
45
59
  - An earlier threshold compacts at the end of a turn, even when no handoff note is ready.
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 HugoLopes45
3
+ Copyright (c) 2026 Hugo Lopes
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,16 +1,10 @@
1
1
  # pi-context-kit: long Pi sessions that stay sharp
2
2
 
3
- English | [简体中文](https://github.com/HugoLopes45/pi-context-kit/blob/main/README.zh-CN.md)
3
+ [![CI](https://github.com/HugoLopes45/pi-extensions/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/HugoLopes45/pi-extensions/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit) [![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit) [![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)
4
4
 
5
- [![CI](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/HugoLopes45/pi-context-kit/actions/workflows/ci.yml)
6
- [![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit)
7
- [![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit)
8
- [![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org)
9
- [![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)
5
+ **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.
10
6
 
11
- 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.
12
-
13
- ```sh
7
+ ```bash
14
8
  pi install npm:pi-context-kit
15
9
  ```
16
10
 
@@ -45,12 +39,12 @@ These notices never change your messages or the model's tool calls. The model's
45
39
 
46
40
  ## Pi alone, and Pi with pi-context-kit
47
41
 
48
- | In a long session | Pi alone | With pi-context-kit |
49
- | --- | --- | --- |
50
- | The model reads the same file again | Both copies stay in the context. | The old copy is replaced, above the threshold. |
51
- | Old tool outputs fill the context | They stay until Pi summarizes. | They are replaced with a short notice. No model request. |
52
- | The context reaches the limit | Pi writes a summary. | A handoff note can be ready, because it was written in the background. |
53
- | The model needs a removed detail | The summary is all that remains in the context. | The model calls `recall` to read the original text. |
42
+ | In a long session | Pi alone | With pi-context-kit |
43
+ | ----------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
44
+ | The model reads the same file again | Both copies stay in the context. | The old copy is replaced, above the threshold. |
45
+ | Old tool outputs fill the context | They stay until Pi summarizes. | They are replaced with a short notice. No model request. |
46
+ | The context reaches the limit | Pi writes a summary. | A handoff note can be ready, because it was written in the background. |
47
+ | The model needs a removed detail | The summary is all that remains in the context. | The model calls `recall` to read the original text. |
54
48
 
55
49
  The original session entries never change. Only the context that Pi sends to the model becomes smaller.
56
50
 
@@ -65,17 +59,17 @@ In a long session, the conversation fills the context window. File reads and com
65
59
  <details>
66
60
  <summary>Words used in this document</summary>
67
61
 
68
- | Word | Meaning |
69
- | --- | --- |
70
- | Token | A small piece of text. The model counts its memory in tokens. |
71
- | Context window | The maximum number of tokens that the model can read at one time. |
72
- | Context | All the text that Pi sends to the model now: instructions, messages, and tool outputs. |
73
- | Turn | One cycle: the model replies, uses its tools, and stops. |
74
- | Tool output | The result of a tool, for example the content of a file or the output of a command. |
75
- | Threshold | The number of tokens at which maintenance starts. |
76
- | Compaction | Pi replaces the old conversation with a summary. The newest messages stay. |
77
- | Handoff note | A summary that pi-context-kit writes with the same model as your session. |
78
- | Pi's summary | The summary that Pi writes when no handoff note is available. |
62
+ | Word | Meaning |
63
+ | -------------- | -------------------------------------------------------------------------------------- |
64
+ | Token | A small piece of text. The model counts its memory in tokens. |
65
+ | Context window | The maximum number of tokens that the model can read at one time. |
66
+ | Context | All the text that Pi sends to the model now: instructions, messages, and tool outputs. |
67
+ | Turn | One cycle: the model replies, uses its tools, and stops. |
68
+ | Tool output | The result of a tool, for example the content of a file or the output of a command. |
69
+ | Threshold | The number of tokens at which maintenance starts. |
70
+ | Compaction | Pi replaces the old conversation with a summary. The newest messages stay. |
71
+ | Handoff note | A summary that pi-context-kit writes with the same model as your session. |
72
+ | Pi's summary | The summary that Pi writes when no handoff note is available. |
79
73
 
80
74
  </details>
81
75
 
@@ -88,42 +82,38 @@ You need Pi 1.0.3 or later and Node.js 22.19 or later.
88
82
  3. Look at the footer. It shows `Context 0% · cleanup at 75%` when the extension is active.
89
83
  4. Work as usual. Type `/context-kit` to change the settings.
90
84
 
91
- ## Update, try or remove
92
-
93
- ```sh
94
- pi update npm:pi-context-kit # update, then restart Pi
95
- pi -e npm:pi-context-kit # try for one session without installing
96
- pi remove npm:pi-context-kit # remove, then restart Pi
97
- ```
98
-
99
- After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).
100
-
101
- ## Use it
85
+ ## Footer
102
86
 
103
87
  You do not need to configure anything. pi-context-kit shows its state in Pi's footer:
104
88
 
105
- | Footer | Meaning |
106
- | --- | --- |
107
- | `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. |
89
+ | Footer | Meaning |
90
+ | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
91
+ | `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. |
108
92
  | `Context 70% · cleanup at 75% · writing summary` | A handoff note is being written in the background. `summary ready` means that it is ready. |
109
- | `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. |
110
- | `Context cleanup off` | You turned automatic cleanup off. |
93
+ | `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. |
94
+ | `Context cleanup off` | You turned automatic cleanup off. |
111
95
 
112
96
  After pi-context-kit shortens old outputs, Pi shows a notice, for example: `pi-context-kit freed 17% of the context (34k tokens). The agent can still look up what was removed.`
113
97
 
98
+ ## Commands
99
+
114
100
  To change the settings, type `/context-kit` and press Enter. Select a line with the arrow keys and press Enter to change its value. The change is saved at once and applies from the next turn. Press Escape to close the panel.
115
101
 
116
- | Panel line | Choices | Setting in the file |
117
- | --- | --- | --- |
118
- | Automatic cleanup | On, Off | `enabled` |
119
- | Clean up when the context is | 50% to 90% full, At Pi's limit | `threshold` |
120
- | Cleanup method | Summary notes (recommended), Trim first, Pi's summary | `strategy`: `"balanced"`, `"frugal"`, `"pi-summary"` |
102
+ The panel has a scope row. Choose the session, the global settings, or the project settings when the project is trusted. Edits go to the selected scope. Each other line is one setting, named as in [Settings](#settings). A line shows the value in effect, and the scope it comes from when that is not the default. The first three lines are the main settings:
103
+
104
+ | Line | On Enter |
105
+ | ----------- | ----------------------------------------------------------------- |
106
+ | `enabled` | Steps through `inherit`, `on`, `off` |
107
+ | `threshold` | Opens a field: a token count, a percentage such as `75%`, or `pi` |
108
+ | `strategy` | Steps through `inherit`, `balanced`, `frugal`, `pi-summary` |
109
+
110
+ The other on and off settings step the same way as `enabled`. The other settings open a field. In a field, type `inherit` to remove the value from the selected scope.
121
111
 
122
- The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method.
112
+ Commands write the same values, for example `/context-kit off --global` turns cleanup off in the global settings. `/context-kit set threshold 8000` sets a value for this session only. `/context-kit inherit threshold --project` removes the project value. Without `--global` or `--project`, a command writes to the session.
123
113
 
124
114
  Outside the interactive mode, `/context-kit` shows the current settings in one line.
125
115
 
126
- ## How it works during a session
116
+ ## How it works
127
117
 
128
118
  ```text
129
119
  Every turn ends
@@ -148,16 +138,13 @@ Outside the interactive mode, `/context-kit` shows the current settings in one l
148
138
 
149
139
  ### 1. Old file reads are replaced
150
140
 
151
- Sometimes the model reads the same file two times. The first copy is then old.
152
- pi-context-kit replaces the old copy with this text: `[Superseded by a newer read of this file]`.
141
+ Sometimes the model reads the same file two times. The first copy is then old. pi-context-kit replaces the old copy with this text: `[Superseded by a newer read of this file]`.
153
142
 
154
- It does this only when the newer read covers all of the old read. If the newer read was cut short, the old copy stays.
155
- It does this only when the context is above the threshold, in the same change as pruning, shaking or compaction. Each change to old text makes the provider read all later text again without its cache. With Anthropic, it also removes the model's earlier reasoning from the request. One change near the threshold costs less than one change at each turn.
143
+ It does this only when the newer read covers all of the old read. If the newer read was cut short, the old copy stays. It does this only when the context is above the threshold, in the same change as pruning, shaking or compaction. Each change to old text makes the provider read all later text again without its cache. With Anthropic, it also removes the model's earlier reasoning from the request. One change near the threshold costs less than one change at each turn.
156
144
 
157
145
  ### 2. A handoff note is prepared in advance
158
146
 
159
- Before the context reaches the threshold, the session model writes a handoff note in the background. Your work does not stop.
160
- The note starts one eighth of the threshold early, with a maximum of 32,000 tokens. With a threshold of 150,000 tokens, it starts at approximately 131,250 tokens.
147
+ Before the context reaches the threshold, the session model writes a handoff note in the background. Your work does not stop. The note starts one eighth of the threshold early, with a maximum of 32,000 tokens. With a threshold of 150,000 tokens, it starts at approximately 131,250 tokens.
161
148
 
162
149
  The note uses the same sections as Pi's summary. It also lists the files that were read and changed.
163
150
 
@@ -172,14 +159,16 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this
172
159
 
173
160
  If pruning is not sufficient, pi-context-kit tries the methods of the [strategy](#main-settings), one after the other:
174
161
 
175
- | Method | What it does | Uses the model? |
176
- | --- | --- | --- |
177
- | `handoff` | Replaces the old conversation with the handoff note. The newest messages stay. | Yes |
178
- | `shake` | Replaces large old code blocks, XML blocks, and images with a short notice. Your messages are never shaken. | No |
179
- | `soft` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops here. | Yes |
162
+ | Method | What it does | Uses the model? |
163
+ | --------- | ----------------------------------------------------------------------------------------------------------- | --------------- |
164
+ | `handoff` | Replaces the old conversation with the handoff note. The newest messages stay. | Yes |
165
+ | `shake` | Replaces large old code blocks, XML blocks, and images with a short notice. Your messages are never shaken. | No |
166
+ | `soft` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops here. | Yes |
180
167
 
181
168
  Your work continues during these steps. pi-context-kit never stops a running task to compact.
182
169
 
170
+ Failed and truncated responses remain under Pi's recovery control. Aborted turns do not start background notes or commit maintenance edits. Disabling cleanup cancels pending notes at the next turn boundary.
171
+
183
172
  ### The `recall` tool
184
173
 
185
174
  The `recall` tool reads original session text, not the shortened context sent to the model. It can:
@@ -187,14 +176,13 @@ The `recall` tool reads original session text, not the shortened context sent to
187
176
  - search earlier conversation text on the current branch, including removed and summarized messages;
188
177
  - read an entry's text by ID, with pagination for large entries.
189
178
 
190
- Other branches and sessions are excluded. System prompt entries are not searched.
191
- Images remain in the original session entries, but `recall` returns only their MIME types, not image content.
192
- The model must call `recall` to retrieve a missing detail. Retrieval is not automatic.
179
+ Other branches and sessions are excluded. System prompt entries are not searched. Shell commands explicitly excluded from model context with `!!` are not available through `recall`.
180
+
181
+ Images remain in the original session entries, but `recall` returns only their MIME types, not image content. The model must call `recall` to retrieve a missing detail. Retrieval is not automatic.
193
182
 
194
183
  ## What maintenance preserves
195
184
 
196
- File-read replacement, pruning, and shaking do not rewrite the original session entries.
197
- In the model's context, these steps preserve:
185
+ File-read replacement, pruning, and shaking do not rewrite the original session entries. In the model's context, these steps preserve:
198
186
 
199
187
  - Your messages, including your instructions and images.
200
188
  - The model's tool calls and reasoning. Anthropic can still drop the reasoning after an edited message (see [Old file reads are replaced](#1-old-file-reads-are-replaced)).
@@ -204,126 +192,146 @@ Compaction is different: it replaces older context with a summary, including old
204
192
 
205
193
  ## Settings
206
194
 
207
- This section is for users who edit the settings file. The panel changes the three main settings; the file also has the advanced settings.
195
+ This section is for users who edit the settings. The `/context-kit` panel lists every setting, one line each. The main settings come first in this section.
208
196
 
209
197
  ### The settings files
210
198
 
211
- | File | Applies to |
212
- | --- | --- |
213
- | `~/.pi/agent/context-kit.json` | All your projects. `~` is your home folder. |
214
- | `.pi/context-kit.json` in a project folder | Only this project, and only when you trust the project in Pi. Its values replace the values of the global file. |
199
+ pi-context-kit keeps its settings in the `context-kit` entry of Pi's `settings.json`. Three layers apply, the later one wins:
215
200
 
216
- You do not need to set all settings. A missing setting uses its default. pi-context-kit reads the files again at each turn, so you do not need to restart Pi. The panel writes to the project file when that file sets the setting, otherwise to the global file.
201
+ | Layer | File | Applies to |
202
+ | ------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
203
+ | Global | `~/.pi/agent/settings.json` | All your projects. `~` is your home folder. |
204
+ | Project | `.pi/settings.json` in a project | Only this project, and only when you trust the project in Pi. Its values replace the values of the global file. |
205
+ | Session | Entries of the current session | This session only. It replaces the values of both files. Commands write here unless you name a file with `--global` or `--project`. |
217
206
 
218
- Add the `$schema` line to get completion and checks in editors such as VS Code:
207
+ Write the values in the `context-kit` entry, like this:
219
208
 
220
209
  ```json
221
210
  {
222
- "$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
223
- "threshold": "70%",
224
- "strategy": "frugal"
211
+ "context-kit": {
212
+ "threshold": "70%",
213
+ "strategy": "frugal"
214
+ }
225
215
  }
226
216
  ```
227
217
 
218
+ The package file `context-kit.schema.json` describes the `context-kit` entry for editors. Do not add a `$schema` key to the entry: it is not a setting.
219
+
220
+ You do not need to set all settings. A missing setting uses its default. Pi applies a change from the next turn, so you do not need to restart Pi.
221
+
228
222
  ### Main settings
229
223
 
230
- | Setting | Allowed values | Default | What it does |
231
- | --- | --- | --- | --- |
232
- | `enabled` | `true`, `false` | `true` | `false` stops all maintenance and handoff notes. The `recall` tool stays available. |
233
- | `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"` | Where maintenance starts. |
234
- | `strategy` | `"balanced"`, `"frugal"`, `"pi-summary"` | `"balanced"` | What pi-context-kit does when pruning is not sufficient. |
224
+ | Setting | Allowed values | Default | What it does |
225
+ | ----------- | ----------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------- |
226
+ | `enabled` | `true`, `false` | `true` | `false` stops all maintenance and handoff notes. The `recall` tool stays available. |
227
+ | `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"` | Where maintenance starts. |
228
+ | `strategy` | `"balanced"`, `"frugal"`, `"pi-summary"` | `"balanced"` | What pi-context-kit does when pruning is not sufficient. |
235
229
 
236
230
  **`threshold`.** A percentage applies to each model's context window, so `"75%"` is 150,000 tokens with a 200,000-token window and 750,000 tokens with a 1,000,000-token window. Decimals are allowed, for example `"72.5%"`. A number such as `150000` is the same for all models. Do not put spaces, dots or commas in a number of tokens. `"pi"` waits for Pi's own limit. pi-context-kit can start before Pi's limit, never after: if your value is larger, Pi's limit is used. See [Pi settings that also apply](#pi-settings-that-also-apply).
237
231
 
238
232
  **`strategy`.**
239
233
 
240
- | Strategy (panel name) | Above the threshold, after pruning | Background requests |
241
- | --- | --- | --- |
242
- | `"balanced"` (Summary notes) | A handoff note. If the note fails, shake. Then Pi's summary. | Yes: the note is written before the threshold. |
243
- | `"frugal"` (Trim first) | Shake, because it does not call the model. If that is not sufficient, a handoff note. Then Pi's summary. | No |
244
- | `"pi-summary"` (Pi's summary) | Pi's summary. No handoff note, no shaking. | No |
234
+ | Strategy | Above the threshold, after pruning | Background requests |
235
+ | -------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
236
+ | `"balanced"` | A handoff note. If the note fails, shake. Then Pi's summary. | Yes: the note is written before the threshold. |
237
+ | `"frugal"` | Shake, because it does not call the model. If that is not sufficient, a handoff note. Then Pi's summary. | No |
238
+ | `"pi-summary"` | Pi's summary. No handoff note, no shaking. | No |
245
239
 
246
240
  ### Advanced settings
247
241
 
248
- Put these settings in an `advanced` block. Most users never need them.
242
+ Put these settings in the `context-kit` entry under the flat names in the table. Most users never need them.
249
243
 
250
244
  ```json
251
245
  {
252
- "advanced": {
246
+ "context-kit": {
253
247
  "methodOrder": ["handoff", "shake", "soft"],
254
248
  "background": true,
255
249
  "supersedeReads": true,
256
250
  "progressRatio": 0.8,
257
- "prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 },
258
- "shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 }
251
+ "pruneEnabled": true,
252
+ "pruneProtectTokens": 40000,
253
+ "pruneMinSavings": 20000,
254
+ "pruneMinTokens": 50,
255
+ "shakeProtectTokens": 16000,
256
+ "shakeMinSavings": 4000,
257
+ "shakeBlockMinTokens": 400
259
258
  }
260
259
  }
261
260
  ```
262
261
 
263
- | Setting | Default | What it does |
264
- | --- | --- | --- |
265
- | `methodOrder` | From `strategy` | Replaces the method order of the strategy. Allowed values: `"handoff"`, `"shake"`, `"soft"`. Methods after `"soft"` never run. Without `"handoff"` before `"soft"`, no handoff note is written, also on `/compact`. An empty list `[]` only replaces old reads and prunes. |
266
- | `background` | From `strategy` | `true` writes the handoff note in the background, one eighth of the threshold early (maximum 32,000 tokens). `false` writes it at the threshold, and your work waits for it. |
267
- | `supersedeReads` | `true` | Replaces the old copy of a file that the model read again. |
268
- | `progressRatio` | `0.8` | Each method must bring the context to this fraction of the threshold, otherwise its result is not used and the next method runs. Above 0, up to 1. |
269
- | `prune.enabled` | `true` | `false` never prunes tool outputs. |
270
- | `prune.protectTokens` | `40000` | The newest tool outputs, up to this number of tokens, are never pruned. |
271
- | `prune.minSavings` | `20000` | Pruning occurs only if it removes at least this number of tokens. |
272
- | `prune.minTokens` | `50` | Tool outputs smaller than this are never pruned. |
273
- | `shake.protectTokens` | `16000` | The newest context, up to this number of tokens, is never shaken. Your own messages are never shaken. |
274
- | `shake.minSavings` | `4000` | Shaking occurs only if it removes at least this number of tokens. |
275
- | `shake.blockMinTokens` | `400` | Code and XML blocks smaller than this are never shaken. |
262
+ The flat names replace the nested names of 0.4 `context-kit.json`: `prune.enabled` is `pruneEnabled`, `prune.protectTokens` is `pruneProtectTokens`, `prune.minSavings` is `pruneMinSavings`, `prune.minTokens` is `pruneMinTokens`, and `shake.protectTokens`, `shake.minSavings` and `shake.blockMinTokens` become `shakeProtectTokens`, `shakeMinSavings` and `shakeBlockMinTokens`.
263
+
264
+ | Setting | Default | What it does |
265
+ | --------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
266
+ | `methodOrder` | From `strategy` | Replaces the method order of the strategy. Allowed values: `"handoff"`, `"shake"`, `"soft"`. Methods after `"soft"` never run. Without `"handoff"` before `"soft"`, no handoff note is written, also on `/compact`. An empty list `[]` only replaces old reads and prunes. |
267
+ | `background` | From `strategy` | `true` writes the handoff note in the background, one eighth of the threshold early (maximum 32,000 tokens). `false` writes it at the threshold, and your work waits for it. |
268
+ | `supersedeReads` | `true` | Replaces the old copy of a file that the model read again. |
269
+ | `progressRatio` | `0.8` | Each method must bring the context to this fraction of the threshold, otherwise its result is not used and the next method runs. Above 0, up to 1. |
270
+ | `pruneEnabled` | `true` | `false` never prunes tool outputs. |
271
+ | `pruneProtectTokens` | `40000` | The newest tool outputs, up to this number of tokens, are never pruned. |
272
+ | `pruneMinSavings` | `20000` | Pruning occurs only if it removes at least this number of tokens. |
273
+ | `pruneMinTokens` | `50` | Tool outputs smaller than this are never pruned. |
274
+ | `shakeProtectTokens` | `16000` | The newest context, up to this number of tokens, is never shaken. Your own messages are never shaken. |
275
+ | `shakeMinSavings` | `4000` | Shaking occurs only if it removes at least this number of tokens. |
276
+ | `shakeBlockMinTokens` | `400` | Code and XML blocks smaller than this are never shaken. |
276
277
 
277
278
  ### When a setting is incorrect
278
279
 
279
- pi-context-kit checks each value. If a value is incorrect, Pi shows a warning and the setting uses its default. The other settings still apply. Example: with `"threshold": "150000"` (a text in quotes, not a number), Pi shows:
280
-
281
- ```text
282
- pi-context-kit settings need attention: threshold must be a positive integer (tokens), a percentage such as "75%", or "pi" (default used). Type /context-kit to see them.
283
- ```
280
+ pi-context-kit checks every value of a layer. If one value is incorrect, pi-context-kit ignores that whole layer, the global file or the project file. The other layer still applies, and defaults apply to every setting that no remaining layer sets. Pi shows a warning that names the layer and the problem.
284
281
 
285
- Pi also warns about a setting name with a spelling mistake, a file that is not valid JSON, and settings that have no effect, for example `advanced.background` without a handoff note in the method order.
282
+ Pi also warns about an unknown setting name, which makes its layer incorrect, and about a settings file that is not valid JSON.
286
283
 
287
284
  ### Upgrade from 0.3
288
285
 
289
- You do not need to do anything. Version 0.4 reads its own file. At the first start, it copies the `contextKit` block of Pi's `settings.json` to `~/.pi/agent/context-kit.json` (and the block of a trusted project to `.pi/context-kit.json`), with the same behavior, and shows a notice once. The project file gets only the settings that the project block changed, because 0.3 used the global block for the others. It does not change Pi's `settings.json`; you can delete the `contextKit` block, which is no longer used. If `context-kit.json` already exists, nothing is copied. If you had no `contextKit` block, 0.4 starts maintenance at the new default of `"75%"`; to wait for Pi's limit as before, set `"threshold": "pi"`. The table shows how the values are converted.
286
+ You do not need to do anything. At each start, pi-context-kit moves its settings into the `context-kit` entry once for each layer that has no such entry.
287
+
288
+ A layer that has no `context-kit` entry imports its `context-kit.json` if that file exists. Otherwise it converts the `contextKit` block of Pi's `settings.json`, the 0.3 settings, with the same behavior.
289
+
290
+ The project block converts over the global settings, as 0.3 merged them. The project entry gets only the settings that the project block changed.
291
+
292
+ After the import is written, `context-kit.json` is renamed to `context-kit.json.migrated`, and pi-context-kit shows a notice once. If the write fails, the file keeps its name and the import runs again at the next start. Defaults apply until then.
293
+
294
+ An existing `context-kit` entry is never changed by the import. The 0.3 `contextKit` block stays in `settings.json` and is no longer read, so you can delete it.
290
295
 
291
- | 0.3 (`contextKit` in `settings.json`) | 0.4 (`context-kit.json`) |
292
- | --- | --- |
293
- | `thresholdTokens: 150000` | `threshold: 150000` |
294
- | `thresholdPercent: 75` | `threshold: "75%"` |
295
- | Both `thresholdTokens` and `thresholdPercent` | `threshold` with the number of tokens |
296
- | No threshold (Pi's limit) | `threshold: "pi"`. The default for new users is `"75%"`. |
297
- | `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`, with `advanced.background: true` unless `asyncEnabled` was `false` |
298
- | `methodOrder: ["soft"]` | `strategy: "pi-summary"` |
299
- | Other `methodOrder` values | `advanced.methodOrder`, without `"remote"` and `"snapcompact"`, which 0.3 already skipped. A list with an unknown method becomes the default order, as in 0.3. |
300
- | `asyncEnabled` | `advanced.background`, when it differs from the strategy |
301
- | `supersedeReads`, `progressRatio`, `prune`, `shake` | The same names in `advanced` |
296
+ If you had no `contextKit` block, 0.4 starts maintenance at the new default of `"75%"`; to wait for Pi's limit as before, set `"threshold": "pi"`. The table shows how the values are converted.
297
+
298
+ | 0.3 (`contextKit` in `settings.json`) | 0.4 (`context-kit` entry) |
299
+ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
300
+ | `thresholdTokens: 150000` | `threshold: 150000` |
301
+ | `thresholdPercent: 75` | `threshold: "75%"` |
302
+ | Both `thresholdTokens` and `thresholdPercent` | `threshold` with the number of tokens |
303
+ | No threshold (Pi's limit) | `threshold: "pi"`. The default for new users is `"75%"`. |
304
+ | `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`, with `background: true` unless `asyncEnabled` was `false` |
305
+ | `methodOrder: ["soft"]` | `strategy: "pi-summary"` |
306
+ | Other `methodOrder` values | `methodOrder`, without `"remote"` and `"snapcompact"`, which 0.3 already skipped. A list with an unknown method becomes the default order, as in 0.3. |
307
+ | `asyncEnabled` | `background`, when it differs from the strategy |
308
+ | `supersedeReads`, `progressRatio` | The same names |
309
+ | `prune`, `shake` (0.3 or 0.4 `context-kit.json`) | Flat names, such as `pruneEnabled` and `shakeMinSavings` |
302
310
 
303
311
  ### Pi settings that also apply
304
312
 
305
313
  These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block of Pi's `settings.json`.
306
314
 
307
- | Pi setting | Default | Effect on pi-context-kit |
308
- | --- | --- | --- |
309
- | `compaction.enabled` | `true` | `false` stops Pi's automatic compaction. Then pi-context-kit changes the context only on `/compact`, because there is no threshold. |
310
- | `compaction.reserveTokens` | `16384` | Pi's limit is the context window minus this number. pi-context-kit always starts at this limit or before. |
311
- | `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
312
- | `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
315
+ | Pi setting | Default | Effect on pi-context-kit |
316
+ | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
317
+ | `compaction.enabled` | `true` | `false` stops Pi's automatic compaction. Then pi-context-kit changes the context only on `/compact`, because there is no threshold. |
318
+ | `compaction.reserveTokens` | `16384` | Pi's limit is the context window minus this number. pi-context-kit always starts at this limit or before. |
319
+ | `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
320
+ | `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
313
321
 
314
322
  pi-context-kit has no setting per model. To start earlier for one model only, make Pi's limit smaller for this model with `compaction.modelOverrides`, for example `{ "compaction": { "modelOverrides": { "provider/model-id": { "reserveTokens": 80000 } } } }`. With a 200,000-token window, this model then starts at 120,000 tokens at the latest. The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`.
315
323
 
316
- ## Recipes
324
+ ### Recipes
317
325
 
318
- | I want to... | `context-kit.json` |
319
- | --- | --- |
320
- | Start later, at Pi's own limit | `{ "threshold": "pi" }` |
321
- | Start at the same number of tokens on all models | `{ "threshold": 150000 }` |
322
- | Avoid model requests when possible | `{ "strategy": "frugal" }` |
323
- | Never write a handoff note | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` |
324
- | Keep more recent tool outputs | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` |
325
- | Keep all old file copies | `{ "advanced": { "supersedeReads": false } }` |
326
- | Turn pi-context-kit off, but keep `recall` | `{ "enabled": false }`, or `/context-kit` |
326
+ | I want to... | Value in the `context-kit` entry |
327
+ | ------------------------------------------------ | -------------------------------------------------- |
328
+ | Start later, at Pi's own limit | `"threshold": "pi"` |
329
+ | Start at the same number of tokens on all models | `"threshold": 150000` |
330
+ | Avoid model requests when possible | `"strategy": "frugal"` |
331
+ | Never write a handoff note | `"methodOrder": ["shake", "soft"]` |
332
+ | Keep more recent tool outputs | `"pruneProtectTokens": 80000` |
333
+ | Keep all old file copies | `"supersedeReads": false` |
334
+ | Turn pi-context-kit off, but keep `recall` | `"enabled": false`, or `/context-kit off --global` |
327
335
 
328
336
  ## Limits
329
337
 
@@ -333,25 +341,25 @@ pi-context-kit has no setting per model. To start earlier for one model only, ma
333
341
  - **If Pi's compaction is off** (`compaction.enabled: false`), pi-context-kit changes the context only when you run `/compact`. Then it writes a handoff note, as with compaction on. `threshold` is ignored, because pi-context-kit edits the context automatically only at a threshold.
334
342
  - **Manual compaction and errors.** When you type `/compact`, when the context is too large for the model, or when Pi compacts before a turn, `shake` cannot run. pi-context-kit uses a ready handoff note, or Pi's summary.
335
343
  - **The method order stops at `soft`.** The methods after `soft` do not run.
344
+ - **Summary requests skip session hooks.** Handoff notes and early summaries go to the model directly, as Pi's own compaction summaries do. The `context` and `before_provider_request` hooks of other extensions do not change these requests. If an extension removes sensitive text with these hooks, that text can still reach the model in a summary request.
336
345
  - **Subagents** read the same settings files. They show no warnings and no status, because they have no screen.
337
346
 
338
347
  ## Troubleshooting
339
348
 
340
349
  **No `Context` in the footer**: type `pi list` and check that it shows `npm:pi-context-kit`. Then restart Pi. Pi shows the footer only in the interactive mode.
341
350
 
342
- **`pi-context-kit settings need attention`**: a value in a settings file is not valid. pi-context-kit uses the default for that value. Type `/context-kit` to see the problem, then correct the file or select a new value in the panel.
351
+ **`pi-context-kit settings need attention`**: a value in a settings layer is not valid, so that layer is ignored. The other layer still applies. Type `/context-kit` to see the problem, then correct the file or select a new value in the panel.
343
352
 
344
- **`pi-context-kit moved its settings to ...`**: an earlier version kept the settings in Pi's `settings.json`. pi-context-kit copied them to its own file once. You can remove the `contextKit` entry from `settings.json`.
353
+ **`pi-context-kit moved its settings into Pi's settings.json`**: an earlier version kept the settings in its own files. pi-context-kit moved them once, and renamed each file to `context-kit.json.migrated`. You can delete the `.migrated` files and the `contextKit` block of Pi's `settings.json`.
345
354
 
346
355
  **`pi-context-kit: handoff note failed`**: the summary request failed. pi-context-kit uses the next method or Pi's summary, so your session continues. Check the model and your provider limits.
347
356
 
348
- **The panel cannot save a value**: Pi shows `pi-context-kit:` and the file error. Check that you can write the settings file, then select the value again.
357
+ **The panel cannot save a value**: the panel shows the error under the list, and a command shows it after `pi-context-kit:`. Check that you can write the settings file, then select the value again.
349
358
 
350
359
  ## FAQ
351
360
 
352
361
  **Does it slow down my work?**
353
- Usually not. The handoff note is written in the background, and pruning and shaking do not use the model.
354
- If no note is ready at the threshold, pi-context-kit can postpone the handoff until the note in progress is ready. It can also write a new note, which adds one model request.
362
+ Usually not. The handoff note is written in the background, and pruning and shaking do not use the model. If no note is ready at the threshold, pi-context-kit can postpone the handoff until the note in progress is ready. It can also write a new note, which adds one model request.
355
363
 
356
364
  **Does it cost more?**
357
365
  A handoff note is one extra model request. It uses the same model, thinking level, and tool choice as your session. With Anthropic, this lets the provider reuse the cached conversation. Caching is not guaranteed.
@@ -365,21 +373,24 @@ Yes. Type `/compact` and the focus, for example `/compact keep the database migr
365
373
  **The model forgot a detail. What can I do?**
366
374
  Ask the model to use the `recall` tool, for example: "Use recall to find the error message from the first test run."
367
375
 
368
- ## Development
376
+ ## Update, try or remove
369
377
 
370
- ```sh
371
- npm ci
372
- npm run check
378
+ ```bash
379
+ pi update npm:pi-context-kit # update, then restart Pi
380
+ pi -e npm:pi-context-kit # try for one session without installing
381
+ pi remove npm:pi-context-kit # remove, then restart Pi
373
382
  ```
374
383
 
375
- The tests run offline with Pi's faux provider. They do not call a real model.
376
- Development uses Pi `1.5.2`. The oldest supported version is Pi `1.0.3`. CI checks the locked dependencies on Node 22 and 24, and Pi `1.0.3` and latest Pi on Node 24.
377
- Host-provided peer dependencies use `"*"`, as required by Pi's package guide. This is not a guarantee that every Pi version works.
384
+ After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).
385
+
386
+ ## Contributing
387
+
388
+ See [CONTRIBUTING.md](https://github.com/HugoLopes45/pi-extensions/blob/main/CONTRIBUTING.md) for setup, checks and releases. Report bugs on [GitHub Issues](https://github.com/HugoLopes45/pi-extensions/issues), and vulnerabilities through [SECURITY.md](https://github.com/HugoLopes45/pi-extensions/blob/main/SECURITY.md).
378
389
 
379
- ## Contributing and releases
390
+ ## Author
380
391
 
381
- See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks, pull requests and releases. Report vulnerabilities through [SECURITY.md](SECURITY.md), not public issues.
392
+ Built by [Hugo Lopes](https://github.com/HugoLopes45), a senior frontend developer based in Paris, passionate about AI and agent harnesses.
382
393
 
383
394
  ## License
384
395
 
385
- MIT
396
+ [MIT](LICENSE)