@herbertgao/pi-extensions 2026.8.1 → 2026.8.2

package/node_modules/@herbertgao/pi-stash/README.md

@@ -12,20 +12,20 @@ pi install npm:@herbertgao/pi-stash
 
 ## Keybinding
 
-pi-stash overrides Pi's built-in `Ctrl+S` shortcuts. Remap them in `$PI_CODING_AGENT_DIR/keybindings.json` (default: `~/.pi/agent/keybindings.json`), then run `/reload`:
+pi-stash uses `Alt+S`, which does not conflict with Pi's built-in shortcuts.
 
-```json
-{
-  "app.models.save": ["ctrl+shift+s"],
-  "app.session.toggleSort": ["ctrl+shift+s"]
-}
-```
+### macOS
+
+On macOS, press `Option+S` (`Option` is the `Alt` key). If that inserts `ß` instead of triggering pi-stash, configure the terminal to send `Option` as Meta/Escape:
+
+- Terminal.app: **Settings → Profiles → Keyboard → Use Option as Meta key**.
+- iTerm2: **Settings → Profiles → Keys → Left Option key** (or **Right Option key**) → **Esc+**.
 
 ## Usage
 
-Press `Ctrl+S` with text in the editor to stash it. Pi clears the editor so you can send another message, then restores the draft as soon as that message is submitted.
+Press `Alt+S` with text in the editor to stash it. Pi clears the editor so you can send another message, then restores the draft as soon as that message is submitted.
 
-Press `Ctrl+S` again while the editor is empty to restore the draft manually. If the editor contains new text, pi-stash keeps both drafts unchanged and refuses to overwrite either one.
+Press `Alt+S` again while the editor is empty to restore the draft manually. If the editor contains new text, pi-stash keeps both drafts unchanged and refuses to overwrite either one.
 
 The stash belongs to the current session and survives reloads and restarts. Slash commands and `!` shell commands do not consume it.
 

package/node_modules/@herbertgao/pi-stash/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-stash",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Stash one pi draft and restore it after the next message.",
   "keywords": [
     "pi",

package/node_modules/@herbertgao/pi-stash/src/index.ts

@@ -6,6 +6,7 @@ import type {
 } from "@earendil-works/pi-coding-agent"
 
 export const STASH_ENTRY_TYPE = "pi-stash-state"
+export const STASH_SHORTCUT = "alt+s"
 
 interface StashState {
   draft: string | null
@@ -92,7 +93,7 @@ export default function stashExtension(pi: ExtensionAPI) {
     if (shouldAutoRestore(event.source, event.text)) restoreDraft(ctx)
   })
 
-  pi.registerShortcut("ctrl+s", {
+  pi.registerShortcut(STASH_SHORTCUT, {
     description: "Stash or restore the current draft",
     handler: (ctx) => {
       const action = getShortcutAction(ctx.ui.getEditorText(), pendingDraft)

package/node_modules/@herbertgao/pi-subagents/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.15.2
+
+### Patch Changes
+
+- [#15](https://github.com/HerbertGao/pi-extensions/pull/15) [`bc083d2`](https://github.com/HerbertGao/pi-extensions/commit/bc083d27c974f6b5239561dbd2295b6dd53526c0) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Skip unreadable or malformed custom agent files by default, warn when an earlier same-named definition remains active, and add opt-in strict startup validation.
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -7,6 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`strictAgentFiles` — fail startup on a broken agent file instead of skipping it.** Off by default and applied only during initial extension activation; later per-call reloads remain tolerant.
+
+### Fixed
+
+- **One malformed agent file no longer aborts extension activation** ([#212](https://github.com/tintinweb/pi-subagents/issues/212) — thanks [@daromaj](https://github.com/daromaj)). Unreadable and unparseable files are skipped with a path-specific warning, including the earlier source that remains active when a broken file was an override.
+
 ## [0.15.1] - 2026-08-10
 
 ### Fixed

package/node_modules/@herbertgao/pi-subagents/README.md

@@ -180,6 +180,8 @@ Agents are discovered from three locations (higher priority wins):
 
 Project-level agents override global ones with the same name, so you can customize a global agent for a specific project. If both project locations define the same name, **`.pi/agents/` wins** — `.pi` stays the project authority; `.agents/agents/` is an additional read location for projects that keep their agent assets in the `.agents` workspace. The global location follows the upstream `PI_CODING_AGENT_DIR` env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.
 
+An unreadable or unparseable agent file is skipped by default, with a warning that names the file and error. If the skipped file was overriding a same-named agent, another warning names the earlier file that remains active. Set `strictAgentFiles: true` in `subagents.json` (or `/agents → Settings → Strict agent files`) to fail startup on a broken file instead; mid-session reloads remain tolerant.
+
 ### Example: `.pi/agents/auditor.md`
 
 ```markdown
@@ -430,12 +432,14 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default join mode, scheduling on/off, scope models on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, widget all/background/off) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, nested depth, fallback agent, default join mode, scheduling on/off, scope models on/off, strict agent files on/off, disable defaults on/off, output transcript on/off, tool description full/compact/custom, widget all/background/off) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
 
-**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, defaults enabled).
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, strict agent files disabled, defaults enabled).
+
+**Strict agent files** (`strictAgentFiles`, default `false`): fail extension startup when any discovered agent file is unreadable or malformed. Enable via `/agents → Settings → Strict agent files` or set `true` in `subagents.json`. Strictness applies only to startup; reloads before later Agent calls remain tolerant so a file edited incorrectly mid-session is skipped with a warning instead of aborting the call.
 
 **Nested depth** (`maxSubagentDepth`, default `2`): the hard ceiling on [nested delegation](#nested-subagents), counted from the main session (main = 0, its subagents = 1). `0` or `1` disables nesting project-wide regardless of any agent's `allowed_subagents`. Read when a subagent session is built, so a change applies to agents started after it.
 

package/node_modules/@herbertgao/pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Claude Code-style autonomous subagents for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
@@ -64,8 +64,8 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.14.3",
+    "version": "0.15.0",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "2966cd5"
+    "commit": "140324c"
   }
 }

package/node_modules/@herbertgao/pi-subagents/src/custom-agents.ts

@@ -8,6 +8,13 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent"
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js"
 import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js"
 
+interface WarningState {
+  previous: Set<string>
+  current: Set<string>
+}
+
+const warningHistoryByCwd = new Map<string, Set<string>>()
+
 /**
  * Scan for custom agent .md files from multiple locations.
  * Discovery hierarchy (higher priority wins):
@@ -20,15 +27,36 @@ import type { AgentConfig, MemoryScope, ThinkingLevel } from "./types.js"
  * authority; .agents/agents is an additional read location.
  * Any name is allowed — names matching defaults (e.g. "Explore") override them.
  */
-export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
+export function loadCustomAgents(
+  cwd: string,
+  strict = false,
+): Map<string, AgentConfig> {
   const globalDir = join(getAgentDir(), "agents")
   const workspaceProjectDir = join(cwd, ".agents", "agents")
   const projectDir = join(cwd, ".pi", "agents")
 
   const agents = new Map<string, AgentConfig>()
-  loadFromDir(globalDir, agents, "global") // lowest priority
-  loadFromDir(workspaceProjectDir, agents, "project") // shared workspace
-  loadFromDir(projectDir, agents, "project") // highest priority (overwrites)
+  const skippedOverrides = new Set<string>()
+  const warnings: WarningState = {
+    previous: warningHistoryByCwd.get(cwd) ?? new Set(),
+    current: new Set(),
+  }
+
+  loadFromDir(globalDir, agents, "global", strict, warnings, skippedOverrides) // lowest priority
+  loadFromDir(
+    workspaceProjectDir,
+    agents,
+    "project",
+    strict,
+    warnings,
+    skippedOverrides,
+  ) // shared workspace
+  loadFromDir(projectDir, agents, "project", strict, warnings, skippedOverrides) // highest priority (overwrites)
+
+  for (const name of skippedOverrides) {
+    warnSkippedOverride(name, agents, warnings)
+  }
+  warningHistoryByCwd.set(cwd, warnings.current)
   return agents
 }
 
@@ -37,6 +65,9 @@ function loadFromDir(
   dir: string,
   agents: Map<string, AgentConfig>,
   source: "project" | "global",
+  strict: boolean,
+  warnings: WarningState,
+  skippedOverrides: Set<string>,
 ): void {
   if (!existsSync(dir)) return
 
@@ -49,16 +80,15 @@ function loadFromDir(
 
   for (const file of files) {
     const name = basename(file, ".md")
+    const path = join(dir, file)
 
-    let content: string
-    try {
-      content = readFileSync(join(dir, file), "utf-8")
-    } catch {
+    const parsed = readAgentFile(path, strict, warnings)
+    if (!parsed) {
+      skippedOverrides.add(name)
       continue
     }
-
-    const { frontmatter: fm, body } =
-      parseFrontmatter<Record<string, unknown>>(content)
+    skippedOverrides.delete(name)
+    const { frontmatter: fm, body } = parsed
 
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools)
 
@@ -97,10 +127,54 @@ function loadFromDir(
       isolation: fm.isolation === "worktree" ? "worktree" : undefined,
       enabled: fm.enabled !== false, // default true; explicitly false disables
       source,
+      sourcePath: path,
     })
   }
 }
 
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * skip. Under strict mode the same failure aborts startup while naming the file.
+ */
+function readAgentFile(
+  path: string,
+  strict: boolean,
+  warnings: WarningState,
+): { frontmatter: Record<string, unknown>; body: string } | undefined {
+  try {
+    return parseFrontmatter<Record<string, unknown>>(
+      readFileSync(path, "utf-8"),
+    )
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    if (strict) throw new Error(`${path}: ${reason}`)
+    warnIfNew(`Skipping agent file ${path}: ${reason}`, warnings)
+    return undefined
+  }
+}
+
+/** Warn when a broken higher-priority file exposes an earlier definition. */
+function warnSkippedOverride(
+  name: string,
+  agents: Map<string, AgentConfig>,
+  warnings: WarningState,
+): void {
+  const surviving = agents.get(name)
+  if (!surviving?.sourcePath || surviving.enabled === false) return
+  warnIfNew(
+    `Agent "${name}" now loads from ${surviving.sourcePath} instead`,
+    warnings,
+  )
+}
+
+/** Warn once while an error is unchanged, but report it again after recovery. */
+function warnIfNew(message: string, warnings: WarningState): void {
+  if (warnings.current.has(message)) return
+  warnings.current.add(message)
+  if (warnings.previous.has(message)) return
+  console.warn(`[pi-subagents] ${message}`)
+}
+
 // ---- Field parsers ----
 // All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
 

package/node_modules/@herbertgao/pi-subagents/src/index.ts

@@ -83,6 +83,7 @@ import { SubagentScheduler } from "./schedule.js"
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js"
 import {
   applyAndEmitLoaded,
+  loadSettings,
   type SubagentsSettings,
   saveAndEmitChanged,
   type ToolDescriptionMode,
@@ -426,14 +427,18 @@ export default function (pi: ExtensionAPI) {
     },
   )
 
+  // This setting controls the initial load, which runs before the normal settings
+  // application below. Later per-call reloads deliberately remain tolerant.
+  let strictAgentFiles = loadSettings(process.cwd()).strictAgentFiles === true
+
   /** Reload agents from project/global custom agent dirs and merge with defaults (called on init and each Agent invocation). */
-  const reloadCustomAgents = () => {
-    const userAgents = loadCustomAgents(process.cwd())
+  const reloadCustomAgents = (strict = false) => {
+    const userAgents = loadCustomAgents(process.cwd(), strict)
     registerAgents(userAgents)
   }
 
-  // Initial load
-  reloadCustomAgents()
+  // Initial load — the only strict one.
+  reloadCustomAgents(strictAgentFiles)
 
   // ---- Agent activity tracking + widget ----
   const agentActivity = new Map<string, AgentActivity>()
@@ -990,6 +995,9 @@ export default function (pi: ExtensionAPI) {
       setDefaultJoinMode,
       setSchedulingEnabled,
       setScopeModels: setScopeModelsEnabled,
+      setStrictAgentFiles: (enabled) => {
+        strictAgentFiles = enabled
+      },
       setDisableDefaultAgents: setDisableDefaultAgents,
       setToolDescriptionMode: setToolDescriptionMode,
       setFleetView: setFleetViewEnabled,
@@ -2673,6 +2681,7 @@ ${systemPrompt}
       defaultJoinMode: getDefaultJoinMode(),
       schedulingEnabled: isSchedulingEnabled(),
       scopeModels: isScopeModelsEnabled(),
+      strictAgentFiles,
       disableDefaultAgents: isDefaultsDisabled(),
       toolDescriptionMode: getToolDescriptionMode(),
       fleetView: isFleetViewEnabled(),
@@ -2762,6 +2771,14 @@ ${systemPrompt}
           currentValue: isScopeModelsEnabled() ? "on" : "off",
           values: ["on", "off"],
         },
+        {
+          id: "strictAgentFiles",
+          label: "Strict agent files",
+          description:
+            "Fail startup on an unreadable or unparseable agent .md instead of skipping it with a warning",
+          currentValue: strictAgentFiles ? "on" : "off",
+          values: ["on", "off"],
+        },
         {
           id: "disableDefaultAgents",
           label: "Disable defaults",
@@ -2867,6 +2884,13 @@ ${systemPrompt}
         const enabled = value === "on"
         setScopeModelsEnabled(enabled)
         notifyApplied(ctx, `Scope models ${enabled ? "enabled" : "disabled"}`)
+      } else if (id === "strictAgentFiles") {
+        const enabled = value === "on"
+        strictAgentFiles = enabled
+        notifyApplied(
+          ctx,
+          `Strict agent files ${enabled ? "enabled" : "disabled"}. Takes effect on next pi session.`,
+        )
       } else if (id === "disableDefaultAgents") {
         const enabled = value === "on"
         setDisableDefaultAgents(enabled)

package/node_modules/@herbertgao/pi-subagents/src/settings.ts

@@ -49,6 +49,12 @@ export interface SubagentsSettings {
    * against. Defaults to false: subagents may use any model.
    */
   scopeModels?: boolean
+  /**
+   * When true, an unreadable or unparseable agent `.md` aborts extension load
+   * instead of being skipped with a warning. This applies only during startup;
+   * later per-call reloads remain tolerant. Defaults to false.
+   */
+  strictAgentFiles?: boolean
   /**
    * When true, the three built-in default agents (general-purpose, Explore, Plan)
    * are not registered at startup. User-defined agents from project/global custom
@@ -129,6 +135,7 @@ export interface SettingsAppliers {
   setDefaultJoinMode: (mode: JoinMode) => void
   setSchedulingEnabled: (b: boolean) => void
   setScopeModels: (enabled: boolean) => void
+  setStrictAgentFiles: (b: boolean) => void
   setDisableDefaultAgents: (b: boolean) => void
   setToolDescriptionMode: (mode: ToolDescriptionMode) => void
   setFleetView: (b: boolean) => void
@@ -207,6 +214,9 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.scopeModels === "boolean") {
     out.scopeModels = r.scopeModels
   }
+  if (typeof r.strictAgentFiles === "boolean") {
+    out.strictAgentFiles = r.strictAgentFiles
+  }
   if (typeof r.disableDefaultAgents === "boolean") {
     out.disableDefaultAgents = r.disableDefaultAgents
   }
@@ -315,6 +325,8 @@ export function applySettings(
   if (typeof s.schedulingEnabled === "boolean")
     appliers.setSchedulingEnabled(s.schedulingEnabled)
   if (typeof s.scopeModels === "boolean") appliers.setScopeModels(s.scopeModels)
+  if (typeof s.strictAgentFiles === "boolean")
+    appliers.setStrictAgentFiles(s.strictAgentFiles)
   if (typeof s.disableDefaultAgents === "boolean")
     appliers.setDisableDefaultAgents(s.disableDefaultAgents)
   if (s.toolDescriptionMode)

package/node_modules/@herbertgao/pi-subagents/src/types.ts

@@ -77,6 +77,8 @@ export interface AgentConfig {
   enabled?: boolean
   /** Where this agent was loaded from */
   source?: "default" | "project" | "global"
+  /** Path of the .md it was loaded from. Unset for embedded defaults. */
+  sourcePath?: string
 }
 
 export type JoinMode = "async" | "group" | "smart"

package/node_modules/@narumitw/pi-btw/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@narumitw/pi-btw/README.md

@@ -0,0 +1,210 @@
+# 💬 pi-btw — Side Questions for the Pi Coding Agent
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-btw)](https://www.npmjs.com/package/@narumitw/pi-btw) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`@narumitw/pi-btw` is a native [Pi coding agent](https://pi.dev) 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 or resuming an in-memory side thread or changing pi-btw settings.
+- Keeps `/btw <question>` as a direct fast path that always starts a fresh side thread.
+- Answers side questions in a dedicated, scrollable full-screen UI.
+- Keeps mouse-drag copying stable while the main agent continues running in the background.
+- Supports follow-up questions in the same ephemeral side thread.
+- Resumes any non-empty side thread retained by the current Pi session, listed by its first question.
+- Queues Pi-style `Steering` questions while an answer is running and processes them one at a time.
+- 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
+
+```bash
+pi install npm:@narumitw/pi-btw
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:@narumitw/pi-btw
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./packages/pi-btw
+```
+
+## 🚀 Usage
+
+Open the pi-btw menu or provide the first question immediately:
+
+```text
+/btw
+/btw <your side question>
+```
+
+Examples:
+
+```text
+/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 menu with **Start side thread** selected first. When the current Pi
+session has non-empty side threads in memory, **Resume side thread** opens a bounded choice list;
+**Settings** changes the starting thinking level and whether shortcut changes are remembered.
+Each Resume row keeps the first question as its fixed title, shows its question count, and the list
+is ordered by the newest recorded answer or visible error. Opening and closing a thread without a
+new result does not reorder it. `/btw <question>` bypasses this menu and always starts a fresh side
+thread. Its answer opens above the side-thread editor. The side thread uses a dedicated full-screen
+terminal view.
+The main agent continues running in the background, but its screen rendering stays suspended until
+`/btw` closes, so new main-thread output cannot move a mouse selection inside the side thread.
+Drag the primary mouse button across side-thread text to select and copy it through Pi's terminal
+clipboard support. Returning from `/btw` redraws the main view with everything produced while it
+was hidden. 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 and composer remain visible above an `Answering…`
+status.
+Type another question and press `Enter` to queue it as `Steering`; queued questions are shown in
+submission order and answered one at a time after the active response completes.
+A queued question uses the side thread's thinking level when its turn begins.
+A failed active response is shown in the transcript and does not discard later steering questions.
+The footer shows `PgUp`/`PgDn` only when history can scroll; press `Ctrl+C` to cancel the active
+response and discard the ephemeral side-thread draft and steering queue. Completed questions,
+answers, and visible errors remain available through Resume until the current extension instance
+ends. Steering remains entirely inside pi-btw and never appends to the main conversation or editor.
+
+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` never adds the side thread to the main
+conversation. Non-empty threads remain only in memory for Resume within the current Pi session.
+`/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard every retained
+thread. Unsent drafts, steering queues, interrupted answers, and model credentials are never retained.
+
+## ⚙️ Model and thinking level
+
+By default, `/btw` uses the current session model. To use an independent model for side
+questions, create:
+
+```text
+$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.
+
+```json
+{
+  "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
+
+```txt
+packages/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`:
+
+```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`](./LICENSE).