💬 pi-btw — Side Questions for the Pi Coding Agent

@narumitw/pi-btw is a native Pi coding agent extension that adds /btw, a side-question command for quick clarifications that should not interrupt or pollute the main agent conversation.

Use it when you want to ask a temporary question, inspect context, or get a short explanation while keeping the primary coding task focused.

✨ Features

• Adds a /btw menu for starting a side thread or changing pi-btw settings.
• Keeps /btw <question> as a direct fast path.
• Answers side questions in a temporary, scrollable UI.
• Supports follow-up questions in the same ephemeral side thread.
• Optionally brings the latest answer, a question-to-end suffix, an exact line range, or the entire side thread into the main editor.
• Uses the current session branch as context.
• Uses Pi's current model or an independent model selected in pi-btw.json.
• Uses a pi-btw thinking level that can be changed with Pi's configured thinking shortcut and remembered for next time.
• Does not append the side question or answer to the main conversation.
• Works as an independently installable npm Pi extension package.

📦 Install

pi install npm:@narumitw/pi-btw

Try without installing permanently:

pi -e npm:@narumitw/pi-btw

Try this package locally from the repository root:

pi -e ./extensions/pi-btw

🚀 Usage

Open the pi-btw menu or provide the first question immediately:

/btw
/btw <your side question>

Examples:

/btw
/btw what does this TypeScript error mean?
/btw summarize the current implementation before we continue
/btw is this API name idiomatic?

Running /btw alone opens a two-row menu. Start side thread is selected first, so pressing Enter opens an empty ephemeral side thread; Settings changes the starting thinking level and whether shortcut changes are remembered. /btw <question> bypasses this menu, and its answer opens above the side-thread editor. A compact btw · side thread header stays fixed above the content so the ephemeral workspace remains recognizable while scrolling. Messages use Pi's normal user and assistant presentation without numbered turns or role labels. Type each question and press Enter; no follow-up shortcut is required. Previous side questions and answers remain available to the model and visible for that invocation. The side-thread header shows its current thinking level. Press Pi's configured app.thinking.cycle shortcut (Shift+Tab by default) in the composer to cycle the levels supported by the side-thread model; every later question uses the displayed level until it is changed again. By default, each shortcut change is also written to pi-btw.json for the next invocation. Turn Remember thinking level changes off in Settings to keep changes local to the current side thread. Neither path changes the main session's thinking level. While a response is running, the transcript stays visible above a compact Answering… status. The footer shows PgUp/PgDn only when history can scroll; press Ctrl+C to cancel an in-progress answer or leave the side thread.

After at least one successful answer, press Ctrl+R to bring selected context to the main editor. The scope menu shows the size of the latest question and answer and the entire side thread before you choose. Bring the latest question and answer, everything from a chosen question onward, an exact text range, or the entire side thread. Question-suffix, exact-range, and entire-thread choices preview the exact editable context block before the side thread closes; Escape returns and Ctrl+C closes without bringing anything to main.

The text-range selector supports both fast line selection and editor-style character selection. It reports whether anything is selected plus the selected line, message, and approximate token counts. Press Space to select the current raw source line, then use Up/Down to extend by whole lines; press Space again to clear it. Alternatively, use the arrow keys to move the cursor and Shift+arrow keys to extend a character-level selection. Starting a Shift selection replaces any active line selection. Selected lines include a visible ● marker in addition to highlighting. Pi's configured keys control vertical navigation, bringing, and going back (Up/Down, Enter, and Escape by default), and the selector displays the active keys. Selection follows raw source text rather than terminal-wrapped visual rows.

Bringing context to main closes the side thread and loads a deterministic, editable context block into Pi's main editor. It never sends the draft automatically. If the main editor already has a draft, append is the recommended default. Replace is labeled as destructive and requires a second confirmation; Cancel returns to the side thread without changing either draft. Concurrent editor updates made while these menus are open are preserved. A success message reports whether context was loaded, appended, or replaced and its approximate size. Without an explicit bring-to-main action, closing /btw, reloading Pi, or switching sessions still discards the side thread without adding it to the main conversation.

⚙️ Model and thinking level

By default, /btw uses the current session model. To use an independent model for side questions, create:

$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
}

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 cannot be found or authenticated, 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.

Pi calls its reasoning setting the thinking level. thinkingLevel sets pi-btw's starting level; accepted values are off, minimal, low, medium, high, xhigh, and max. When the field is absent for backward compatibility, the next invocation starts from the current session level. The initial value and shortcut cycle are clamped to the selected side model's capabilities using Pi's model rules. Pi-btw does not read, write, or change the main session's defaultThinkingLevel.

rememberThinkingLevelChanges controls only persistence and defaults to true when omitted. A side-thread shortcut always changes that side thread immediately. When remembering is on, the concrete level is written for the next invocation; when off, pi-btw.json stays unchanged. 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.

A missing settings file is a side-effect-free read: pi-btw creates it only after a Settings change or a remembered shortcut change. Saves are ordered within the Pi process and published atomically with a same-directory temporary file and rename. They preserve model and unknown fields; malformed or invalid files block saves and remain unchanged. Settings must be valid UTF-8 and no larger than 64 KiB, so unexpectedly large or invalidly encoded files are rejected without being rewritten. Separate Pi processes and external editors are outside this in-process ordering boundary. The file is read for each /btw invocation, so edits apply without /reload.

🧠 Why use pi-btw?

Normal assistant messages become part of the main Pi conversation and can distract the coding agent from the task. pi-btw creates a lightweight side channel for context-aware questions, making it useful for pair programming, debugging, code review, and repository exploration.

🗂️ Package layout

extensions/pi-btw/
├── src/
│   ├── index.ts
│   ├── btw.ts
│   ├── bring-to-main.ts
│   ├── menu.ts
│   ├── settings.ts
│   ├── side-thread.ts
│   ├── text.ts
│   └── transcript-pager.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

The package exposes its Pi extension through package.json:

{
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

🔎 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.