pi-local-trace-viewer

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Pi Local Trace Viewer

[中文文档](https://github.com/xwcq/pi-local-trace-viewer/blob/HEAD/README.zh-CN.md)

A local, read-only execution viewer for the [Pi coding agent](https://pi.dev). It captures complete LLM requests and final responses, tool requests and final results, and displays them in a separate browser process without adding debug output to the prompt.

The extension intentionally ignores streaming token deltas and intermediate tool progress. It focuses on the semantic request/response chain.

## Install

From npm:

```bash
pi install npm:pi-local-trace-viewer
```

From GitHub:

```bash
pi install git:github.com/xwcq/pi-local-trace-viewer
```

Try it for one Pi run without installing:

```bash
pi -e npm:pi-local-trace-viewer
```

Pi packages execute code with the same system access as Pi. Review extension source before installing third-party packages.

## Usage

Start Pi normally. The Viewer starts as a separate localhost process and opens automatically by default.

```text
/trace-viewer status
/trace-viewer open
/trace-viewer on
/trace-viewer off
```

`on` and `off` update the current session immediately and persist the setting globally in `~/.pi/agent/trace-viewer.json`, so future sessions inherit it. If persistence fails, Pi continues and reports that only the current session changed.

A new session started while disabled does not launch or auto-open the Viewer. Turning observation off in an active session stops new capture but leaves its existing Viewer available for historical inspection until the session ends; turning it on starts the Viewer on demand.

The extension intentionally does not register `/trace`, avoiding conflicts with other trace extensions.

## What the Viewer shows

The left tree groups one user message and all work required to produce the user-facing answer into an Interaction:

```text
Interaction N（first user input characters…）
└── ReAct Round 1
    ├── LLM request
    ├── LLM response
    ├── Tool request
    └── Tool response
```

An Interaction can contain multiple ReAct Rounds when the model requests tools before returning the final answer. A new user or steering message starts a new Interaction.

The right panel renders system, user, assistant, tool-call, and tool-result messages as structured cards. Text uses Markdown rendering, while metadata and non-text values remain available as JSON. When an Interaction is selected, every card starts collapsed so the complete execution chain stays compact. In individual event, ReAct Round, and call views, LLM request cards start collapsed because they often contain complete conversation history and long system prompts; in those narrower views, LLM response and tool request/response cards remain expanded by default.

Captured events include:

- `llm.request`: complete provider request payload
- `llm.response`: final assistant message, including structured tool calls
- `tool.request`: tool name, call ID, and arguments
- `tool.response`: final result and error status
- Interaction, turn, run, and warning boundaries used to reconstruct the execution tree

The extension does not capture LLM token deltas or `tool_execution_update` progress events.

## Storage

Persistent Pi sessions store traces beside Pi's own session storage:

```text
<sessionDir>/traces/<sessionId>/
├── metadata.json
└── runs/<timestamp>_<runId>/
    ├── events.jsonl
    └── viewer.log
```

`events.jsonl` is append-only newline-delimited JSON. Every complete line is one event object; the file is not a JSON array. Replay ignores a partial final line left by a crash.

In-memory Pi sessions remain visible live but are not persisted automatically. The browser can still export their captured data.

Default retention removes the oldest inactive runs after 14 days or after project trace storage exceeds 1 GiB. The active run is never removed.

## Configuration

Global configuration is read from `~/.pi/agent/trace-viewer.json`. Project configuration in `.pi/trace-viewer.json` overrides other fields, but global `enabled: false` is a kill switch and cannot be re-enabled by a project. When global `enabled` is absent or `true`, a project can still disable capture locally.

```json
{
  "enabled": true,
  "autoOpen": true,
  "persistence": true,
  "contentMode": "full",
  "viewerPort": 0,
  "retentionDays": 14,
  "maxProjectBytes": 1073741824,
  "maxQueueBytes": 8388608
}
```

Port `0` selects an available port. A fixed occupied port causes Viewer startup to fail visibly while Pi and trace persistence continue.

## Privacy and security

This is a local debugging tool and deliberately displays complete captured content without redaction. Traces can contain API keys or other secrets when those values occur in prompts, provider payloads, tool arguments, tool output, or errors.

- The extension does not read Pi authentication files directly.
- The Viewer binds only to `127.0.0.1`.
- Trace and WebSocket routes require a random per-run token.
- Viewer assets are bundled locally.
- No trace content is uploaded and normal operation makes no external network request.
- The Viewer is read-only and cannot send messages, invoke tools, interrupt Pi, or modify requests and responses.

Treat trace files and screenshots as sensitive. See [SECURITY.md](https://github.com/xwcq/pi-local-trace-viewer/blob/HEAD/SECURITY.md) before sharing diagnostic data.

## Failure isolation

Observation is a weak dependency. Viewer startup, port binding, browser launch, IPC congestion, storage, retention, rendering, and shutdown errors are caught and reported without propagating into Pi's LLM or tool execution path. Viewer startup is attempted twice; if it remains unavailable, Pi continues running.

## Development

Requirements: Node.js 22.19 or later and Pi.

```bash
git clone https://github.com/xwcq/pi-local-trace-viewer.git
cd pi-local-trace-viewer
npm install --ignore-scripts
npm test
npm run check
pi -e "$PWD"
```

Tests use faux events and no provider API keys or paid model requests.

## License

[MIT](https://github.com/xwcq/pi-local-trace-viewer/tree/HEAD/LICENSE)

Pi Local Trace Viewer

中文文档

A local, read-only execution viewer for the Pi coding agent. It captures complete LLM requests and final responses, tool requests and final results, and displays them in a separate browser process without adding debug output to the prompt.

The extension intentionally ignores streaming token deltas and intermediate tool progress. It focuses on the semantic request/response chain.

Install

From npm:

pi install npm:pi-local-trace-viewer

From GitHub:

pi install git:github.com/xwcq/pi-local-trace-viewer

Try it for one Pi run without installing:

pi -e npm:pi-local-trace-viewer

Pi packages execute code with the same system access as Pi. Review extension source before installing third-party packages.

Usage

Start Pi normally. The Viewer starts as a separate localhost process and opens automatically by default.

/trace-viewer status
/trace-viewer open
/trace-viewer on
/trace-viewer off

on and off update the current session immediately and persist the setting globally in ~/.pi/agent/trace-viewer.json, so future sessions inherit it. If persistence fails, Pi continues and reports that only the current session changed.

A new session started while disabled does not launch or auto-open the Viewer. Turning observation off in an active session stops new capture but leaves its existing Viewer available for historical inspection until the session ends; turning it on starts the Viewer on demand.

The extension intentionally does not register /trace, avoiding conflicts with other trace extensions.

What the Viewer shows

The left tree groups one user message and all work required to produce the user-facing answer into an Interaction:

Interaction N（first user input characters…）
└── ReAct Round 1
    ├── LLM request
    ├── LLM response
    ├── Tool request
    └── Tool response

An Interaction can contain multiple ReAct Rounds when the model requests tools before returning the final answer. A new user or steering message starts a new Interaction.

The right panel renders system, user, assistant, tool-call, and tool-result messages as structured cards. Text uses Markdown rendering, while metadata and non-text values remain available as JSON. When an Interaction is selected, every card starts collapsed so the complete execution chain stays compact. In individual event, ReAct Round, and call views, LLM request cards start collapsed because they often contain complete conversation history and long system prompts; in those narrower views, LLM response and tool request/response cards remain expanded by default.

Captured events include:

llm.request: complete provider request payload
llm.response: final assistant message, including structured tool calls
tool.request: tool name, call ID, and arguments
tool.response: final result and error status
Interaction, turn, run, and warning boundaries used to reconstruct the execution tree

The extension does not capture LLM token deltas or tool_execution_update progress events.

Storage

Persistent Pi sessions store traces beside Pi's own session storage:

<sessionDir>/traces/<sessionId>/
├── metadata.json
└── runs/<timestamp>_<runId>/
    ├── events.jsonl
    └── viewer.log

events.jsonl is append-only newline-delimited JSON. Every complete line is one event object; the file is not a JSON array. Replay ignores a partial final line left by a crash.

In-memory Pi sessions remain visible live but are not persisted automatically. The browser can still export their captured data.

Default retention removes the oldest inactive runs after 14 days or after project trace storage exceeds 1 GiB. The active run is never removed.

Configuration

Global configuration is read from ~/.pi/agent/trace-viewer.json. Project configuration in .pi/trace-viewer.json overrides other fields, but global enabled: false is a kill switch and cannot be re-enabled by a project. When global enabled is absent or true, a project can still disable capture locally.

{
  "enabled": true,
  "autoOpen": true,
  "persistence": true,
  "contentMode": "full",
  "viewerPort": 0,
  "retentionDays": 14,
  "maxProjectBytes": 1073741824,
  "maxQueueBytes": 8388608
}

Port 0 selects an available port. A fixed occupied port causes Viewer startup to fail visibly while Pi and trace persistence continue.

Privacy and security

This is a local debugging tool and deliberately displays complete captured content without redaction. Traces can contain API keys or other secrets when those values occur in prompts, provider payloads, tool arguments, tool output, or errors.

The extension does not read Pi authentication files directly.
The Viewer binds only to 127.0.0.1.
Trace and WebSocket routes require a random per-run token.
Viewer assets are bundled locally.
No trace content is uploaded and normal operation makes no external network request.
The Viewer is read-only and cannot send messages, invoke tools, interrupt Pi, or modify requests and responses.

Treat trace files and screenshots as sensitive. See SECURITY.md before sharing diagnostic data.

Failure isolation

Observation is a weak dependency. Viewer startup, port binding, browser launch, IPC congestion, storage, retention, rendering, and shutdown errors are caught and reported without propagating into Pi's LLM or tool execution path. Viewer startup is attempted twice; if it remains unavailable, Pi continues running.

Development

Requirements: Node.js 22.19 or later and Pi.

git clone https://github.com/xwcq/pi-local-trace-viewer.git
cd pi-local-trace-viewer
npm install --ignore-scripts
npm test
npm run check
pi -e "$PWD"

Tests use faux events and no provider API keys or paid model requests.

License

MIT