pi-btw-sidecar

Persistent /btw side conversations for the Pi coding agent.

pi-btw-sidecar opens a focused, non-capturing modal sidecar session, keeps BTW discussion separate from the main transcript, and can inject or summarize the side conversation back into the main session on request.

• npm: https://www.npmjs.com/package/pi-btw-sidecar
• GitHub: https://github.com/MasuRii/pi-btw-sidecar

Features

• /btw contextual side thread with current main-session context.
• /btw:tangent contextless tangent thread.
• Modal BTW composer with streaming markdown transcript, scrolling, and Escape dismissal.
• Agent selection from agent/agents/*.md via /btw:agent; the selected agent markdown body becomes the sidecar instruction prompt.
• BTW-only model and thinking overrides with /btw:model and /btw:thinking.
• Isolated no-tool sub-sessions: BTW agents receive selected instructions and seeded conversation context without tools, skills, prompts, agents files, themes, extension resource collections, or inherited main-session system prompts.
• Debug logging controlled by root config.json, with logs written only under extension-local debug/ when enabled.

Installation

npm package

pi install npm:pi-btw-sidecar

Git repository

pi install git:github.com/MasuRii/pi-btw-sidecar

Local extension folder

Place this folder in one of Pi's extension discovery paths:

# Global default when PI_CODING_AGENT_DIR is unset
~/.pi/agent/extensions/pi-btw-sidecar

# Project-specific
.pi/extensions/pi-btw-sidecar

Pi discovers the extension through the root index.ts entry listed in package.json, which forwards to src/btw-runtime.ts.

Commands

| Command | Description | | --- | --- | | /btw [prompt] | Open or continue the contextual BTW thread. Add --save to persist a visible note. | | /btw:tangent [prompt] | Open or continue a contextless tangent thread. | | /btw:agent [name\|list] | Pick, list, or set the BTW instruction agent. | | /btw:new [prompt] | Reset BTW and start a fresh contextual thread. | | /btw:clear | Clear BTW state and dismiss the modal. | | /btw:inject [instructions] | Inject the full BTW thread into the main session. | | /btw:summarize [instructions] | Summarize the BTW thread and inject the summary. | | /btw:model [provider model api\|clear] | Show, set, or clear the BTW-only model override. | | /btw:thinking [level\|clear] | Show, set, or clear the BTW-only thinking override. |

Configuration

Runtime configuration is stored at the extension root:

~/.pi/agent/extensions/pi-btw-sidecar/config.json

A starter template is included at config/config.example.json. Missing config.json or missing keys fall back to production defaults.

cp config/config.example.json config.json

Configuration options

| Key | Type | Default | Purpose | | --- | --- | --- | --- | | debug | boolean | false | Enables debug logging under debug/debug.log. | | showReasoning | boolean | true | Shows sidecar assistant reasoning text when Pi exposes it. | | modalSize | "small" \| "medium" \| "large" | "medium" | Controls the default BTW modal size. |

Example:

{
  "debug": false,
  "showReasoning": true,
  "modalSize": "medium"
}

Invalid values are reported through Pi diagnostics and replaced with bounded defaults.

Debug logging

Debug logging is disabled by default through "debug": false. When enabled, logs are appended only to:

debug/debug.log

The extension does not write debug output to console, stdout, or stderr, and no debug directory or log handle is created when debug logging is disabled.

Repository structure

pi-btw-sidecar/
├── index.ts                         # Stable Pi extension entrypoint for auto-discovery
├── src/
│   ├── btw-runtime.ts               # Command registration and sidecar session orchestration
│   ├── agent-discovery.ts           # Agent markdown discovery and selection state
│   ├── agent-selection-ui.ts        # `/btw:agent` picker UI helpers
│   ├── config.ts                    # Config loading, validation, and defaults
│   ├── debug-logger.ts              # File-only debug logger gated by config.json
│   └── icons.ts                     # Modal icon fallbacks
├── src/test/
│   └── btw-runtime.test.ts
├── config/
│   └── config.example.json          # Starter config template
├── CHANGELOG.md
├── LICENSE
├── package.json
├── README.md
└── tsconfig.json

Development

npm install
npm run build
npm run lint
npm run test
npm run check
npm run package:dry-run

Publishing

The package metadata follows the publish-ready shape used by established Pi extensions:

• entrypoint: index.ts
• package exports: . → ./index.ts
• Pi extension manifest: pi.extensions
• repository, bugs, and homepage links target MasuRii/pi-btw-sidecar
• published files: source, README, changelog, license, and config template
• runtime config.json, debug/ logs, tests, and build artifacts excluded from npm publication

Do not publish, push, or tag until the GitHub repository has been manually reviewed.

Changelog

See CHANGELOG.md for version history.

License

MIT © MasuRii