jitsusama/extension-dev-guide

Pi Extension Development

Discovery Workflow

Before building any UI, follow this sequence:

1. Read Pi's TUI docs for patterns and available components. The main Pi documentation is listed in the system prompt under "Pi documentation" — read docs/tui.md from there. Follow links to related docs as needed.

2. Read the type declarations for the specific component you need. The @mariozechner/pi-tui package's dist/index.d.ts and dist/components/*.d.ts files show the exact API surface.

3. Read the higher-level components exported by @mariozechner/pi-coding-agent in its dist/modes/interactive/components/index.d.ts.

4. Check this project's lib/ui/ for existing abstractions built on top of Pi's primitives. The barrel at lib/ui/index.ts shows the public surface. Don't duplicate what's already there.

5. Browse Pi's examples for working implementations. The examples directory is listed in the system prompt.

Architecture: Extensions vs Library

Extensions and library code serve different roles. See AGENTS.md's "Integration Architecture" section for the full pattern. The short version:

• lib/ holds domain logic: API clients, authentication, renderers, types and UI components. This is reusable code that other Pi packages can import.
• extensions/ holds Pi-specific wiring: tool registration, renderCall/renderResult, slash commands, confirmation gates, session state and lifecycle.

When building an integration, the extension should be a thin consumer of its library. Caching belongs in the extension; the library stays stateless.

When building a guardian or workflow, shared logic goes in lib/internal/. See AGENTS.md for the full guidelines on public vs internal code.

What's Available (Orientation Only; Verify Against Source)

From @mariozechner/pi-tui:

| Need | Component | |------|-----------| | Group children vertically | Container | | Padded container with background | Box | | Display text with word wrap | Text | | Display text truncated to width | TruncatedText | | Render markdown | Markdown | | Empty vertical space | Spacer | | Single-line text input | Input | | Multi-line editor with autocomplete | Editor | | Pick from a list | SelectList | | Toggle settings | SettingsList | | Spinner animation | Loader | | Cancellable spinner with AbortSignal | CancellableLoader | | Display an image | Image | | Key detection | matchesKey, Key | | Text width / truncation / wrapping | visibleWidth, truncateToWidth, wrapTextWithAnsi | | Fuzzy search | fuzzyMatch, fuzzyFilter |

From @mariozechner/pi-coding-agent:

| Need | Component | |------|-----------| | Full-width border line | DynamicBorder | | Bordered spinner with cancel | BorderedLoader | | Custom editor with app keybindings | CustomEditor | | Coloured diff output | renderDiff | | Syntax highlighting | highlightCode, getLanguageFromPath | | Pre-built themes for components | getMarkdownTheme, getSelectListTheme, getEditorTheme, getSettingsListTheme | | Keybinding hint formatting | keyHint, appKeyHint, rawKeyHint | | Visual line truncation | truncateToVisualLines |

From ctx.ui (ExtensionUIContext):

| Need | Method | |------|--------| | Selection dialog | select() | | Yes/no confirmation | confirm() | | Text input dialog | input() | | Multi-line editor dialog | editor() | | Toast notification | notify() | | Footer status indicator | setStatus() | | Loading message during streaming | setWorkingMessage() | | Persistent widget above/below editor | setWidget() | | Replace footer | setFooter() | | Replace header | setHeader() | | Full custom component | custom() | | Overlay (floating component) | custom() with { overlay: true } | | Replace the input editor | setEditorComponent() | | Manipulate editor text | setEditorText(), getEditorText(), pasteToEditor() | | Theme access | theme property | | Tool output expansion | getToolsExpanded(), setToolsExpanded() | | Terminal title | setTitle() | | Raw terminal input | onTerminalInput() |

From this project's lib/ui/ (barrel: lib/ui/index.ts):

| Need | Export | |------|--------| | Interactive single-choice panel | promptSingle | | Interactive tabbed panel | promptTabbed | | Read-only content display | view | | Stateful workspace prompt | workspace | | Markdown/diff/code rendering | renderMarkdown, renderDiff, renderCode | | Navigable list rendering | renderNavigableList, renderNavigableSections | | Text wrapping | contentWrapWidth, wordWrap |

Internal files not in the barrel (redirect.ts, tab-completion.ts, navigable-list.ts input handler, text-layout.ts, panel-height.ts) can be imported directly by extensions in this package when needed.

Gotchas

These are design decisions in Pi that aren't obvious from the type signatures. They'll cause real bugs when you miss them.

Each Render Line Must Be ≤ Width

render(width) must return lines no wider than width visible characters. Use truncateToWidth() on every line. ANSI escape codes don't count toward width, but wide characters (CJK, emoji) count as 2.

Always Use Theme from the Callback

Never import theme directly. Pi's module caching means the global theme may be undefined in extension code loaded via jiti. Always grab the theme parameter from:

• ctx.ui.custom((tui, theme, kb, done) => ...)
• renderCall(args, theme)
• renderResult(result, options, theme)

Type the DynamicBorder Colour Parameter

// Correct: explicit type annotation
new DynamicBorder((s: string) => theme.fg("accent", s))

// Wrong: jiti inference fails
new DynamicBorder((s) => theme.fg("accent", s))

Call tui.requestRender() After State Changes

The TUI doesn't auto-render. After modifying state in handleInput, call tui.requestRender() to trigger a redraw.

Implement invalidate() for Theme Changes

When the theme changes, the TUI calls invalidate() on all components. If you've baked theme colours into cached strings (via theme.fg(), theme.bg()), you need to rebuild them in invalidate(). See the "Rebuild on Invalidate" pattern in Pi's tui.md.

Overlay Components Are Disposable

Create fresh instances each time; never reuse a reference after the overlay closes because the component is disposed when it closes.

Propagate Focusable for IME Support

Container components that embed Input or Editor must implement the Focusable interface and propagate the focused property to the child. Without this, IME candidate windows (CJK input) show up in the wrong position.

Text(content, 0, 0) Inside Box

When placing Text inside a Box, use 0,0 padding on the Text. The Box handles padding. Double-padding is a common mistake.

Dialogs Support Timeout and Signal

All dialog methods (select, confirm, input) accept an options object with timeout (auto-dismiss with countdown) and signal (AbortSignal for manual dismiss).