pi-blackbox

中文说明

pi-blackbox records every model-issued tool call in the current Pi session, shows the live count in Pi's footer, and provides an interactive /blackbox inspector.

Features

• Counts every tool_call event, including built-in tools such as read, write, edit, and bash, plus tools registered by other extensions.
• Reconstructs tool calls from the current session branch after resume, fork, or tree navigation.
• Publishes the blackbox extension status as <count> tool calls through Pi's native ctx.ui.setStatus() data source and displays it on the native statistics row with the same dim color.
• Opens a viewport-sized /blackbox inspector with a fixed header and shortcut footer; press Enter to expand the selected call's complete arguments from their beginning.
• Sends the selected call to the current session model for a concise explanation in the configured language without adding anything to the conversation.
• Detects Chinese or English from the operating system on first launch and persists the choice in ~/.pi/agent/extensions/blackbox.json.

Install

As a published Pi package:

pi install npm:pi-blackbox

During local development:

pi install ./pi-blackbox

Alternatively, try it without installing:

pi -e ./pi-blackbox/src/index.ts

Run /reload in an existing Pi session after installing or changing the extension.

Usage

Enter /blackbox to see the newest tool call at the top. The title shows the active order. Then use:

| Key | Action | | --- | --- | | Up / Down | Select a tool call | | j / k | Move down/up; scroll a selected expanded item when it is taller than the viewport | | Enter | Expand or collapse its complete arguments | | e | Ask the current Pi model to explain its actual effect | | r | Reverse between newest-first and oldest-first order | | q, Esc, or Ctrl+C | Close the view |

The explanation prompt asks for a short and precise account of what the call reads, writes, creates, deletes, executes, or otherwise affects. It forbids execution and unsupported guesses; a short example is allowed only when the call is complex. The selected tool name and arguments are sent to the currently selected model.

Run /blackbox-explain-language to choose Auto-detect, a common language, or Other and enter any language name. The selection is persisted in ~/.pi/agent/extensions/blackbox.json:

{
  "explainLanguage": "Chinese"
}

On first launch, macOS reads AppleLanguages, Linux reads LC_ALL / LC_MESSAGES / LANG, and Windows reads the current user's preferred language list before trying PowerShell 7 (pwsh.exe), Windows PowerShell, and terminal locale variables. If the platform-specific source is unavailable, detection falls back to Intl. Automatic detection selects Chinese for a Chinese locale and English otherwise. Choosing Auto-detect reruns detection and saves the result.

pi-powerline-footer

Pi's default footer displays the count directly after its token/context statistics instead of on a separate extension-status row. To promote the same blackbox status to a dedicated pi-powerline-footer segment, merge this into ~/.pi/agent/settings.json (or the active project .pi/settings.json):

{
  "powerline": {
    "preset": "default",
    "customItems": [
      {
        "id": "blackbox",
        "statusKey": "blackbox",
        "position": "right",
        "color": "accent",
        "hideWhenMissing": true,
        "excludeFromExtensionStatuses": true
      }
    ]
  }
}

The displayed value remains exactly <count> tool calls; no prefix is added. hideWhenMissing keeps the item invisible when pi-blackbox is not loaded, while excludeFromExtensionStatuses prevents a duplicate in the aggregate extension-status segment.

If you already use powerline.customItems, append the object above instead of replacing the array. Restart Pi or run /reload after editing the settings.

Development

npm install
npm run verify