Skip to main content
Automatically capture agent runs, LLM calls, tool executions, and token usage from pi coding-agent sessions you drive with @earendil-works/pi-coding-agent — the library form of pi, where you run an AgentSession from your own Node process instead of the interactive CLI.
Running the interactive pi CLI instead? Use the traceroot pi extension.

Install

Set up

Call TraceRoot.initialize() before creating any session:

Usage

Create and run sessions as usual — every session created after initialization is traced automatically:
Each session.prompt() becomes a nested trace, with tool spans under the LLM span that requested them:

Verify

Run your code and confirm the trace arrives:
  1. In the traceroot UI: Navigate to Tracing > Traces in traceroot Cloud. You should see a trace with root span AgentSession.prompt.
  2. Via the CLI: Run traceroot traces list to inspect your recent traces from the terminal.

What gets captured

captureContent and captureToolIo (both default true) control whether prompt/response text and tool arguments/results are attached to spans. Pass them through the { module, config } form:
captureContent can also be a function that redacts, truncates, replaces, or omits each prompt and response before it is recorded. See Data Capture and Privacy for a working redaction example.

Limitations

  • @earendil-works/pi-coding-agent is ESM-only and requires Node >= 22.19.

Run the example

Clone the repo and run a complete session end-to-end.

TypeScript

Run the TypeScript example

Next steps

TypeScript SDK Reference

Explore the full TypeScript SDK reference and configuration options.

Cost Tracking

Learn how traceroot calculates token costs and tracks model spend.