English | 简体中文

pi-ui-extension

A fullscreen terminal UI extension for Pi Coding Agent. Manage sessions, inspect context usage, view Tool/MCP activity, and keep tool transcripts readable—all from one sidebar.

Requires Pi fullscreen mode. Use pi --tui-mode fullscreen if fullscreen is not already your default. The sidebar is not supported in regular TUI mode.

Preview

Quick start

Install from npm (recommended):

pi install npm:pi-ui-extension

Start Pi in fullscreen mode. The right sidebar appears automatically. To install a specific release instead:

pi install npm:pi-ui-extension@1.7.2

Pinned packages do not automatically move to newer versions. See Installation and updates for Git, local and removal options.

Features

The sidebar consists of three panels:

Panels support mouse interaction, scrolling, terminal resizing, and smaller terminal windows.

Centered dialogs: Session management, bulk cleanup, renaming, resource/MCP browsing, and the Tool View picker now use consistent theme-aware, centered overlays. Select with ↑/↓ and Enter, cancel with Esc; resource details are read-only and scrollable. Trash confirmation starts at Cancel; the sidebar × and advanced manager both require explicit confirmation before moving a session to trash. Pi 1.1.0/1.2.0 are supported.

Sessions and resource shortcuts

The SESSIONS panel lists recent project sessions. Click a session to switch, or use its actions to rename, pin/unpin (☆ / ★), delete, and refresh (↻). Pinned sessions appear first. The number beside each title represents user questions, not Pi's total message count; assistant/tool messages are excluded. For example, 3 · 55m means three questions and an update 55 minutes ago. Unreadable sessions display ?.

Open Advanced Sessions with ≡ or /sessions-manager to:

• Search titles/IDs, sort by last updated, question count, or title, and browse all sessions in pages of eight.
• Switch, rename, pin/unpin, or move an individual session to trash (confirmation required).
• Bulk-clean eligible sessions with ⊗, keeping current, pinned, recently modified, and known active sessions safe.

Deletion safeguards: The current session cannot be deleted. Mutating session operations require Pi to be idle. Bulk cleanup excludes sessions modified in the last 5 minutes, and sessions advertised as active by other Pi instances running this extension. Immediately before moving a file to trash, the extension checks its identity, modification time, and protection state again. Pi instances without this extension cannot be detected reliably; avoid bulk cleanup while they may be using saved sessions. Single-session deletion requires confirmation but does not use the five-minute bulk-cleanup grace period.

The bottom of SESSIONS provides these resource shortcuts:

• AGENTS.md — active instruction resources.
• Skills — discovered agent skills.
• Extensions — installed or loaded extensions.
• MCP — configuration and observable runtime status.

The MCP Status Center is read-only. It shows global/trusted-project configurations, extension-registered servers, and health when explicitly reported by a supported adapter. Configured, registered, or loaded does not mean connected. Credentials, environment values, commands, and raw errors are not exposed. Use Pi's /mcp manager for connection diagnostics, authentication, and changes; the status center cannot perform these operations.

CTX: context and performance

The CTX panel shows:

• Current model, Thinking level, context window/usage, current-run context delta, and image count.
• Context composition: System, Tools, Messages, Tool Results, Summary, and Other.
• Run turns/time, average TTFT and TPS, the latest TTFT, and available cache metrics.

Token composition is a local heuristic estimate, not exact provider tokenization or billing usage. The extension uses observable provider tool definitions when available; before a provider request, it estimates enabled Pi tool schemas. See Architecture for measurement and refresh details.

VIEW: tool transcripts and Thinking

One selector controls both tool output and Thinking; the default is Compact.

Switch with the sidebar buttons or /tool-view normal|compact|hidden|status. The selection is persisted and refreshes existing transcript rows in the current session. It only changes presentation—not model reasoning, tool execution, saved session data, or usage counting.

In Compact, supported built-in tools (read, bash, edit, write, grep, find, ls, and codemode) use Claude-style indentation, ›/⌄ chevrons, and a muted ⎿ result branch:

Thinking · 0.7s
  ›  codemode
    ⎿  1 call · 1 ok │ 59 lines · 85ms
  ›  bash  git status
    ⎿  12 lines · 45ms

Output counts use line/lines (falling back to out on narrow terminals); the duration and metric separator are less prominent and spacing is tighter. Each tool call has its own summary; calls are never merged. Success, running, partial failure, and failure remain distinct. Click any supported tool's › chevron, including Codemode, to expand Pi's native details (script, nested calls, output, or errors); click ⌄ to collapse back to the Compact summary. Normal also supports native details. Third-party tools and special native renderers are left intact.

Thinking duration measures the observable Thinking phase, not the whole response. Live time is prefixed by ~; if reliable timing is unavailable (e.g. after restoring a session), only Thinking is shown. Compact/Hidden Thinking labels are read-only on verified Pi versions; clicking them does not expand private text.

Important: Set Pi's native hideThinkingBlock to false (or enable native Thinking visibility) for the extension's Compact/Hidden Thinking summary to appear. Pi's native hidden placeholder takes precedence otherwise.

Compact's tighter tool spacing and click protection have been verified for Pi 1.1.0 and 1.2.0. They use narrowly scoped, version-checked compatibility adapters for host UI components, rather than changing tool execution. Unsupported host layouts fall back to Pi's native behavior. Normal and Hidden retain their own layouts. Implementation details are in Architecture.

Tool / MCP usage statistics

Below VIEW, tools are grouped by execution source:

RUN is activity in the current agent run; TOTAL accumulates activity in the active session branch. A Codemode parent is counted once in Direct, with its child calls separately in Nested. Do not add MCP totals to Direct + Nested, as that double-counts attributed calls. Counters are reconstructed on session/branch changes where data is available. The list remains scrollable on narrow terminals.

Footer

A compact footer displays the current working directory and Git branch (when available), truncating long paths to fit the terminal.

Installation and updates

For day-to-day usage, prefer npm. Git is available for unreleased repository changes or when you want to track a branch directly.

Pi stores global package declarations in ~/.pi/agent/settings.json. Project-local installation writes <project>/.pi/settings.json and requires Pi to trust the project. Pinning a version stops automatic movement to newer releases.

For one-off local source testing, from the repository root (without changing installed package declarations):

pi --no-extensions -e builtin:mcp -e ./extensions/index.ts --tui-mode fullscreen

--no-extensions prevents loading the installed copy a second time; the explicit -e entries remain active.

Compatibility and troubleshooting

• Requirements: Pi Coding Agent supporting registerToolRenderer(); Node.js >= 22.19.0. CI tests Node 22.19.0/24 with Pi 1.1.0/1.2.0.
• No sidebar: Confirm fullscreen mode and terminal width; regular TUI is not supported for the sidebar.
• Missing Thinking summary: Check Pi's native hideThinkingBlock flag and the selected VIEW mode.
• Uncertain MCP connection: Only adapter-reported connections are confirmed; use /mcp for diagnostics.
• Unexpected Pi version: Run command -v pi, pi --version, and pi list. Bun and npm global installations may coexist; the executable selected by your shell determines the active host. Do not remove other installations without checking dependencies.
• Compatibility approach: No Pi Core files or tool execution methods are rewritten. Public extension APIs are preferred; version-checked host UI guards are used for specific mouse/spacing behavior and fail back to native presentation if unsupported.

Development and release

git clone https://github.com/1993yihuan/pi-ui-extension.git
cd pi-ui-extension
npm ci
npm run check

• Development guide — project layout, testing, CI, OIDC publishing, and release procedure.
• Architecture notes — stats, Thinking, session protection, MCP state, and Pi compatibility details.

This package is published with the pi-package keyword for discovery in the Pi Package Catalog. The npm package declares the preview image above for gallery use.

License

MIT.