pi-better-btw-plus

English | 简体中文

A side-chat overlay for pi, the coding agent. While the main agent keeps working, /btw forks the current conversation into its own overlay — ask about an API detail, sanity-check an approach, get an answer, close it. The main thread is never interrupted.

Features

The side chat

• Non-blocking fork — the side chat is a fresh agent cloned from your current session, rendered in a top overlay. The main editor stays visible underneath and keeps running.
• Read-only by default — out-of-lane tool calls are hard-blocked (a second violation escalates and aborts the turn); peek_main reads the main session's recent activity on demand; Alt+T switches to edit mode.
• Prefix-cache friendly — the side request shares the main session's context, so it hits the gateway's prefix cache and stays fast and cheap.
• Conversation tools — re-fork from the latest context (Alt+R), start an empty conversation (Alt+N), background without losing state (Alt+W), export the transcript (Alt+E), override any injected prompt with a prompt pack.
• Write-overlap guard — files the main session has written while the side chat is open are protected: writing to one of those paths asks for confirmation first.

Aligned with pi

No custom interaction language — shortcuts and behavior follow pi's own conventions, so the side chat feels like the main session:

• Shortcuts mirror the main session — copy/clear, paste, last-message copy, model picker and keymap screen follow pi's official bindings (tui.input.copy, app.clear, app.clipboard.pasteImage, app.message.copy, app.model.select, app.tools.expand). When a key collides, pi wins: Alt+T toggles mode so Ctrl+T stays pi's thinking toggle.
• Behavior matches the main session — retry, overflow handling, clipboard and model selection work exactly like pi itself, and the overlay follows pi's own window geometry.

Terminal muscle memory, re-implemented

The overlay owns the terminal's mouse while open, so conveniences the main session inherits from Windows Terminal or AgentSession are rebuilt inside it:

While the overlay is open it owns the mouse over its region: wheel scrolls, drag selects, right-click copies or pastes. Both TUI modes behave identically — fullscreen (default) routes fork-surface events through pi's component dispatch, regular mode captures the raw reporting stream. Background it (Alt+W) and the covered region's mouse returns to pi.

Input editor selection

• Drag — select a range with a live inverse-video highlight (~30fps).
• Double-click — select the word under the cursor; triple-click — the whole visual line.
• Selections are transient (typing or moving the cursor clears them), never cross a [paste #N …] marker, and are disabled while the autocomplete popup is open.

Install & quick start

pi install npm:pi-better-btw-plus

In pi's TUI, open the side chat with /btw (or the original /side) or Alt+W. Ask, press Enter, close with Esc. Reopening continues the same conversation.

[!NOTE] Verified against pi 1.3.0.

Keybindings

Commands

• /btw, /side — open the side chat (both are registered, aliases of each other; /btw is the project's namesake, /side the original name).
• peek_main — available to the side agent only; reads the main session's recent activity. lines (default 20, max 50), since_fork (only activity after the side chat opened).

Configuration

config.json is read from three layers; a later layer overrides earlier ones per key:

• features — kill switches: rightClickCopyPaste, modelSwitch, retry, editorSelection default to true; fullscreenCopyOnSelect (spec #37) defaults to false and mirrors pi's copy-on-release inside the fork when enabled in fullscreen mode.
• readOnlyExtensionAllowlist — extension tools allowed in the read-only lane. Lists union across layers; the builtin read/grep/find/ls and peek_main are always included.
• readOnlyExtensionAllowlistExclude — remove bundled defaults.
• promptPack — override any injected prompt (framing, focus anchor, lane reminders) with your own markdown files; missing keys fall back to the bundled prompts/.

{
  "readOnlyExtensionAllowlist": ["pi-vision-helper"],
  "features": { "editorSelection": false }
}

How it works

• The side chat is a fresh agent cloned from your current session, rendered in a top overlay — the main editor stays visible and keeps running underneath.
• Read-only mode (default) is enforced: an out-of-lane tool call is blocked, and a second violation escalates and aborts the turn. peek_main reads the main session's recent activity on demand.
• While the overlay is open it owns the mouse: wheel scrolls, drag selects, right-click copies or pastes. Backgrounding (Alt+W) returns the mouse to the terminal.

Development

pi loads TypeScript directly — there is no build step. Point pi's extension loader at ./srcs/index.ts (the entry point; the rest of srcs/ holds the overlay, lane enforcement, retry and clipboard code) and run /reload after edits.

bun install
bun run typecheck
bun test

Limitations

• One side chat at a time; won't open on top of another visible overlay.
• Doesn't merge messages back into the main thread.
• Bash overlap detection is heuristic — catches common write patterns, not all.
• peek_main is on-demand, not live.
• Mouse interaction works only in the regular (non-fullscreen) TUI mode.

License & origin

MIT — see LICENSE. This project is a maintained fork of @yceachan/pi-better-btw, itself a fork of nicobailon/pi-side-chat. All three copyright lines are retained: Nico Bailon, yceachan, hu3rror.