pi CLI

Trace interactive pi sessions — turns, model calls, tool calls and token usage — with the traceroot pi extension.

Embedding pi in your own Node process with @earendil-works/pi-coding-agent? Use the pi SDK integration instead.

Install

Requires Node.js 22.19 or later and pi 0.79 or later.

pi install npm:@traceroot-ai/pi-extension

Set up

Tracing is opt-in. Set these before starting pi, then restart pi:

export TRACEROOT_ENABLED=true
export TRACEROOT_API_KEY="tr-..."
# Optional: only needed for self-hosted deployments
# export TRACEROOT_HOST_URL="https://your-traceroot.example.com"

Setting	Env var	Default	Description
Enabled	`TRACEROOT_ENABLED`	`false`	Required. Turns tracing on.
API key	`TRACEROOT_API_KEY`	—	Required.
Host	`TRACEROOT_HOST_URL`	hosted service	Set only when self-hosting.
Capture content	`TRACEROOT_CAPTURE_CONTENT`	`true`	Send prompts and responses. `false` keeps only metadata.
Capture tool I/O	`TRACEROOT_CAPTURE_TOOL_IO`	`true`	Send tool arguments and results.
Debug	`TRACEROOT_PI_DEBUG`	`false`	Log to stderr. `TRACEROOT_LOG_FILE` writes a JSON-lines log.

Inside pi, /traceroot status shows whether tracing is on and where it sends; /traceroot disable and /traceroot enable switch it for the current session.

Usage

Use pi as usual. Each session becomes one trace, with one span per turn.

pi.session                   # one per session
├── pi.turn                  # one per prompt
│   ├── openai/gpt-…         # LLM span — tokens, cache, cost
│   │   ├── bash: …          # TOOL span — command and result
│   │   └── edit: …
└── pi.turn

Verify

Run one prompt in pi and confirm the trace arrives:

In the traceroot UI: Navigate to Tracing > Traces in traceroot Cloud. You should see a trace with root span pi.session.
Via the CLI: Run traceroot traces list to inspect your recent traces from the terminal.

What gets captured

Attribute	Description
Sessions	One trace per session; resumed and forked sessions are linked
Turns	One span per prompt, marked when interrupted
Model calls	Provider and model, prompt and response; errors and aborts marked
Tokens	Input, output, cache read and write counts, and cost
Tool calls	Tool name, arguments and result; failed tools marked
Compaction	Each compaction as a span on the session

With content capture on, prompts and tool I/O are sent as they are. Nothing is redacted; set TRACEROOT_CAPTURE_CONTENT=false and TRACEROOT_CAPTURE_TOOL_IO=false to send metadata only. See Data Capture and Privacy.

Limitations

The exporter ignores HTTPS_PROXY, so exports can fail on proxy-only networks.
If no trace arrives, run /traceroot status and set TRACEROOT_PI_DEBUG=true to log to stderr.

Overview

Native

Frameworks

Model Providers

Coding Agents

Internal Model Providers

Install

Set up

Usage

Verify

What gets captured

Limitations

Run the example

traceroot-pi-extension

Next steps

pi SDK

Data Capture and Privacy

​Install

​Set up

​Usage

​Verify

​What gets captured

​Limitations

​Run the example

traceroot-pi-extension

​Next steps

pi SDK

Data Capture and Privacy

Install

Set up

Usage

Verify

What gets captured

Limitations

Run the example

Next steps