English | 简体中文

pi-ui-extension

pi-ui-extension is a terminal UI enhancement package for Pi Coding Agent. It adds a right-side information sidebar, session management, context inspection, tool/MCP usage tracking, and a compact footer without modifying Pi Core.

The package can be installed from npm or Git, and uses GitHub Actions for type checking, automated tests, and npm Trusted Publishing via OIDC.

[!IMPORTANT] pi-ui-extension is designed for Pi fullscreen mode. Please run Pi in fullscreen mode when using this extension. In non-fullscreen mode, sidebar panels, layout sizing, and related UI behavior may be unavailable or displayed incorrectly.

Preview

Features

1. Right-side Sidebar

The extension mounts a right-side sidebar in Pi's fullscreen TUI. It contains three default panels:

• SESSIONS: recent sessions and resource shortcuts.
• CTX: model, context window, composition estimates, and runtime performance.
• TOOL VIEW: tool transcript display modes and Tool/MCP usage statistics.

The sidebar supports mouse interaction, wheel scrolling, and terminal resize handling. Panels shrink or become scrollable when vertical space is limited.

The sidebar depends on Pi fullscreen mode. Non-fullscreen mode is not a supported display mode for this extension; sidebar panels, layout sizing, and related UI behavior may be unavailable or displayed incorrectly.

2. Session management

The SESSIONS panel provides quick access to recent sessions:

• Click a session to switch to it.
• Rename a non-current session.
• Delete a non-current session.
• Use the ⊗ action to remove all other sessions.
• Click SESSIONS ↻ to refresh the session list.

To avoid corrupting active agent state, switching, renaming, deleting, and bulk cleanup are only allowed while Pi is idle. The current session cannot be deleted.

3. Resource shortcuts

The bottom of the SESSIONS panel exposes four resource categories:

• AGENTS.md
• Skills
• Extensions
• MCP

These shortcuts let you inspect the resources currently loaded by the project/Pi environment, making it easier to verify which agent instructions, skills, extensions, and MCP servers are actually available.

4. CTX context inspection

The CTX panel shows context and runtime information for the current model request, including:

• Current model name.
• Thinking level.
• Pi context usage / context window.
• Current-question context delta relative to the previous settled state.
• Context composition estimates.
• Image count.
• Turn count and run duration.
• Average TTFT (Time To First Token).
• Average TPS (Tokens Per Second).
• Latest observed TTFT with speed label.
• Cache-related metrics when observable.

Context composition is grouped into:

• System
• Tools
• Messages
• Tool Results
• Summary
• Other

Token counts are local heuristic estimates intended for composition and trend visibility. They are not provider-accurate tokenizer results and are not billing-token counts.

For tool definitions, the extension prefers the observable provider-request tool payload when available. Before a provider request exists, it falls back to estimating the schemas of Pi's currently enabled tools.

5. Tool View modes

TOOL VIEW supports three transcript display modes:

• Normal: standard tool transcript rendering.
• Compact: denser tool output rendering.
• Hidden: hide tool transcripts.

Modes can be changed directly with mouse clicks.

When Fabric takes ownership of tool rendering, the panel remains visible for usage statistics but the local mode selector is hidden and replaced with View controlled by Fabric. This avoids conflicting display control.

6. Tool / MCP usage statistics

Tool View groups usage into:

• TOOLS
• MCP

Each entry is shown as:

current-question calls / current-session calls

Example:

task_todos                         1/5

Usage state is rebuilt when the active branch changes, so restored sessions and branch switches do not blindly reuse counts from another branch.

For calls made through MCP gateways, mcpScript, and similar wrappers, the extension attempts to attribute activity to the actual MCP server instead of counting only the outer wrapper tool.

7. Footer

The extension replaces the default footer with a compact view that displays:

• Current working directory.
• Current Git branch, when available.

The path is automatically truncated to fit terminal width.

Pi Package Catalog

This package is published to npm with the pi-package keyword and a Pi manifest, so it can be discovered by the Pi package catalog at pi.dev/packages. The package metadata also declares the preview image shown above for catalog/gallery presentation.

Installation

Recommended: install from npm

pi install npm:pi-ui-extension

Pi installs the package and writes the declaration to:

~/.pi/agent/settings.json

Example configuration:

{
  "packages": [
    "npm:pi-ui-extension"
  ]
}

To pin a specific version:

pi install npm:pi-ui-extension@1.1.1

or:

{
  "packages": [
    "npm:pi-ui-extension@1.1.1"
  ]
}

Pinned packages do not automatically move to newer versions.

Install from GitHub

You can also install directly from the Git repository:

pi install git:github.com/1993yihuan/pi-ui-extension

Configuration form:

{
  "packages": [
    "git:github.com/1993yihuan/pi-ui-extension"
  ]
}

Pin to a Git tag:

pi install git:github.com/1993yihuan/pi-ui-extension@v1.1.1

Temporary usage

To load the package for a single Pi launch without modifying settings.json:

pi -e npm:pi-ui-extension

Project-local installation

To enable the package only for the current project:

pi install --local npm:pi-ui-extension

The declaration is written to:

<project>/.pi/settings.json

Project-local packages are loaded only after the project is trusted by Pi.

Update and removal

Update unpinned extensions:

pi update --extensions

List configured packages:

pi list

Remove the npm source:

pi remove npm:pi-ui-extension

If installed from Git, remove the corresponding Git source:

pi remove git:github.com/1993yihuan/pi-ui-extension

npm or Git?

For normal usage, npm is recommended:

npm:pi-ui-extension

It provides clear SemVer versioning, predictable installation, and easy version pinning.

Use Git when you want to follow the latest repository state or test changes that have not yet been published to npm:

git:github.com/1993yihuan/pi-ui-extension

For active local development, loading a local checkout is usually faster than committing, pushing, and updating on every change.

Local development

Clone the repository:

git clone https://github.com/1993yihuan/pi-ui-extension.git
cd pi-ui-extension

Install dependencies:

npm ci

Run the full validation suite:

npm run check

Equivalent commands:

npm run typecheck
npm test

The test suite covers the main behavior of Sidebar, CTX, Session management, Tool View, MCP resources, Fabric detection, mouse scrolling, and resize handling.

During development, Pi can load the local source directory directly:

pi install ./path/to/pi-ui-extension

Or load it temporarily for one run:

pi -e ./path/to/pi-ui-extension

Package structure

pi-ui-extension/
├── extensions/
│   ├── ctx/                 # Context composition, delta, runtime metrics
│   ├── footer/              # Footer
│   ├── mcp/                 # MCP resource / usage integration
│   ├── session/             # Session list and actions
│   ├── sidebar/             # Sidebar layout, scrolling, resize
│   ├── tool-view/           # Tool View modes and usage statistics
│   ├── fabric-detection.ts  # Fabric ownership detection
│   └── index.ts             # Pi Extension entry point
├── .github/workflows/
│   ├── ci.yml               # Automatic checks on push / PR
│   └── release.yml          # npm publishing + GitHub Release on tags
├── package.json
└── tsconfig.check.json

Pi's extension entry point is declared explicitly in package.json:

{
  "pi": {
    "extensions": [
      "./extensions/index.ts"
    ]
  }
}

CI / Release

Every push to main and every pull request runs:

npm ci
→ npm run typecheck
→ npm test

To publish a release, create a version tag, for example:

npm version patch
git push
git push --tags

A v* tag triggers the release workflow:

Checkout
→ Node.js 24
→ npm ci
→ npm run check
→ verify tag == package.json version
→ npm pack --dry-run
→ npm Trusted Publishing (OIDC)
→ npm publish
→ GitHub Release

npm publishing uses GitHub Actions OIDC Trusted Publishing, so no long-lived NPM_TOKEN is required in the repository.

Compatibility and design principles

• Does not modify Pi Core.
• @earendil-works/pi-coding-agent and @earendil-works/pi-tui are host-provided peer dependencies to avoid duplicate runtime instances.
• Fabric ownership is detected explicitly to avoid conflicting Tool View controls.
• Session and resource operations use Pi public APIs wherever possible.
• Context composition is clearly presented as an estimate, not provider-exact token accounting.
• Fullscreen sidebar behavior degrades safely when fullscreen layout is unavailable.

Requirements

• Pi Coding Agent
• Node.js >= 22.19.0 (use a Node version supported by your Pi installation)
• Development and CI currently use Node.js 24

License

This project is licensed under the MIT License.