pi-btw-extension

A pi extension that adds a /btw side channel for questions you do not want in the main transcript. It requires Pi 0.84.2–0.84.x and Node 22.19.0+ (the package peer range is >=0.84.2 <0.85.0).

/btw answers in an overlay using the context the main session already has. Nothing reaches the main conversation unless you confirm a share.

Install

pi install npm:pi-btw-extension
pi update --extension npm:pi-btw-extension
pi remove npm:pi-btw-extension

Pi bundles the packages this extension imports; there is no separate dependency to install.

Usage

Ask while the main agent is mid-task:

/btw what does this error actually mean?
/btw --history retryPolicy

The side agent decides whether its read-only tools are needed for each question. History browsing and search are model-free; Continue needs a currently selected model because it opens a writable thread. /btw --settings is a settings UI, while /btw --stats shows an active-lineage report as an interactive notification.

| Key or command | Action | |---|---| | /btw <question> | Ask; opens the overlay | | /btw | Reopen the active thread | | /btw --history | Browse archived threads | | /btw --history <query> | Browse archived threads filtered by query | | /btw --settings | Open settings UI | | /btw --stats | Show an active-lineage statistics notification | | configured shortcut (default Ctrl+Alt+B) | Open the overlay | | Enter | Submit the draft | | Shift+Enter or \ then Enter | Insert a newline in the draft | | Esc | Close the overlay, or cancel sharing selection, preview, or refine | | ← → | Previous / next question when the input is empty | | ↑ ↓ | Scroll a long card when the input is empty | | PgUp PgDn | Previous / next question regardless of input | | Ctrl+R | Regenerate the displayed question as a new immutable attempt | | Shift+← Shift+→ | Previous / next attempt for the displayed question | | Ctrl+P | Open sharing controls |

The overlay is a fixed-height pager (60% of the terminal, minimum 12 rows). It shows one question/answer card at a time; long cards scroll within it. On a tiny terminal, a tall multiline draft or refine loader can exceed that target so the input and footer remain visible. Ctrl+Alt+B is Ctrl+Option+B on macOS. A terminal that does not send Option as Meta (Terminal.app by default, for example) cannot deliver that shortcut; use /btw instead.

Sharing

Ctrl+P selects answers that have not been shared:

| Key | Action | |---|---| | ← → | Pick a card | | Shift+← Shift+→ | Inspect attempts on the selected question | | ↑ ↓ | Scroll the selected card | | Enter | Share the selected attempt | | a | Share one newest eligible unshared attempt per question in one note | | r | Rewrite as a short summary, then share | | Esc | Cancel |

Single, all, and refined sharing always open an editable preview. Its first [/btw note: ...] line must remain exactly unchanged. Canceling, submitting an empty preview, or letting the target become stale sends nothing. A confirmed preview queues one nextTurn note; sharing never starts a model turn itself. A durable shared to main badge records successful queueing, but cannot tell whether the main agent has consumed the note. Closing the overlay discards an in-flight ask, retry, or refine preview unless its attempt has already been persisted.

/btw --history is read-only. Use c to explicitly Continue the reviewed snapshot into the current session/branch. Continue leaves the archive untouched and makes a new writable thread, cloning its attempts, promotion state, summary, and summary meter into that snapshot. If the session or branch changes while browsing, reopen history. Legacy v1/v2 threads remain read-only history until Continue.

Configuration

Environment variables take precedence over the user-global ~/.pi/agent/btw.json, which takes precedence over defaults. Environment rows are read-only in the settings UI. Invalid individual values fail closed to the lower-precedence value; malformed JSON or UTF-8 is left byte-for-byte unchanged. Unknown JSON keys are preserved when settings are saved.

| Setting | Default | Environment variable | Notes | |---|---|---|---| | answerMaxTokens | 4096 | BTW_ANSWER_MAX_TOKENS | Caps every answer | | refineMaxTokens | 1024 | BTW_REFINE_MAX_TOKENS | Caps the r summary only | | toolCallBudget | 8 | BTW_TOOL_BUDGET | Tool calls per ask before it wraps up | | toolAllowlist | read,grep,find,ls | BTW_TOOL_ALLOWLIST | Comma-separated allowed tools; an empty value permits none and it can only narrow the built-in set | | summaryEnabled | true | BTW_SUMMARY_ENABLED | Enables automatic rolling side-thread maintenance | | summaryTriggerTokens | 12000 | BTW_SUMMARY_TRIGGER_TOKENS | Estimated side Q/A size before maintenance is considered | | summaryRetainTokens | 8000 | BTW_SUMMARY_RETAIN_TOKENS | Recent raw Q/A retained outside each summary | | summaryMaxTokens | 1024 | BTW_SUMMARY_MAX_TOKENS | Token cap for the separate summary request | | shortcut | ctrl+alt+b | BTW_SHORTCUT | Portable modified-key grammar only; unsafe or malformed values fall back |

/btw --settings writes user-global settings only, never environment values. Shortcut changes take effect after Pi reloads extensions. Pi reports shortcut conflicts during loading, but the final host conflict outcome is not introspectable by this extension.

Storage, migration, and privacy

Threads are stored per project at:

~/.pi/agent/btw/threads-<hash-of-cwd>.json

The current format is strict v5. v1/v2 legacy data is read losslessly but stays read-only until Continue; v3 scoped data retains its writable scope; v4 attempt-based data migrates to v5. Empty session/tree scope boundaries are preserved. Future-version and corrupt files are preserved as exact bytes and are never overwritten; BTW instead continues in memory with one persistence warning. This means mixed old/new installations have a limit: older binaries may refuse v5, so do not run a pre-v5 writer concurrently against shared project data. There is no automatic delete UI.

The file can contain side questions and answers, immutable attempts, model and grounding metadata, read-only tool names and errors, rolling summaries, summary usage and cost meters, durable share state, and session IDs/tree leaf IDs. To remove it manually, stop Pi first and back it up if needed; deleting a project hash loses that project archive. Do not delete it while Pi is running. Writes use a lock, latest-state reload, idempotent scoped operation, and atomic replace so same-cwd processes preserve each other’s creates and answers. Power-loss fsync durability and broader platform stale-lock recovery remain deferred.

Threads are isolated by Pi session and each real /tree navigation. The provider-visible grounding cache is keyed by session and tree leaf, and is cleared on session start, /tree navigation, and shutdown. Capture failures rebuild from current persisted context only, or return an empty prefix; they never expose a prior transcript. Every answer is an immutable attempt; retry streams to a temporary preview and appends a new attempt rather than replacing the old one. Attempt navigation is local, including read-only history. The side agent’s tool boundary is read-only (read, grep, find, ls): no write, edit, or bash is exposed.

Summary and statistics

Defaults use the active session context and separate provider requests for rolling summaries. Summary usage is separate from answer usage; /btw --stats reports only the active continued lineage. It cannot provide an exact global aggregate because Continue clones a cumulative meter. Raw Q/A is authoritative over generated summaries. Summary calls receive no tools and no main prefix; failures are silent and nonblocking. There is no cross-process call deduplication.

The UTF-8 token estimator is approximate, not an exact tokenizer. Summary maintenance never delays an ask. Its separate provider call preserves normal provider configuration but should be accounted for separately.

Development

npm run typecheck
npm test

The deterministic offline package-load test uses Pi 0.84.2’s DefaultResourceLoader and an in-memory SettingsManager. It loads both the working directory and a locally packed, locally installed tarball in bounded child processes with PI_OFFLINE=1, a minimal credential-free environment, and a fetch override that fails any network attempt. It also invokes the pinned local Pi CLI through Node with an isolated temporary agent directory to install, list, and remove the locally installed artifact. It never sends a provider, model, or session request, and enforces exactly 22 runtime package files. Provider-required smoke prompts are not a release gate.

Release checklist (automated gates are required; manual checks are pending until performed):

• [x] Run npm run typecheck, npm test, and npm pack --dry-run --json; confirm 22 files.
• [x] Run the credential-free isolated Pi CLI install/list/remove smoke against the locally packed artifact.
• [ ] Confirm real macOS and Windows CI runs (Linux, macOS, Windows; Node 22.19 and 24).
• [ ] Test Korean, Japanese, and Chinese IME input on macOS and on a Linux or Windows terminal.
• [ ] Test narrow and fullscreen TUI layouts.
• [ ] Run two Pi processes in the same cwd.
• [ ] Load a real v0.4.1 store copy and verify migration behavior.
• [ ] Reload a changed shortcut and check a Pi shortcut conflict.
• [ ] Check preview cancel, edit, and confirm flows.

Limitations

There is no web search or page fetching. Pi has no public API for one extension to reuse another extension’s tools. Terminal Option/Meta delivery can prevent the default macOS shortcut. The extension cannot introspect Pi’s ultimate shortcut-conflict outcome. Power-loss fsync and broader platform stale-recovery policy are deferred.

License

MIT