pi-context-kit 0.3.2 → 0.4.1

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ Pi shows the entries newer than your installed version after `pi update`.
4
+
5
+ ## [0.4.1] - 2026-11-13
6
+
7
+ - The README has a quick start and a troubleshooting section. No change to the extension.
8
+
9
+ ## [0.4.0] - 2026-11-13
10
+
11
+ - The footer shows how full the context is and when cleanup starts, for example `Context 62% · cleanup at 75%`.
12
+ - `/context-kit` opens a panel to turn cleanup on or off, and to choose when and how to clean up.
13
+ - 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.
14
+ - The default threshold is now `75%`. Set `"threshold": "pi"` to wait for Pi's limit as before.
15
+
16
+ ## [0.3.2] - 2026-11-11
17
+
18
+ - Documentation only.
19
+
20
+ ## [0.3.1] - 2026-11-11
21
+
22
+ - Documentation and package metadata only.
23
+
24
+ ## [0.3.0] - 2026-11-11
25
+
26
+ - Breaking: the `staleSuffixTokens` setting is removed. Remove it from your settings.
27
+ - Supports Pi 1.5. Pi 1.0.3 is still the oldest supported version.
28
+ - Requires Node.js 22.19 or later, as Pi does.
29
+ - pi-context-kit edits the context only at the threshold, in one batch, so the provider's prompt cache breaks less often.
30
+ - After a handoff note, shaking runs only when pruning is not enough.
31
+ - With Pi's compaction off, pi-context-kit changes the context only on `/compact`.
32
+ - Background handoff notes are cancelled after session-tree navigation.
33
+
34
+ ## [0.2.1] - 2026-10-06
35
+
36
+ - The README explains each term, the steps of a session, and each setting.
37
+
38
+ ## [0.2.0] - 2026-10-06
39
+
40
+ - Handoff notes use the session's thinking level and tool choice, so Anthropic can reuse the cached conversation.
41
+ - An earlier threshold compacts at the end of a turn, even when no handoff note is ready.
42
+ - Recall regex searches are bounded and can be cancelled.
43
+ - Handoff notes that are truncated, too large or that call a tool are rejected.
44
+ - A failed threshold note is not retried until the next compaction.
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
- # pi-context-kit
1
+ # pi-context-kit: long Pi sessions that stay sharp
2
2
 
3
- [![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)
4
-
5
- **Long Pi sessions that stay sharp.**
3
+ [![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)
4
+ [![npm](https://img.shields.io/npm/v/pi-context-kit)](https://www.npmjs.com/package/pi-context-kit)
5
+ [![Pi package](https://img.shields.io/badge/pi.dev-package-blue)](https://pi.dev/packages/pi-context-kit)
6
+ [![Node.js](https://img.shields.io/node/v/pi-context-kit)](https://nodejs.org)
7
+ [![License: MIT](https://img.shields.io/npm/l/pi-context-kit)](LICENSE)
6
8
 
7
9
  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.
8
10
 
@@ -10,7 +12,7 @@ Pi compaction and context management for the [Pi coding agent](https://github.co
10
12
  pi install npm:pi-context-kit
11
13
  ```
12
14
 
13
- Restart Pi. That is all: the defaults work without configuration. Requirements: Pi 1.0.3 or later, Node.js 22.19 or later.
15
+ Restart Pi. The defaults work without configuration.
14
16
 
15
17
  ## Why pi-context-kit
16
18
 
@@ -19,11 +21,12 @@ Restart Pi. That is all: the defaults work without configuration. Requirements:
19
21
  - **Nothing is deleted.** The session keeps the original text. The model searches and reads it again with the `recall` tool.
20
22
  - **Free where possible.** Replacing old reads, pruning and shaking do not call the model.
21
23
  - **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.
22
- - **Zero setup.** Install, restart, work. Tune it later if you want.
24
+ - **Zero setup.** Install, restart, work. By default, maintenance starts at 75% of the context window, which for most models is before Pi's own limit.
25
+ - **Visible.** The footer shows how full the context is and when cleanup starts. A notice tells you what was freed. Type `/context-kit` to change the main settings in a panel, without editing a file.
23
26
 
24
27
  ## What the model sees
25
28
 
26
- 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)):
29
+ 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 [`strategy`](#main-settings)):
27
30
 
28
31
  ```diff
29
32
  - <first read of src/app.ts, about 5,000 tokens>
@@ -74,45 +77,49 @@ In a long session, the conversation fills the context window. File reads and com
74
77
 
75
78
  </details>
76
79
 
77
- ## Install
80
+ ## Quick start
78
81
 
79
- 1. Open a terminal.
80
- 2. Type this command and press Enter:
82
+ You need Pi 1.0.3 or later and Node.js 22.19 or later.
81
83
 
82
- ```sh
83
- pi install npm:pi-context-kit
84
- ```
84
+ 1. Install the package with the command above.
85
+ 2. Restart Pi.
86
+ 3. Look at the footer. It shows `Context 0% · cleanup at 75%` when the extension is active.
87
+ 4. Work as usual. Type `/context-kit` to change the settings.
85
88
 
86
- 3. Restart Pi.
89
+ ## Update, try or remove
87
90
 
88
- To check the installation, type `pi list`. The list must show `npm:pi-context-kit`.
91
+ ```sh
92
+ pi update npm:pi-context-kit # update, then restart Pi
93
+ pi -e npm:pi-context-kit # try for one session without installing
94
+ pi remove npm:pi-context-kit # remove, then restart Pi
95
+ ```
89
96
 
90
- To update, type `pi update npm:pi-context-kit` and restart Pi.
97
+ After an update, Pi shows what changed, from [CHANGELOG.md](CHANGELOG.md).
91
98
 
92
- To remove it, type `pi remove npm:pi-context-kit` and restart Pi.
99
+ ## Use it
93
100
 
94
- ## Recommended setup
101
+ You do not need to configure anything. pi-context-kit shows its state in Pi's footer:
95
102
 
96
- The default setup works without changes. By default, maintenance starts at the same time as Pi's compaction.
97
- For large context windows, start maintenance earlier. This example starts at 150,000 tokens:
103
+ | Footer | Meaning |
104
+ | --- | --- |
105
+ | `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. |
106
+ | `Context 70% · cleanup at 75% · writing summary` | A handoff note is being written in the background. `summary ready` means that it is ready. |
107
+ | `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. |
108
+ | `Context cleanup off` | You turned automatic cleanup off. |
98
109
 
99
- 1. Open the file `~/.pi/agent/settings.json` in a text editor. `~` is your home folder.
100
- 2. Add the `contextKit` block inside the outer `{ }`. Put a comma between this block and the other settings.
110
+ 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.`
101
111
 
102
- ```json
103
- {
104
- "contextKit": {
105
- "thresholdTokens": 150000
106
- }
107
- }
108
- ```
112
+ 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.
109
113
 
110
- 3. Save the file.
111
- 4. In Pi, type `/reload`, or restart Pi.
114
+ | Panel line | Choices | Setting in the file |
115
+ | --- | --- | --- |
116
+ | Automatic cleanup | On, Off | `enabled` |
117
+ | Clean up when the context is | 50% to 90% full, At Pi's limit | `threshold` |
118
+ | Cleanup method | Summary notes (recommended), Trim first, Pi's summary | `strategy`: `"balanced"`, `"frugal"`, `"pi-summary"` |
112
119
 
113
- If a value is incorrect, Pi shows a warning that starts with `pi-context-kit: invalid settings`. The incorrect value is ignored and its default is used.
120
+ The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method.
114
121
 
115
- 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.
122
+ Outside the interactive mode, `/context-kit` shows the current settings in one line.
116
123
 
117
124
  ## How it works during a session
118
125
 
@@ -134,7 +141,7 @@ To use a setting only in one project, put the same block in the file `.pi/settin
134
141
  |
135
142
  no
136
143
  v
137
- Try each method in "methodOrder": handoff, shake, soft
144
+ Try each method of the strategy, for example: handoff, shake, soft
138
145
  ```
139
146
 
140
147
  ### 1. Old file reads are replaced
@@ -161,7 +168,7 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this
161
168
 
162
169
  ### 4. Other methods, in order
163
170
 
164
- If pruning is not sufficient, pi-context-kit tries the methods in `methodOrder`, one after the other:
171
+ If pruning is not sufficient, pi-context-kit tries the methods of the [strategy](#main-settings), one after the other:
165
172
 
166
173
  | Method | What it does | Uses the model? |
167
174
  | --- | --- | --- |
@@ -195,298 +202,105 @@ Compaction is different: it replaces older context with a summary, including old
195
202
 
196
203
  ## Settings
197
204
 
198
- This section lists every setting. Each setting has its allowed values, its default, and an example.
205
+ This section is for users who edit the settings file. The panel changes the three main settings; the file also has the advanced settings.
199
206
 
200
- ### Where to put the settings
201
-
202
- Put all settings in a `contextKit` block, in one of these files:
207
+ ### The settings files
203
208
 
204
209
  | File | Applies to |
205
210
  | --- | --- |
206
- | `~/.pi/agent/settings.json` | All your projects. `~` is your home folder. |
207
- | `.pi/settings.json` in a project folder | Only this project. These values replace the values of the global file. |
208
-
209
- You do not need to set all settings. A missing setting uses its default.
210
- After a change, type `/reload` in Pi, or restart Pi.
211
+ | `~/.pi/agent/context-kit.json` | All your projects. `~` is your home folder. |
212
+ | `.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. |
211
213
 
212
- ### All settings with their defaults
214
+ 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.
213
215
 
214
- This block sets every setting to its default. It has the same effect as no `contextKit` block.
215
- Copy only the lines that you want to change.
216
+ Add the `$schema` line to get completion and checks in editors such as VS Code:
216
217
 
217
218
  ```json
218
219
  {
219
- "contextKit": {
220
- "enabled": true,
221
- "thresholdTokens": -1,
222
- "thresholdPercent": -1,
223
- "methodOrder": ["handoff", "shake", "soft"],
224
- "asyncEnabled": true,
225
- "supersedeReads": true,
226
- "progressRatio": 0.8,
227
- "prune": {
228
- "enabled": true,
229
- "protectTokens": 40000,
230
- "minSavings": 20000,
231
- "minTokens": 50
232
- },
233
- "shake": {
234
- "protectTokens": 16000,
235
- "minSavings": 4000,
236
- "blockMinTokens": 400
237
- }
238
- }
220
+ "$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json",
221
+ "threshold": "70%",
222
+ "strategy": "frugal"
239
223
  }
240
224
  ```
241
225
 
242
- ### Summary table
226
+ ### Main settings
243
227
 
244
- | Setting | Allowed values | Default | Short description |
228
+ | Setting | Allowed values | Default | What it does |
245
229
  | --- | --- | --- | --- |
246
- | [`enabled`](#enabled) | `true`, `false` | `true` | Turns all maintenance on or off. |
247
- | [`thresholdTokens`](#thresholdtokens) | `-1`, or a whole number above 0 | `-1` | Starts maintenance at this number of tokens. |
248
- | [`thresholdPercent`](#thresholdpercent) | `-1`, or a number above 0, up to 100 | `-1` | Starts maintenance at this percentage of the context window. |
249
- | [`methodOrder`](#methodorder) | A list of `"handoff"`, `"shake"`, `"soft"` | `["handoff", "shake", "soft"]` | The methods to try, and their order. |
250
- | [`asyncEnabled`](#asyncenabled) | `true`, `false` | `true` | Prepares the handoff note in the background. |
251
- | [`supersedeReads`](#supersedereads) | `true`, `false` | `true` | Replaces old copies of a file that was read again. |
252
- | [`progressRatio`](#progressratio) | A number above 0, up to 1 | `0.8` | How small the context must become. |
253
- | [`prune.enabled`](#pruneenabled) | `true`, `false` | `true` | Turns pruning of old tool outputs on or off. |
254
- | [`prune.protectTokens`](#pruneprotecttokens) | A whole number, 0 or more | `40000` | The newest tool outputs that are never pruned. |
255
- | [`prune.minSavings`](#pruneminsavings) | A whole number, 0 or more | `20000` | The minimum gain for pruning. |
256
- | [`prune.minTokens`](#prunemintokens) | A whole number, 0 or more | `50` | Tool outputs smaller than this are never pruned. |
257
- | [`shake.protectTokens`](#shakeprotecttokens) | A whole number, 0 or more | `16000` | The newest context that is never shaken. |
258
- | [`shake.minSavings`](#shakeminsavings) | A whole number, 0 or more | `4000` | The minimum gain for shaking. |
259
- | [`shake.blockMinTokens`](#shakeblockmintokens) | A whole number, 0 or more | `400` | Blocks smaller than this are never shaken. |
260
-
261
- "Whole number" means a number without decimals, for example `150000`. Do not put spaces, dots, or commas in numbers: write `150000`, not `150,000`.
262
-
263
- ### When a setting is incorrect
264
-
265
- 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.
266
-
267
- Example: with `"thresholdTokens": "150000"` (a text in quotes, not a number), Pi shows:
268
-
269
- ```text
270
- pi-context-kit: invalid settings, defaults used (contextKit.thresholdTokens must be -1 or a positive integer).
271
- ```
230
+ | `enabled` | `true`, `false` | `true` | `false` stops all maintenance and handoff notes. The `recall` tool stays available. |
231
+ | `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"` | Where maintenance starts. |
232
+ | `strategy` | `"balanced"`, `"frugal"`, `"pi-summary"` | `"balanced"` | What pi-context-kit does when pruning is not sufficient. |
272
233
 
273
- A setting name with a spelling mistake also shows a warning, for example `contextKit.treshold is not a setting`.
234
+ **`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).
274
235
 
275
- ### `enabled`
236
+ **`strategy`.**
276
237
 
277
- Turns all maintenance on or off.
278
-
279
- - `true` (default): pi-context-kit works as described in this document.
280
- - `false`: pi-context-kit does nothing. Pi uses only its own summary. The `recall` tool stays available.
281
-
282
- ```json
283
- { "contextKit": { "enabled": false } }
284
- ```
285
-
286
- ### `thresholdTokens`
287
-
288
- Maintenance starts when the context is larger than this number of tokens.
289
-
290
- - `-1` (default): use `thresholdPercent`. If `thresholdPercent` is also `-1`, use Pi's limit.
291
- - A whole number above 0: start at this number of tokens.
292
-
293
- This setting has priority over `thresholdPercent`.
294
- pi-context-kit can start before Pi's limit, never after. If your value is larger than Pi's limit, Pi's limit is used. See [Pi settings that also apply](#pi-settings-that-also-apply).
295
-
296
- Example: start at 150,000 tokens.
297
-
298
- ```json
299
- { "contextKit": { "thresholdTokens": 150000 } }
300
- ```
301
-
302
- | Model context window | Pi's limit (default reserve) | Threshold used |
238
+ | Strategy (panel name) | Above the threshold, after pruning | Background requests |
303
239
  | --- | --- | --- |
304
- | 1,000,000 | 983,616 | 150,000 |
305
- | 200,000 | 183,616 | 150,000 |
306
- | 128,000 | 111,616 | 111,616 (Pi's limit is smaller) |
240
+ | `"balanced"` (Summary notes) | A handoff note. If the note fails, shake. Then Pi's summary. | Yes: the note is written before the threshold. |
241
+ | `"frugal"` (Trim first) | Shake, because it does not call the model. If that is not sufficient, a handoff note. Then Pi's summary. | No |
242
+ | `"pi-summary"` (Pi's summary) | Pi's summary. No handoff note, no shaking. | No |
307
243
 
308
- ### `thresholdPercent`
244
+ ### Advanced settings
309
245
 
310
- Maintenance starts when the context is larger than this percentage of the model's context window.
311
-
312
- - `-1` (default): no percentage. If `thresholdTokens` is also `-1`, use Pi's limit.
313
- - A number above 0, up to 100: start at this percentage. Decimals are allowed, for example `72.5`. Values above 99 are used as 99.
314
-
315
- pi-context-kit ignores this setting when `thresholdTokens` is not `-1`.
316
-
317
- Example: start at 75% of the context window.
246
+ Put these settings in an `advanced` block. Most users never need them.
318
247
 
319
248
  ```json
320
- { "contextKit": { "thresholdPercent": 75 } }
249
+ {
250
+ "advanced": {
251
+ "methodOrder": ["handoff", "shake", "soft"],
252
+ "background": true,
253
+ "supersedeReads": true,
254
+ "progressRatio": 0.8,
255
+ "prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 },
256
+ "shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 }
257
+ }
258
+ }
321
259
  ```
322
260
 
323
- | Model context window | Threshold used |
324
- | --- | --- |
325
- | 1,000,000 | 750,000 |
326
- | 200,000 | 150,000 |
327
- | 128,000 | 96,000 |
328
-
329
- Use `thresholdPercent` if you use models with different context windows and you want the same proportion for all of them. Use `thresholdTokens` if you want the same number for all of them.
330
-
331
- ### `methodOrder`
332
-
333
- The methods that pi-context-kit tries when pruning is not sufficient, in this order.
334
-
335
- Allowed values in the list:
336
-
337
- | Value | What it does | Calls the model? |
261
+ | Setting | Default | What it does |
338
262
  | --- | --- | --- |
339
- | `"handoff"` | Replaces the old conversation with a handoff note. The newest messages stay. | Yes, the session model |
340
- | `"shake"` | Replaces large old code blocks, XML blocks, and images with a short notice. | No |
341
- | `"soft"` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops the list. | Yes, the session model |
342
- | `"remote"`, `"snapcompact"` | Accepted for oh-my-pi compatibility, but skipped. Pi does not have these methods. | No |
343
-
344
- Rules:
345
-
346
- - The order is important. pi-context-kit tries the first method, then the next one.
347
- - `"soft"` ends the list. Methods after `"soft"` never run.
348
- - If `"handoff"` is not in the list before `"soft"`, pi-context-kit writes no handoff note at all. This also applies to `/compact` and to background notes. Pi writes its own summary.
349
- - If `"shake"` is not in the list before `"soft"`, nothing is shaken.
350
- - A value that appears two times is used one time.
351
- - An empty list `[]` is allowed. Then pi-context-kit only replaces old file reads and prunes old tool outputs.
352
-
353
- Common choices:
354
-
355
- | `methodOrder` | What happens above the threshold |
356
- | --- | --- |
357
- | `["handoff", "shake", "soft"]` (default) | Prune. Then a handoff note. If the note fails, shake. Then Pi's summary. |
358
- | `["shake", "handoff", "soft"]` | Prune and shake together. If that is not sufficient, a handoff note. Then Pi's summary. |
359
- | `["handoff", "soft"]` | Prune. Then a handoff note. Never shake. |
360
- | `["shake", "soft"]` | Prune and shake. Then Pi's summary. No handoff note. |
361
- | `["soft"]` | Prune. Then Pi's summary. |
362
- | `[]` | Prune only. Pi writes its summary when the context reaches Pi's limit. |
363
-
364
- Example: try shaking first, because it does not call the model.
263
+ | `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. |
264
+ | `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. |
265
+ | `supersedeReads` | `true` | Replaces the old copy of a file that the model read again. |
266
+ | `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. |
267
+ | `prune.enabled` | `true` | `false` never prunes tool outputs. |
268
+ | `prune.protectTokens` | `40000` | The newest tool outputs, up to this number of tokens, are never pruned. |
269
+ | `prune.minSavings` | `20000` | Pruning occurs only if it removes at least this number of tokens. |
270
+ | `prune.minTokens` | `50` | Tool outputs smaller than this are never pruned. |
271
+ | `shake.protectTokens` | `16000` | The newest context, up to this number of tokens, is never shaken. Your own messages are never shaken. |
272
+ | `shake.minSavings` | `4000` | Shaking occurs only if it removes at least this number of tokens. |
273
+ | `shake.blockMinTokens` | `400` | Code and XML blocks smaller than this are never shaken. |
365
274
 
366
- ```json
367
- { "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }
368
- ```
369
-
370
- ### `asyncEnabled`
371
-
372
- Prepares the handoff note in the background, before the threshold.
373
-
374
- - `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens. If the note is ready at the threshold, compaction is fast.
375
- - `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note.
376
-
377
- This setting has an effect only if `"handoff"` is in `methodOrder` before `"soft"`.
378
-
379
- Example: no background requests.
380
-
381
- ```json
382
- { "contextKit": { "asyncEnabled": false } }
383
- ```
384
-
385
- ### `supersedeReads`
386
-
387
- Replaces the old copy of a file when the model reads the same file again.
388
-
389
- - `true` (default): the old copy becomes `[Superseded by a newer read of this file]`.
390
- - `false`: all copies stay.
391
-
392
- This works only above the threshold, together with pruning and shaking.
393
-
394
- ```json
395
- { "contextKit": { "supersedeReads": false } }
396
- ```
397
-
398
- ### `progressRatio`
399
-
400
- How small the context must become after a method, as a fraction of the threshold.
401
- If a method cannot make the context this small, pi-context-kit does not use its result and tries the next method.
402
-
403
- - `0.8` (default): the context must become 80% of the threshold or less. With a threshold of 150,000 tokens, this is 120,000 tokens.
404
- - A smaller value, for example `0.6`, gives more free space after maintenance. But each method must remove more, so it fails more often.
405
- - A larger value, for example `0.95`, makes each method succeed more easily. But maintenance can start again soon after.
406
-
407
- The value must be above 0 and not more than 1.
408
-
409
- ```json
410
- { "contextKit": { "progressRatio": 0.7 } }
411
- ```
412
-
413
- ### `prune.enabled`
414
-
415
- Turns pruning on or off. Pruning replaces old tool outputs with a notice, for example `[Output pruned: about 5000 tokens. Call recall with entryId "abc123" to read it.]`.
416
-
417
- - `true` (default).
418
- - `false`: tool outputs are never pruned.
419
-
420
- ```json
421
- { "contextKit": { "prune": { "enabled": false } } }
422
- ```
423
-
424
- ### `prune.protectTokens`
425
-
426
- The newest tool outputs, up to this number of tokens, are never pruned. Thus the model keeps its most recent results.
427
-
428
- - `40000` (default).
429
- - A larger value keeps more recent outputs, but removes less.
430
-
431
- ```json
432
- { "contextKit": { "prune": { "protectTokens": 60000 } } }
433
- ```
434
-
435
- ### `prune.minSavings`
436
-
437
- Pruning occurs only if it removes at least this number of tokens. This prevents small changes with little gain.
438
-
439
- - `20000` (default).
440
-
441
- ```json
442
- { "contextKit": { "prune": { "minSavings": 10000 } } }
443
- ```
444
-
445
- ### `prune.minTokens`
446
-
447
- Tool outputs smaller than this number of tokens are never pruned. A notice would not be much smaller than these outputs.
448
-
449
- - `50` (default).
450
-
451
- ```json
452
- { "contextKit": { "prune": { "minTokens": 200 } } }
453
- ```
454
-
455
- ### `shake.protectTokens`
456
-
457
- The newest part of the context, up to this number of tokens, is never shaken. Your own messages are never shaken, also when they are old.
458
-
459
- - `16000` (default).
460
-
461
- ```json
462
- { "contextKit": { "shake": { "protectTokens": 32000 } } }
463
- ```
464
-
465
- ### `shake.minSavings`
466
-
467
- Shaking occurs only if it removes at least this number of tokens.
275
+ ### When a setting is incorrect
468
276
 
469
- - `4000` (default).
277
+ 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:
470
278
 
471
- ```json
472
- { "contextKit": { "shake": { "minSavings": 8000 } } }
279
+ ```text
280
+ 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.
473
281
  ```
474
282
 
475
- ### `shake.blockMinTokens`
283
+ 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.
476
284
 
477
- Code blocks and XML blocks smaller than this number of tokens are never shaken.
285
+ ### Upgrade from 0.3
478
286
 
479
- - `400` (default).
287
+ 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.
480
288
 
481
- ```json
482
- { "contextKit": { "shake": { "blockMinTokens": 1000 } } }
483
- ```
484
-
485
- There is no `shake.enabled` setting. To stop shaking, remove `"shake"` from `methodOrder`.
289
+ | 0.3 (`contextKit` in `settings.json`) | 0.4 (`context-kit.json`) |
290
+ | --- | --- |
291
+ | `thresholdTokens: 150000` | `threshold: 150000` |
292
+ | `thresholdPercent: 75` | `threshold: "75%"` |
293
+ | Both `thresholdTokens` and `thresholdPercent` | `threshold` with the number of tokens |
294
+ | No threshold (Pi's limit) | `threshold: "pi"`. The default for new users is `"75%"`. |
295
+ | `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`, with `advanced.background: true` unless `asyncEnabled` was `false` |
296
+ | `methodOrder: ["soft"]` | `strategy: "pi-summary"` |
297
+ | 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. |
298
+ | `asyncEnabled` | `advanced.background`, when it differs from the strategy |
299
+ | `supersedeReads`, `progressRatio`, `prune`, `shake` | The same names in `advanced` |
486
300
 
487
301
  ### Pi settings that also apply
488
302
 
489
- These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block, next to the `contextKit` block.
303
+ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block of Pi's `settings.json`.
490
304
 
491
305
  | Pi setting | Default | Effect on pi-context-kit |
492
306
  | --- | --- | --- |
@@ -495,61 +309,41 @@ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction`
495
309
  | `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. |
496
310
  | `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. |
497
311
 
498
- 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`. pi-context-kit always starts at Pi's limit or before, so it also starts earlier for this model.
499
-
500
- Example: all models start at 150,000 tokens. One model with a 200,000-token window starts at 200,000 − 80,000 = 120,000 tokens. Replace `provider/model-id` with the ID of your model.
501
-
502
- ```json
503
- {
504
- "compaction": {
505
- "modelOverrides": {
506
- "provider/model-id": { "reserveTokens": 80000 }
507
- }
508
- },
509
- "contextKit": {
510
- "thresholdTokens": 150000
511
- }
512
- }
513
- ```
514
-
515
- Pi also uses `reserveTokens` to limit the length of its own summary. See the Pi documentation about compaction.
516
-
517
- The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`.
312
+ 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`.
518
313
 
519
314
  ## Recipes
520
315
 
521
- | I want to... | Settings |
316
+ | I want to... | `context-kit.json` |
522
317
  | --- | --- |
523
- | Start earlier with large models | `{ "contextKit": { "thresholdTokens": 150000 } }` |
524
- | Use the same proportion for all models | `{ "contextKit": { "thresholdPercent": 75 } }` |
525
- | Never write a handoff note | `{ "contextKit": { "methodOrder": ["shake", "soft"] } }` |
526
- | Try the free method first, then a handoff note | `{ "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }` |
527
- | Keep more recent tool outputs | `{ "contextKit": { "prune": { "protectTokens": 80000 } } }` |
528
- | Keep all old file copies | `{ "contextKit": { "supersedeReads": false } }` |
529
- | Use other settings in one project | Put the `contextKit` block in `.pi/settings.json` in that project. |
530
- | Turn pi-context-kit off, but keep `recall` | `{ "contextKit": { "enabled": false } }` |
531
-
532
- To combine recipes, put all the settings in one `contextKit` block:
533
-
534
- ```json
535
- {
536
- "contextKit": {
537
- "thresholdTokens": 150000,
538
- "methodOrder": ["shake", "handoff", "soft"],
539
- "prune": { "protectTokens": 80000 }
540
- }
541
- }
542
- ```
318
+ | Start later, at Pi's own limit | `{ "threshold": "pi" }` |
319
+ | Start at the same number of tokens on all models | `{ "threshold": 150000 }` |
320
+ | Avoid model requests when possible | `{ "strategy": "frugal" }` |
321
+ | Never write a handoff note | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` |
322
+ | Keep more recent tool outputs | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` |
323
+ | Keep all old file copies | `{ "advanced": { "supersedeReads": false } }` |
324
+ | Turn pi-context-kit off, but keep `recall` | `{ "enabled": false }`, or `/context-kit` |
543
325
 
544
326
  ## Limits
545
327
 
546
328
  - **Pi still has its own limit.** Pi compacts when the context reaches the context window minus `compaction.reserveTokens` (default 16,384). pi-context-kit can only start earlier, not later. You set Pi's limit with `compaction.reserveTokens` and `compaction.modelOverrides`.
547
329
  - **A threshold is not a guarantee.** At the threshold, pi-context-kit tries to make the context smaller. If one tool output is very large, or the summary request fails, the methods can fail. Then Pi compacts at its own limit.
548
330
  - **Token counts are estimates.** pi-context-kit uses Pi's estimates. The real count of the provider can be different.
549
- - **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. `thresholdTokens` and `thresholdPercent` are ignored, because pi-context-kit edits the context automatically only at a threshold.
331
+ - **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.
550
332
  - **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.
551
- - **`methodOrder` stops at `soft`.** The methods after `soft` do not run.
552
- - **Subagents** use their own settings. They show no warnings, because they have no screen.
333
+ - **The method order stops at `soft`.** The methods after `soft` do not run.
334
+ - **Subagents** read the same settings files. They show no warnings and no status, because they have no screen.
335
+
336
+ ## Troubleshooting
337
+
338
+ **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.
339
+
340
+ **`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.
341
+
342
+ **`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`.
343
+
344
+ **`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.
345
+
346
+ **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.
553
347
 
554
348
  ## FAQ
555
349