repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: format markdown

3c038369741e7c27ef9ed2e7441c5f740052d906

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (20)

README.md

Modified
1 1 # pi-ext
3 -Personal Pi extension pack: tools, footers, shell bridges, workflow hacks,
4 -small demons.
3 +Personal Pi extension pack:
4 +tools, footers, shell bridges, workflow hacks, small demons.
6 6 ## Install

TMUX_AGENT_WORKFLOWS.md

Modified
6 6 ## Use Cases
8 -- Real interactive testing: exercise actual terminal UI, not mocks.
9 -- Long-running workflows: let agents, builds, servers, or model calls run while
10 - you inspect from outside.
11 -- Input timing tests: send input while a process is busy, idle, paused, or
12 - waiting.
13 -- UI verification: capture status bars, widgets, spinners, prompts, and
14 - wrapped text.
15 -- Repro sandboxes: run each scenario in a fresh cwd/session dir.
16 -- Debug artifacts: preserve logs, transcripts, temp files, and captured pane output.
17 -- Remote work: keep sessions alive across SSH disconnects.
18 -- Multi-process orchestration: agent pane + server pane + logs pane + watcher pane.
8 +- Real interactive testing:
9 + exercise actual terminal UI, not mocks.
10 +- Long-running workflows:
11 + let agents, builds, servers, or model calls run while you inspect from
12 + outside.
13 +- Input timing tests:
14 + send input while a process is busy, idle, paused, or waiting.
15 +- UI verification:
16 + capture status bars, widgets, spinners, prompts, and wrapped text.
17 +- Repro sandboxes:
18 + run each scenario in a fresh cwd/session dir.
19 +- Debug artifacts:
20 + preserve logs, transcripts, temp files, and captured pane output.
21 +- Remote work:
22 + keep sessions alive across SSH disconnects.
23 +- Multi-process orchestration:
24 + agent pane + server pane + logs pane + watcher pane.
20 26 ## Pros
22 28 - Tests real behavior end-to-end.
23 29 - Works with any terminal app.
24 -- Non-blocking: launch, poll, inspect, continue.
30 +- Non-blocking:
31 + launch, poll, inspect, continue.
25 32 - Scriptable enough for smoke tests.
26 33 - Great for reproducing bugs found only in interactive mode.
27 -- Keeps visible history while also allowing machine-readable session/log inspection.
34 +- Keeps visible history while also allowing machine-readable session/log
35 + inspection.
29 37 ## Cons
31 39 - Timing can be brittle; sleeps and polling are imperfect.
32 40 - Pane output may wrap, truncate, or include ANSI/control artifacts.
33 41 - Assertions are weaker than structured APIs.
34 -- Cleanup matters: stale tmux sessions and temp dirs cause false results.
42 +- Cleanup matters:
43 + stale tmux sessions and temp dirs cause false results.
35 44 - Real providers/network/LLMs add cost, latency, and nondeterminism.
36 45 - Terminal dimensions affect rendering.
99 -- Use fixed pane size: `-x 120 -y 40`.
100 -- Capture enough scrollback: `-S -200` or more.
108 +- Use fixed pane size:
109 + `-x 120 -y 40`.
110 +- Capture enough scrollback:
111 + `-S -200` or more.
101 112 - Prefer checking stable text, not exact whole-screen snapshots.
102 113 - For wrapping/color bugs, inspect both pane output and screenshots if needed.
155 166 Useful layouts:
157 -- Left: agent/TUI
158 -- Right top: logs
159 -- Right bottom: filesystem/session watcher
168 +- Left:
169 + agent/TUI
170 +- Right top:
171 + logs
172 +- Right bottom:
173 + filesystem/session watcher
161 175 ## Cleanup
165 179 rm -rf "$work"
168 -For debugging, do not delete immediately. Print paths instead:
182 +For debugging, do not delete immediately.
183 +Print paths instead:
170 185 ```bash
171 186 echo "tmux attach -t $name"
191 206 - Input pasted while app uses alternate screen/editor mode → use `send-keys` or
192 207 paste buffer carefully.
193 208 - Output wraps differently → fix pane dimensions.
194 -- Grep matches old scrollback → use unique markers or clear pane before scenario.
209 +- Grep matches old scrollback → use unique markers or clear pane before
210 + scenario.
195 211 - Stale session reused → kill session and reset workdir.
196 212 - App still running when assertions start → poll for a completion marker.

extensions/angel/README.md

Modified
12 12 ## Install / load
14 14 Angel is loaded through the root `pi-ext` package.
15 -See [root README](../../README.md).
15 +See [root README](../../README.md).
17 17 ## Commands / tools / settings
138 138 1. Executor attempts selected dangerous `bash`:
139 139 `sudo`, `rm -rf`, `git push`, `npm publish`, `pnpm publish`, `bun publish`,
140 - recursive `chmod`/`chown`, `dd if=`/`dd of=`, `mkfs`, `curl|sh`,
141 - `curl|bash`, `wget|sh`, `wget|bash`, or fork bomb syntax.
140 + recursive `chmod`/`chown`, `dd if=`/`dd of=`, `mkfs`, `curl|sh`, `curl|bash`,
141 + `wget|sh`, `wget|bash`, or fork bomb syntax.
142 142 2. Angel blocks that exact command once.
143 143 3. Angel consults the advisor and returns formatted advice in the block reason.
144 144 4. Executor may retry the same command if still correct.

extensions/builtin-tools/README.md

Modified
5 5 ## Install / load
7 7 Loaded through root pi-ext package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings
32 32 `/builtin-tools` checks registered tools, then toggles available built-ins:
34 -- if all are active: disables them
35 -- otherwise: enables them
34 +- if all are active:
35 + disables them
36 +- otherwise:
37 + enables them
37 39 UI notifications report changed tools.
38 40 If no target tools are registered, the command reports that.

extensions/context-size/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root `pi-ext` package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings
45 45 Usage color:
47 -- `< 70%`: muted
48 -- `≥ 70%`: warning
49 -- `≥ 85%`: error
50 -- unknown percent: muted
47 +- `< 70%`:
48 + muted
49 +- `≥ 70%`:
50 + warning
51 +- `≥ 85%`:
52 + error
53 +- unknown percent:
54 + muted
52 56 No UI update runs when UI is unavailable.

extensions/cost/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root `pi-ext` package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings

extensions/cwd/README.md

Modified
5 5 ## Install / load
7 7 This extension is loaded through the root pi-ext package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings

extensions/devil/README.md

Modified
6 6 ## Install / load
8 8 Loaded through the root pi-ext package.
9 -See [root README](../../README.md).
9 +See [root README](../../README.md).
11 11 ## Commands / tools / settings
24 24 Commands:
26 26 - `/devil <idea>` — start an interactive debate.
27 -- `/devil` — reports `Usage: /devil <your idea>`.
27 +- `/devil` — reports `Usage:
28 + /devil <your idea>`.
29 30 Registered flags:

extensions/diff-review/README.md

Modified
13 13 ## Install / load
15 15 Loaded through the root pi-ext package.
16 -See [root README](../../README.md).
16 +See [root README](../../README.md).
18 18 ## Commands / tools / settings
22 22 - `/diff-review`
23 23 - `/diff-review --staged`
24 24 - `/diff-review --base <ref>` or `/diff-review --base=<ref>`
25 -- `/diff-review --files <path[,path...]>` or `/diff-review --files=<path[,path...]>`
25 +- `/diff-review --files <path[,path...]>` or `/diff-review
26 + --files=<path[,path...]>`
26 27 - `/diff-review-cancel`
28 29 Tools:

extensions/fast/README.md

Modified
10 10 ## Commands / tools / settings
12 -Commands: none.
12 +Commands:
13 +none.
14 -Tools: none.
15 +Tools:
16 +none.
16 18 Hooks:
18 -- `session_start`: refreshes settings from the session cwd.
19 -- `model_select`: refreshes settings from the session cwd.
20 +- `session_start`:
21 + refreshes settings from the session cwd.
22 +- `model_select`:
23 + refreshes settings from the session cwd.
21 25 Settings:
31 -`fast.enable` is a boolean. Project settings override global settings.
32 -Default: disabled.
35 +`fast.enable` is a boolean.
36 +Project settings override global settings.
37 +Default:
38 +disabled.
34 40 ## Behavior
36 42 Registers provider `openai-codex` with API `openai-codex-responses`.
38 -When enabled, wraps `openai-codex` streaming and sends native
39 -`serviceTier: "priority"`.
44 +When enabled, wraps `openai-codex` streaming and sends native `serviceTier:
45 +"priority"`.
41 47 When disabled, uses the normal simple OpenAI Codex response stream.
43 49 Scope:
45 -- provider: `openai-codex`
46 -- API: `openai-codex-responses`
51 +- provider:
52 + `openai-codex`
53 +- API:
54 + `openai-codex-responses`
47 55 - all OpenAI Codex models
49 57 Reasoning options are clamped for the selected model before sending.

extensions/footer/README.md

Modified
11 11 ## Install / load
13 13 Loaded through the root `pi-ext` package.
14 -See [root README](../../README.md).
14 +See [root README](../../README.md).
16 16 ## Commands / tools / settings
45 45 Optional fields:
46 46 `variants`, `icon`, `color`, `bar`, `suffix`, `order`.
48 -Send `{ id, text: undefined }` to remove a segment.
48 +Send `{ id, text:
49 +undefined }` to remove a segment.
50 51 Segments sort by `order`; default is `50`.
51 52 Current session name is inserted in the `workspace` zone with order `0.5`.
62 63 Bar values clamp to `0..100`.
64 65 Publishes capability state at `Symbol.for("@bugabinga/pi-ext-footer")`:
65 -`{ version: 1, loaded: true }`.
66 +`{ version:
67 +1, loaded:
68 +true }`.
66 69 On quit/reload shutdown, `loaded` becomes `false`.
68 71 Hidden mode swaps in a zero-height footer stub.

extensions/forget/PLAN.md

Modified
1 1 # forget plan
3 -Experimental goal: expose a `forget` tool that removes selected transcript spans
4 -from the **active LLM context window**.
3 +Experimental goal:
4 +expose a `forget` tool that removes selected transcript spans from the **active
5 +LLM context window**.
6 7 ## SDK constraints
8 -- Pi session files are append-only. Entries cannot be modified or physically
9 - deleted through `SessionManager`.
9 +- Pi session files are append-only.
10 + Entries cannot be modified or physically deleted through `SessionManager`.
10 11 - Active context can still be changed safely by adding a compaction entry.
11 12 `appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook)`
12 13 makes `buildSessionContext()` emit the summary, then branch messages from
13 14 `firstKeptEntryId` onward.
14 -- Recent tail deletion is already covered by Pi tree navigation/forking. It is
15 - out of scope for Forget.
16 -- Middle deletion is not supported without replaying or filtering the transcript.
15 +- Recent tail deletion is already covered by Pi tree navigation/forking.
16 + It is out of scope for Forget.
17 +- Middle deletion is not supported without replaying or filtering the
18 + transcript.
17 19 Replay breaks IDs/tool-call adjacency; per-turn filtering is fragile and not a
18 20 persistent session edit.
20 22 ## Design
22 -- Tool: `forget`
23 - - `mode="inspect"`: list active branch entries with id, role/type, rough token
24 - estimate, and no content preview by default. Preview is opt-in only because
25 - inspect output itself becomes newer context and can otherwise re-leak text
26 - the next `before` compaction is meant to hide.
27 - - `mode="before"`: append a compaction entry that replaces all active context
28 - before `entry_id` with a short tombstone summary.
29 -- Per-prompt system reminder: short turn-local line tells the agent to consider
30 - Forget when the user starts a new task/objective and skip same-task follow-ups.
24 +- Tool:
25 + `forget`
26 + - `mode="inspect"`:
27 + list active branch entries with id, role/type, rough token estimate, and no
28 + content preview by default.
29 + Preview is opt-in only because inspect output itself becomes newer context
30 + and can otherwise re-leak text the next `before` compaction is meant to
31 + hide.
32 + - `mode="before"`:
33 + append a compaction entry that replaces all active context before `entry_id`
34 + with a short tombstone summary.
35 +- Per-prompt system reminder:
36 + short turn-local line tells the agent to consider Forget when the user starts
37 + a new task/objective and skip same-task follow-ups.
31 38 - Guardrails:
32 39 - target must exist on active branch.
33 - - target must be the latest user message, marked `current_user=yes` by inspect.
40 + - target must be the latest user message, marked `current_user=yes` by
41 + inspect.
34 42 - target must not be a `toolResult` or stale earlier user message.
35 - - dry-run preview available with `dry_run: true`.
43 + - dry-run preview available with `dry_run:
44 + true`.
36 45 - no physical deletion claim; JSONL keeps recoverable history.
37 46 - not a secret-redaction guarantee; newer/current messages and model thinking
38 47 can still contain sensitive strings.
40 49 ## Tests
42 -- Unit: branch formatting, target validation, forget summary/details.
43 -- Harness: extension loads, tool registers, injects short per-prompt reminder,
44 - `inspect` output works, `before` creates compaction with expected
45 - `firstKeptEntryId`, context drops old text, `range` refuses.
46 -- Real MiniMax: optional `FORGET_REAL=1`; runs isolated SDK session with only
47 - Forget loaded, calls real model, applies forget, verifies compaction is active.
48 -- Real task-switch probes: baseline prompt had 0 compactions; stronger
49 - `MUST` + `current_user=yes` prompt caused MiniMax to forget at task switches
50 - while still answering simple tasks.
51 +- Unit:
52 + branch formatting, target validation, forget summary/details.
53 +- Harness:
54 + extension loads, tool registers, injects short per-prompt reminder, `inspect`
55 + output works, `before` creates compaction with expected `firstKeptEntryId`,
56 + context drops old text, `range` refuses.
57 +- Real MiniMax:
58 + optional `FORGET_REAL=1`; runs isolated SDK session with only Forget loaded,
59 + calls real model, applies forget, verifies compaction is active.
60 +- Real task-switch probes:
61 + baseline prompt had 0 compactions; stronger `MUST` + `current_user=yes` prompt
62 + caused MiniMax to forget at task switches while still answering simple tasks.
52 64 ## Manual test

extensions/forget/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root `pi-ext` package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings
23 23 Hooks/events:
25 -- `before_agent_start`: injects one short reminder so the agent considers Forget
26 - when a new user prompt changes task/objective.
25 +- `before_agent_start`:
26 + injects one short reminder so the agent considers Forget when a new user
27 + prompt changes task/objective.
28 29 ## Behavior
30 -`forget mode="inspect"` lists active branch entries. Content previews are hidden
31 -by default so inspection does not copy soon-to-be-forgotten text into newer
32 -context. The latest user prompt is marked `current_user=yes` and repeated as
33 -`current_user_entry_id=...` near the top. Use `show_preview=true` only for
34 -debugging.
31 +`forget mode="inspect"` lists active branch entries.
32 +Content previews are hidden by default so inspection does not copy
33 +soon-to-be-forgotten text into newer context.
34 +The latest user prompt is marked `current_user=yes` and repeated as
35 +`current_user_entry_id=...` near the top.
36 +Use `show_preview=true` only for debugging.
36 -`forget mode="before" entry_id="..."` appends a Pi compaction entry. Active LLM
37 -context becomes:
38 +`forget mode="before" entry_id="..."` appends a Pi compaction entry.
39 +Active LLM context becomes:
39 41 1. a short tombstone summary saying prior context was intentionally forgotten;
40 42 2. branch messages from `entry_id` onward;
41 43 3. future messages.
43 -History is not physically deleted from the JSONL session file. It is removed from
44 -the active context path by Pi compaction semantics and can be recovered through
45 -tree/session history.
45 +History is not physically deleted from the JSONL session file.
46 +It is removed from the active context path by Pi compaction semantics and can be
47 +recovered through tree/session history.
47 -Forget is a context-budget tool, not a secrecy/redaction tool. If sensitive text
48 -appears in the current request, assistant reasoning, tool results, or later
49 -messages, Forget cannot remove that middle/newer span without also dropping the
50 -newer branch.
49 +Forget is a context-budget tool, not a secrecy/redaction tool.
50 +If sensitive text appears in the current request, assistant reasoning, tool
51 +results, or later messages, Forget cannot remove that middle/newer span without
52 +also dropping the newer branch.
52 54 Middle deletion is intentionally unsupported.
54 56 The injected reminder is intentionally turn-local system prompt text, not a
55 -stored reminder message. It costs a short line each turn but does not accumulate
56 -inside the session transcript.
57 +stored reminder message.
58 +It costs a short line each turn but does not accumulate inside the session
59 +transcript.

extensions/ghost/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root pi-ext package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings

extensions/goal/README.md

Modified
73 73 bytes read from the latest assistant response for judgment.
74 74 Default `4096`, clamped to `512..65536`.
75 75 - `tokenBudget`:
76 - optional approximate token budget for a new goal. Accepts numbers or strings
77 - like `100k`.
76 + optional approximate token budget for a new goal.
77 + Accepts numbers or strings like `100k`.
78 78 - `timeBudgetSeconds` / `timeBudget`:
79 - optional wall-clock budget for a new goal. Accepts seconds or strings like
80 - `30m`, `2h`.
79 + optional wall-clock budget for a new goal.
80 + Accepts seconds or strings like `30m`, `2h`.
82 82 ## Hooks
125 125 - Incomplete verdict increments `turnsUsed`; exhausted turn/token/time budget
126 126 pauses the goal.
127 127 - If still active, continuation is queued as a hidden `goal-continuation` custom
128 - message with `deliverAs: "followUp"` and `triggerTurn: true`.
128 + message with `deliverAs:
129 + "followUp"` and `triggerTurn:
130 + true`.
129 131 - `update_goal` is hidden until the first continue verdict increments
130 132 `turnsUsed`, then hidden again for terminal or paused goals.
131 133 - `/goal pause` only pauses active owned goals.
139 141 current owned goal.
140 142 - `/goal criteria` lists criteria.
141 143 Empty criteria print `No goal criteria.`
142 -- `/goal status` emits a compact notify summary: phase, elapsed/budget,
143 - objective, criteria preview, and last judge glyph/reason.
144 +- `/goal status` emits a compact notify summary:
145 + phase, elapsed/budget, objective, criteria preview, and last judge
146 + glyph/reason.
144 147 - UI status key:
145 148 `goal` for active, paused, queued, judging, and blocked goals when the shared
146 149 `footer` extension is absent.

extensions/leaks/README.md

Modified
4 4 # leaks
6 6 Provider-bound secret redaction for Pi.
8 8 ## Install / load
10 -Loaded through the root [pi-ext package](../../README.md).
10 +Loaded through the root [pi-ext package](../../README.md).
12 12 ## Commands / tools / settings
14 14 Command:
15 15 `/leaks status|reload|test <text>|clear`.
17 -Tools: none.
17 +Tools:
18 +none.
19 20 Hooks:
20 21 provider requests, context messages, tool calls, assistant message end.

extensions/model-info/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root `pi-ext` package.
8 -See [root README](../../README.md).
8 +See [root README](../../README.md).
10 10 ## Commands / tools / settings
52 52 Thinking level comes from `thinking_level_select`; otherwise from the latest
53 53 `thinking_level_change` session entry; fallback is `off`.
55 -Publishing only runs when UI is available. On shutdown, the extension clears its
56 -footer segment and status fallback.
55 +Publishing only runs when UI is available.
56 +On shutdown, the extension clears its footer segment and status fallback.

extensions/neko/README.md

Modified
7 7 ## Install / load
9 9 Loaded through the root pi-ext package.
10 -See [root README](../../README.md).
10 +See [root README](../../README.md).
12 12 ## Commands / tools / settings

extensions/nu-bang/README.md

Modified
9 9 ## Install / load
11 11 Loaded through the root pi-ext package.
12 -See [root README](../../README.md).
12 +See [root README](../../README.md).
14 14 ## Commands / tools / settings

extensions/prompt-autopsy/README.md

Modified
5 5 ## Install / load
7 7 Loaded through the root pi-ext package.
8 -See the [root README](../../README.md).
8 +See the [root README](../../README.md).
10 10 ## Commands / tools / settings
12 -- Command: `/prompt-autopsy`
13 -- Shortcut: `Ctrl+Alt+A`
14 -- Hooks: `session_start`, `session_shutdown`, `before_agent_start`, `agent_start`
15 -- Tools: none
16 -- Settings: none
12 +- Command:
13 + `/prompt-autopsy`
14 +- Shortcut:
15 + `Ctrl+Alt+A`
16 +- Hooks:
17 + `session_start`, `session_shutdown`, `before_agent_start`, `agent_start`
18 +- Tools:
19 + none
20 +- Settings:
21 + none
18 23 ## Behavior