💬 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 <question> command to Pi.
• Answers side questions in a temporary, scrollable UI.
• Uses the current session branch as context.
• Uses Pi's current model or an independent model selected in pi-btw.json.
• Inherits Pi's current thinking level or uses a fixed level from pi-btw.json.
• 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

/btw <your side question>

Examples:

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

Long answers open in a pager-style view. Use ↑/↓ or k/j to scroll by line, PgUp/PgDn, Shift+Space/Space, or Ctrl+B/Ctrl+F to scroll by page, Ctrl+U/Ctrl+D to scroll by half page, and Home/End to jump. Close with q, Esc, Enter, or Ctrl+C.

⚙️ 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"
}

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. By default, /btw inherits the current runtime level, including changes made through /settings or Shift+Tab. It does not read or change defaultThinkingLevel directly. Supported fixed values are off, minimal, low, medium, high, and xhigh. The selected value applies to the model actually used by /btw and does not change the main session. Pi's provider layer may clamp a requested level when that model does not support it.

The settings file is optional and is never created automatically. A missing file, {}, or omitted fields silently inherit the current Pi model and thinking level. The file is read for each /btw invocation, so edits apply to the next side question without /reload. Invalid or unreadable settings produce a warning and fall back to the current Pi defaults.

🧠 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/
│   └── btw.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

The package exposes its Pi extension through package.json:

{
  "pi": {
    "extensions": ["./src/btw.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.