3 -Pi context blowup fuse for oversized `bash` output.
3 +Compacts oversized Pi `read` results before they hit context.
7 +Loaded through the root `pi-ext` package. See [../../README.md](../../README.md).
9 +##
Commands / tools / settings 17 +- `tool_result`: watches builtin `read` results and may replace large full-file reads with a bounded head/tail view.
24 +PI_CTX_COMPACT_THRESHOLD=20000
25 +PI_CTX_READ_OUTPUT_THRESHOLD=20000
28 +`PI_CTX_COMPACT_THRESHOLD` wins if both are set.
5 32 `ctx` does one thing:
7 -1. watches `bash` tool results
8 -2. if output is too large, stores full text off-context in SQLite FTS
9 -3. replaces visible output with a small `ctx:stored ...` pointer
10 -4. exposes `ctx` search for that stored output
34 +1. watches `read` tool results
35 +2. ignores errors and bounded reads with `limit`
36 +3. if full read output exceeds the threshold, returns:
38 + - `[ctx compacted read: ...]` marker
39 + - grep/read-offset instruction
41 +4. leaves `bash`, `grep`, `find`, `ls`, and all other tools untouched
12 -It does **not** run shell/JS/Python jobs. It does **not** inspect files. Use normal Pi tools for normal work.
43 +No SQLite. No search tool. No replacement tools. No workspace writes.
45 +Agents can recover hidden middle content with normal builtin tools:
49 +read path offset=120 limit=40
18 -Search output previously stored by ctx:
22 - "query":
"TARGET_EVENT",
23 - "source":
"bash:178810b1:42",
55 +{
"ctxCompactedRead":
true }
28 -Range-read known lines, like `read`:
32 - "source":
"bash:178810b1:42",
38 -Use the exact `source` label from `ctx:stored`.
45 -PI_CTX_LARGE_OUTPUT_THRESHOLD=20000
46 -PI_CTX_ERROR_OUTPUT_THRESHOLD=5000
51 -- successful `bash` output > 20KB → stored
52 -- failed `bash` output > 5KB → stored + error-oriented preview
53 -- smaller output → unchanged
60 -${XDG_STATE_HOME:-~/.local/state}/pi/ctx/<session-file-basename>-<sha256(abs-cwd)[0..16]>.db
66 -Linux: ${XDG_STATE_HOME:-~/.local/state}/pi/ctx/
67 -macOS: ~/Library/Application Support/pi/ctx/
68 -Windows:%LOCALAPPDATA%\\pi\\ctx\\
71 -`ctx` still requires the active Pi session file, but only to derive the session id. It does not store under `sessionManager.getSessionDir()`, because that can mix unrelated session runtime data.
73 -Override for tests/debug:
76 -PI_CTX_DB_PATH
=/tmp/ctx.db 79 -In benchmark runs this is inside sandbox HOME:
82 -/home/bench/.local/state/pi/ctx/<session-id>-<cwd-hash>.db
87 -- `sources` table: labels, byte counts, metadata
88 -- `chunks_fts` FTS5 table: chunked searchable output
94 -→ ctx:stored bash:178810b1:42 (2085.9KB, 135 chunks).
95 - Stored output is not in the workspace. Call the ctx tool with {"query":"...","source":"bash:178810b1:42"}.
97 -ctx {"query":"TARGET_EVENT","source":"bash:178810b1:42"}
98 -→ matching snippets only
100 -ctx {"source":"bash:178810b1:42","offset":201,"limit":200}
61 +