💬 pi-btw — Ask Side Questions Without Derailing the Main Task

Ask questions in a temporary side thread without adding them to the main Pi conversation. Only context you explicitly bring back is loaded into the main editor.

✨ Features

• Starts a side thread immediately with /btw <question> or opens the manager with /btw.
• Uses any persisted main-session branch as context without switching branches.
• Supports scrollable answers, transcript search, a clickable jump-to-latest control, follow-up questions, queued steering, and in-memory resume.
• Uses Pi's message components, a native-style working editor border, and a compact footer below the editor.
• Offers fullscreen, side-thread-left, and side-thread-right workspaces with Pi's live main-thread view, mouse or keyboard pane focus, and a draggable remembered divider.
• Renders supported Mermaid fences as width-safe, themed Unicode diagrams without a browser or network request.
• Keeps side questions and answers out of the main conversation by default.
• Brings back the latest answer, a question suffix, an exact range, or the complete thread only when requested.
• Uses Pi's current model and thinking level or saved pi-btw choices.
• Offers BTW-only exit, thinking-cycle, bring-to-main, and pane-switch keybindings.

📦 Install

pi install npm:@narumitw/pi-btw

Try without installing permanently:

pi -e npm:@narumitw/pi-btw

Build and try this package locally from the repository root:

npm --workspace @narumitw/pi-btw run build
pi -e ./packages/pi-btw

The package declares dist/index.ts, so an unbuilt local checkout must run the build before Pi loads the package directory. Pi extensions run with the Pi process's user permissions, so install only trusted packages.

🚀 Quick start

In TUI mode, run /btw <question> to start immediately or /btw to choose context and settings first. The side thread stays separate until you explicitly bring context to the main editor.

💬 Commands

Command	Purpose
/btw	Choose context, start or resume a side thread, or change settings.
/btw <question>	Start a new side thread immediately with the supplied question.

Both routes require TUI mode and a model with usable credentials; see Settings. Side questions and selected conversation context are sent to that model's provider. Bringing context back fills the main editor without submitting; replacing an existing draft requires confirmation. Ctrl+C cancels the response and discards the current draft and queued questions, but completed exchanges remain resumable in memory. Read the workflow guide for context selection, copying, search, steering, and draft recovery; /new, /resume, /reload, and restart discard retained threads.

⚙️ Settings

By default, /btw uses the current session model. Open /btw → Settings → Model to choose an available model or Same as main thread to remove the override. The searchable picker follows the current Pi model scope and saves immediately without changing the main session model. A manually configured available model outside that scope remains active and visible until you explicitly choose another option.

You can also edit the user settings file directly:

$PI_CODING_AGENT_DIR/pi-btw.json

The normal location is ~/.pi/agent/pi-btw.json. PI_CODING_AGENT_DIR is an existing Pi setting; pi-btw does not add any environment variables.

{
  "model": "anthropic/claude-sonnet-4-5",
  "thinkingLevel": "low",
  "rememberThinkingLevelChanges": true,
  "fullscreenCopyOnSelect": true,
  "layout": "left-pane",
  "sidePaneRatio": 0.5
}

The model value uses provider/model-id format. Only the first / is the separator, so model IDs may contain additional slashes, such as openrouter/anthropic/claude-sonnet. The configured model must exist in Pi's model registry and have usable credentials. If it is missing or unauthenticated, pi-btw warns and falls back to the current session model. If neither model is available, /btw reports an error and stops. This selection affects only /btw; it does not change the main session model. Model changes apply when the next new or resumed side thread starts.

Pi calls its reasoning setting the thinking level. In Settings, choose Same as main thread to start each new side thread from the main thread's current thinking level. This is stored by omitting thinkingLevel from pi-btw.json.

Set thinkingLevel only when you want a fixed pi-btw starting level. Accepted fixed values are off, minimal, low, medium, high, xhigh, and max. The initial value and shortcut cycle are clamped to the selected side model's capabilities using Pi's model rules. Resumed side threads keep their own local thinking level instead of re-syncing with the main thread. Pi-btw does not read, write, or change the main session's defaultThinkingLevel.

rememberThinkingLevelChanges controls only persistence for fixed thinking levels and defaults to true when omitted. A side-thread shortcut always changes that side thread immediately. When a fixed thinking level is selected and remembering is on, the concrete level is written for the next invocation; when off, pi-btw.json stays unchanged. When Same as main thread is selected, shortcut changes stay local even when remembering is on. If a shortcut write fails, the local change remains active and pi-btw warns that it was not remembered. A failed Settings-screen save instead restores the previous displayed value.

fullscreenCopyOnSelect controls only pi-btw's dedicated workspace and defaults to true when omitted. Turn Copy selection automatically off to retain highlighted selections and copy them with Pi's effective app.message.copy binding. Pi-btw does not inherit Pi core's setting of the same name because Pi's public extension API does not expose its effective value.

layout controls the dedicated workspace and defaults to fullscreen when omitted. Accepted values are fullscreen, left-pane, and right-pane. The pane names identify the side thread's position; the other pane reuses Pi's native main-thread rendering at pane width and stays current while BTW is open. A single muted divider separates the panes; click either pane or use the pane-switch shortcut to move keyboard focus. The footer below the editor shows BTW focus or Main focus and the available switch key. It also shows the selected side model and thinking level when space permits; narrow or short views omit optional fields and hints before the active input row. Drag the divider with the primary mouse button to resize both panes. The side-thread share is limited to 20–80% and saved as sidePaneRatio when the button is released, independent of whether the side thread is on the left or right. If the save fails, the workspace restores the last saved ratio and reports the error. Pi's search and keyboard viewport controls apply to the active pane. The mouse wheel scrolls the pane under the pointer without moving keyboard focus, and both panes continue redrawing while either pane is active. If you selected context from the main-thread tree, the main pane still shows the active main thread while the side model receives the selected branch. Pane layouts collapse to the side thread alone below 80 terminal columns and return keyboard focus to it. Choose Side-thread layout in Settings; changes apply the next time a new or resumed BTW workspace opens.

Keybindings

Open /btw → Settings, select a shortcut row, then choose Edit key combination… or Restore default. Type a key name such as ctrl+q or f6; this is not a key-recording prompt. Changes save immediately and apply when opening or resuming BTW, without /reload. Escape cancels an unfinished edit, not earlier saves. The literal /btw settings remains a side question, not a settings subcommand.

JSON field under keybindings	Default	Action
exit	ctrl+c	Cancel and leave the dedicated side-thread workspace, including its nested dialogs.
cycleThinkingLevel	Inherit Pi's app.thinking.cycle	Cycle supported levels while composing or generating.
bringToMain	ctrl+r	Open the bring-to-main chooser after a completed answer.
switchPane	First available f6, f7, or f8	Switch keyboard focus between panes in a split workspace.

For example, merge these overrides into pi-btw.json:

{
  "keybindings": {
    "exit": "ctrl+q",
    "cycleThinkingLevel": "f6",
    "bringToMain": "f7"
  }
}

Each override accepts one Pi key name with optional ctrl, shift, alt, and super modifiers; modifier order and letter case do not matter. Letters, digits, Pi special keys and symbols are recognized, except the literal +, which Pi's matcher cannot parse as a base key. Function keys f1–f12 and Escape accept no modifiers; Clear accepts only no modifier, Shift, or Ctrl. Actual availability depends on the terminal; super and some modified combinations require extended keyboard reporting.

New overrides cannot take ordinary typing keys or conflict with BTW actions, Pi editing, selection, search, scrolling, or enabled manual-copy bindings. Pi's explicitly configured printable thinking shortcuts remain inherited for compatibility. If a saved override becomes conflicting, BTW warns and uses an available default; if none is usable, that shortcut is unavailable and its activation hint is omitted. The pane-switch action uses only the first available fallback and does not displace an existing BTW override or inherited Pi thinking shortcut. It has no effect in fullscreen-only or collapsed layouts, and background pane switching is blocked while an overlay owns focus. An explicitly unbound Pi thinking action stays unbound. Remove an override field to restore its default; neither saving nor resetting modifies Pi's global keybindings. Ctrl+C always remains available as hard cancel, even after configuring another exit key. Shortcut handling does not interpret bracketed-paste payloads as commands.

Persistence

Reading a missing settings file has no side effects. Pi-btw creates it only after a Settings change, a remembered shortcut change, or a divider drag. Within one Pi process, saves run in order and publish atomically through a same-directory temporary file and rename. Saves preserve other recognized settings and unknown fields. Malformed or invalid files block saves and remain unchanged. Files must be valid UTF-8 and no larger than 64 KiB. Separate Pi processes and external editors are outside the in-process ordering boundary. The file is read for every /btw invocation, so edits apply without /reload.

🚧 Limitations

• /btw supports TUI mode only.
• Only the active pane receives keyboard input; hovering or scrolling over the other pane does not move focus.
• Resume state is memory-only and lasts only for the current extension instance.
• A side thread retains the latest 40,000 characters of main-conversation context and adds a truncation notice when earlier content is omitted.
• Clipboard access depends on Pi's host helper, the operating system, and the terminal.
• The live workspace still uses a BTW-owned terminal handoff and private host-layout access because Pi has no public workspace-composition API; see the core-alignment handoff for tested safeguards, exact limits, and proposed APIs.
• Pi does not expose all effective renderer options or a public clipboard-read callback. BTW uses native automatic wheel behavior but does not inherit private host wheel overrides or right-click clipboard paste.
• Conversation appearance follows native defaults, not custom host editor/footer extensions or private padding settings. BTW uses one-cell message padding and zero-cell editor padding; see the appearance reference and before/after frames.
• Malformed, unsupported, or oversized Mermaid diagrams remain readable as fenced source; partial parses also show a warning.
• Pi versions before 0.85 omit the clickable jump-to-latest control.

🗂️ Package layout

packages/pi-btw/
├── src/                               # Authoritative implementation and helpers
│   ├── index.ts                       # Thin Pi entrypoint
│   └── btw.ts                         # Side-thread lifecycle and command
├── dist/                              # Generated Jiti runtime
├── docs/                              # Workflows, appearance evidence, and core-alignment handoff
├── scripts/build-runtime.mjs          # Runtime builder
└── test/                              # Behavior and lifecycle coverage

The generated runtime is built from src/index.ts and does not import back into src.

🔎 Keywords

Pi extension, Pi coding agent, AI coding agent, side question command, agent chat workflow, TypeScript Pi package, npm Pi extension.

📄 License

MIT. See LICENSE.