{"_id":"@arter/pi-auto-compact-percent","name":"@arter/pi-auto-compact-percent","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@arter/pi-auto-compact-percent","version":"1.0.0","description":"Pi extension: live context-usage bar + debounced auto-compaction at a configurable threshold.","type":"module","keywords":["pi-package","pi","extension","compaction","context"],"license":"MIT","publishConfig":{"access":"public"},"main":"index.ts","scripts":{"test":"node --experimental-test-module-mocks --test test/**/*.test.ts","test:coverage":"node --experimental-test-module-mocks --experimental-test-coverage --test test/**/*.test.ts","lint":"biome check index.ts test/index.test.ts","lint:fix":"biome check --write index.ts test/index.test.ts","format":"biome format --write index.ts test/index.test.ts"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"pi":{"extensions":["./index.ts"],"image":"https://raw.githubusercontent.com/christopherarter/pi-auto-compact-percent/main/autocompact.png"},"devDependencies":{"@biomejs/biome":"^2.5.6","@earendil-works/pi-coding-agent":"^0.83.0","typescript":"^5.9.3"},"gitHead":"bf0547306b1aa3c2cd005ffd9c1bde009f323e45","_id":"@arter/pi-auto-compact-percent@1.0.0","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-JUlHAtx4SrvlgJGcWAXkeeerVRZNLIO4IjjUN8zNM/uijzUTxmud1y2rpH+OWzcKFwjXrOANjYYcz0NG5f/IaA==","shasum":"a5a4e032c36de98b51cd0cacf039555852fd090e","tarball":"https://registry.npmjs.org/@arter/pi-auto-compact-percent/-/pi-auto-compact-percent-1.0.0.tgz","fileCount":4,"unpackedSize":75226,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDrx+e0i7btvu/hOkodU/IRQMlzDkbjJVZAali5dsu0QAiEAyGo/yBI0T0hITmSJW2pUVL/JR+zkZ2IyXNftd/psLCU="}]},"_npmUser":{"name":"chrisarter","email":"christopherarter@gmail.com"},"directories":{},"maintainers":[{"name":"chrisarter","email":"christopherarter@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-auto-compact-percent_1.0.0_1785812198693_0.44947861763447494"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-04T02:56:38.453Z","1.0.0":"2026-08-04T02:56:38.822Z","modified":"2026-08-04T02:56:39.114Z"},"maintainers":[{"name":"chrisarter","email":"christopherarter@gmail.com"}],"description":"Pi extension: live context-usage bar + debounced auto-compaction at a configurable threshold.","keywords":["pi-package","pi","extension","compaction","context"],"license":"MIT","readme":"# auto-compact-percent\n\n<img src=\"autocompact.png\" alt=\"auto-compact-percent status bar\" width=\"700\" style=\"max-width:100%;height:auto;\">\n\n---\n\nPi extension that shows a **live context-usage bar** in the status line and\n**auto-compacts early** — either at a configurable percentage of the context\nwindow, or when the real input token count (including the system prompt)\nreaches a fixed threshold.\n\nUnlike pi's native compaction (which fires near the model limit, based on\nreserved response tokens), this lets you compact _early_ at any percentage you\nchoose, or at a specific token count, with a visible countdown bar.\n\n## What it does\n\n- **Context bar**: after every turn, renders a bar in the pi status line using\n  the **real total input** from the last assistant response:\n  `[█████░░░░░ 14%] 27k/200k`\n  - Both the bar % and the `27k/200k` suffix reflect **everything the model\n    actually has in context**: system prompt + tools + conversation + cached\n    tokens (`usage.input + cacheRead + cacheWrite`, same as pi's own \"Input\"\n    accounting).\n  - Before the first response it shows a chars/4 estimate of just the system\n    prompt, so the bar is never a misleading `0/1M`.\n  - After compaction the total is reset (it's stale) and the bar falls back to\n    the system-prompt floor until the next response reports fresh usage.\n- **Trigger marker**: once usage passes the threshold, appends `trigger` to\n  the bar so you can see it's about to compact.\n- **Auto-compaction**: when either trigger fires (see below) and the debounce\n  window has passed, calls `ctx.compact()` with instructions focused on the\n  most recent work. Shows a `compacting` bar and notifies on start/complete.\n- **Two triggers**: compacts when the real total reaches `threshold` fraction\n  of the context window, OR when the real total token count reaches\n  `maxTokens` (whichever comes first). The threshold is now measured on the\n  REAL total (system prompt + cache included), so at 40% you're compacting\n  when the model's context is actually 40% full — not 40% of conversation.\n- **Debounce**: skips compaction if fewer than `debounceTurns` turns have\n  passed since the last one (or since session start), so a burst of activity\n  doesn't trigger compaction repeatedly.\n- **Eligibility check**: skips compaction when context usage is below\n  `minTokens`, so a short session with nothing old to summarize isn't\n  compacted wastefully.\n\n## Commands\n\n| Command                                  | Purpose                                                                              |\n| ---------------------------------------- | ------------------------------------------------------------------------------------ |\n| `/auto-compact`                          | Toggle auto-compaction for the current session (in-memory only; resets on `/reload`) |\n| `/auto-compact on` / `/auto-compact off` | Enable or disable explicitly                                                         |\n\nThe toggle is session-scoped and never writes to your settings files.\n\n## Install\n\n### As a pi package (from git)\n\n```bash\npi install git:github.com/christopherarter/pi-auto-compact-percent\n```\n\n> npm publishing is planned; until then install from git above.\n\n### Manual (local copy)\n\nPi auto-discovers extensions in `~/.pi/agent/extensions/`:\n\n```bash\nmkdir -p ~/.pi/agent/extensions/auto-compact-percent\ncp index.ts README.md ~/.pi/agent/extensions/auto-compact-percent/\n```\n\nThen reload pi (`/reload`) or restart. Loads from\n`~/.pi/agent/extensions/auto-compact-percent/index.ts`.\n\n## Configuration\n\nConfigure via `autoCompactPct` in either:\n\n- `~/.pi/agent/settings.json` (global, all projects)\n- `.pi/settings.json` in the current project (project override, wins)\n\n| Key                      | Default                                                              | Description                                                                                 |\n| ------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `threshold`              | `0.4`                                                                | Fraction (0–1) of context window (REAL total, incl. system prompt) that triggers compaction |\n| `maxTokens`              | `0`                                                                  | Compact when real input tokens (incl. system prompt + cache) reach this. `0` disables       |\n| `minContextWindow`       | `32000`                                                              | Don't auto-compact if the model's context window is smaller than this                       |\n| `minTokens`              | `8000`                                                               | Don't auto-compact if context usage is below this (nothing old to summarize)                |\n| `debounceTurns`          | `5`                                                                  | Minimum turns between compaction attempts                                                   |\n| `barWidth`               | `20`                                                                 | Width of the rendered progress bar in characters                                            |\n| `compactionInstructions` | `\"Focus on the most recent work, decisions, and in-progress tasks.\"` | Custom instructions passed to `ctx.compact()`                                               |\n\nExample:\n\n```json\n{\n  \"autoCompactPct\": {\n    \"threshold\": 0.5,\n    \"maxTokens\": 200000,\n    \"minContextWindow\": 64000,\n    \"minTokens\": 10000,\n    \"debounceTurns\": 3,\n    \"barWidth\": 30,\n    \"compactionInstructions\": \"Preserve unfinished work and exact details required to resume safely.\"\n  }\n}\n```\n\nInvalid values (threshold out of range, negative numbers, tiny bar widths)\nfall back to defaults.\n\n## Development\n\nSingle-file extension + `node:test` suite. To package for npm:\n\n```bash\nnpm test        # run the 26-test suite (node --test + module mocks)\nnpm pack        # verify tarball contents\nnpm publish     # requires \"pi-package\" keyword (already set)\n```\n\nDependencies: only the pi core package (`@earendil-works/pi-coding-agent`),\nlisted as a peer dependency — pi bundles it at runtime, so no install needed.\n\n## Behavior notes\n\n- The bar is always rendered (even below threshold) while enabled; compaction\n  only fires when a trigger is reached.\n- The bar's `%` and the `27k/200k` suffix are both the **real total** from the\n  last assistant response (`usage.input + cacheRead + cacheWrite`, same as\n  pi's own \"Input\" accounting) — the accurate measure of window pressure,\n  system prompt included. At session start, before the first response, both\n  show a chars/4 estimate of the system prompt so it's not `0`. If `maxTokens`\n  is set, it compares against this real total.\n- Compaction respects pi's own `compaction.enabled` setting — if compaction\n  is disabled globally this extension's `ctx.compact()` may be a no-op.\n- On compaction failure the bar clears and compaction stays disarmed until\n  usage drops back below the threshold, so a broken compaction can't cause a\n  retry loop.\n- The `/auto-compact` toggle is in-memory: it survives `turn_end` calls but\n  resets to enabled on `/reload` or restart. It never modifies settings files.\n- No background resources are started from the factory; all work happens on\n  `session_start` and `turn_end` events.\n- UI calls (`notify`) are guarded with `ctx.hasUI` so it degrades gracefully\n  in print/JSON modes.\n\n## Similar packages\n\n- [`@thunstack/auto-compact`](https://github.com/aashishd/pi-auto-compact-plugin)\n  — percentage-based auto-compaction with a `/auto-compact` toggle and TUI\n  config panel, but no live context bar.\n- [`pi-powerline-footer`](https://github.com/nicobailon/pi-powerline-footer)\n  — shows context as text (`12k/200k (6.2%)` or `83%`) but doesn't\n  auto-compact and has no progress bar.\n\nThis package combines the live visual bar with early percentage-based\ncompaction, plus a real-token (`maxTokens`) trigger for a tight, window-\nindependent leash.\n","readmeFilename":"README.md","_rev":"1-c229cf730fa4a2fc93a7706cfcd698bd"}