TracingCoding Agents

pi (tracing)

pi is a minimal terminal coding agent. The @respan/instrumentation-pi package is a pi extension that traces your pi sessions to Respan: every turn, model call, tool execution, and compaction. Nothing is written to disk on your machine; spans are batched in memory and sent straight to Respan.

This page covers interactive pi sessions in the terminal. To trace the @earendil-works/pi-coding-agent SDK inside your own application, see Pi Coding Agent SDK.

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

pi can also call models through the Respan gateway: add a provider with "baseUrl": "https://api.respan.ai/api" and "api": "openai-completions" to ~/.pi/agent/models.json. Every LLM call is then logged by the gateway with no SDK; the extension on this page adds the agent-level structure (turns, tool calls, threads) on top.

How it works

The extension traces pi by observing it, not by proxying it:

  • pi talks to its model provider directly.
  • pi’s native extension events notify the extension when sessions start, turns run, models respond, and tools execute.
  • The extension turns those events into OpenTelemetry spans and sends them to Respan from inside the pi process. There is no daemon, no local journal, and no log directory: if Respan is unreachable, the batch is retried and then dropped, and pi keeps working. For guaranteed delivery through outages, see Delivery guarantees.
  • Credentials come from RESPAN_API_KEY or from ~/.respan/credentials.json written by respan auth login; the extension never stores them in its own config.

Each prompt you send appears in Respan as one trace with turn, model call, and tool spans; all traces of a pi session share the session id as thread id. See What gets traced.

Set up tracing

The extension requires pi v0.65.0 or later.

1

Install pi

If you haven’t already, install pi.

2

Install the extension

With the Respan CLI:

$respan auth login          # or: export RESPAN_API_KEY=...
$respan integrate pi

respan integrate pi runs pi install npm:@respan/instrumentation-pi and writes a non-secret ~/.pi/agent/respan.json. Use --local to install into the current project instead, --trace-scope run if you prefer one trace per prompt instead of one per session (see Settings), and --disable to turn tracing off without uninstalling.

Without the Respan CLI:

$pi install npm:@respan/instrumentation-pi
$export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
3

Restart pi

Restart pi so it loads the extension. The footer shows Respan: tracing while active, and after each prompt a widget below the editor shows a link to its trace.

4

View your trace

Open the Traces page. Each pi session is one trace and every prompt adds a turn to it, even after a restart or a week-long pause; the Threads view shows the whole pi session as a conversation.

What gets traced

Each agent run (one prompt → agent_end) is one root agent span, pi.turn-<n>.agent, displayed as agent.turn-<n> — n is the prompt’s number within the pi session, so a session resumed with pi -c continues at the next turn.

pi.turn-1.agent (agent)                         one per prompt, shown as agent.turn-1
├── pi.chat (chat)                              one per assistant message
│     prompts, completion, tool_calls, usage, TTFT, cost
├── bash.tool (tool)                            one per tool execution
├── read.tool (tool)                            skill usage detected from SKILL.md
├── pi.chat (chat)
└── pi.compaction (task)                        when compaction happens mid-run
DataDescription
TurnsOne root agent span per prompt, with the prompt as input, the final assistant text as output, turn / tool-call counts, thinking level, pi version, session file and working directory.
Model callsOne chat span per assistant message: provider, model, the conversation sent to the model, the response, this turn’s tool calls, available tools.
UsageInput, output, total, cache-read and cache-creation tokens, reasoning tokens, estimated cost, time to first token.
Tool executionsOne tool span per execution with arguments and result; failures carry the error. When pi reads a SKILL.md or runs the skill tool, the span is tagged with the skill name.
Compaction and branch summariesTask spans with the trigger and the resulting summary.
Git metadataRepository URL (credentials stripped), branch and commit of the working directory on each turn span.
ErrorsAssistant errors and aborts, tool errors, and runs interrupted by quitting pi.

Chat and tool spans are sent the moment they complete, so a long-running turn streams into the dashboard while it is still running; the turn span arrives when the run ends.

Settings

respan integrate pi saves its configuration to ~/.pi/agent/respan.json. A project-level .pi/respan.json overrides it, and environment variables override both. The API key is never written to these files.

SettingSaved keyEnvironment variableHow to change it
Enable tracingenabledRESPAN_PI_TRACING (true/false)Re-run respan integrate pi (or --disable), or edit the file.
API endpointbase_urlRESPAN_BASE_URLPoint it at a local collector or a self-hosted Respan.
Trace scopetrace_scopeRESPAN_PI_TRACE_SCOPE (session/run)session (default) = one trace per pi session with a root per prompt; run = one trace per prompt.
Customercustomer_idRESPAN_CUSTOMER_IDSets customer_identifier on every span.
Workflow nameworkflow_name—respan integrate pi --workflow-name; traceloop.workflow.name on turn spans (default pi).
Projectproject_idRESPAN_PROJECT_IDrespan integrate pi --project-id; routes traces to a Respan project.
Extra span metadatametadata—Edit metadata (string key-value pairs) in the file.
Debug output—RESPAN_PI_DEBUG=1Prints the extension’s diagnostics to stderr.

Trace scope decides what one trace is:

  • session (default): every prompt of the session joins one trace whose id is derived from the pi session id, so a session resumed with pi -c in another process, or after a week-long pause, keeps adding turns to the same trace. Respan shows the turns as multiple roots under one synthetic root, ordered by time; the trace’s duration spans from the first to the latest turn. No span is ever held open across idle time.
  • run: every prompt is its own trace with its own cost and latency. All traces of the session still share thread_identifier = the pi session id, so the Threads view shows the whole session in order.

To switch:

$respan integrate pi --trace-scope run

Common workflows

Install for one project only

$respan integrate pi --local      # or: pi install -l npm:@respan/instrumentation-pi

This records the extension in the project’s .pi/settings.json instead of ~/.pi/agent/settings.json.

Turn tracing off temporarily

$RESPAN_PI_TRACING=false pi

Or run respan integrate pi --disable, which keeps the package installed and sets enabled: false.

Non-interactive runs

pi -p "..." runs are traced the same way; the extension flushes before pi exits.

Upgrade

$pi update npm:@respan/instrumentation-pi

Uninstall

$pi remove npm:@respan/instrumentation-pi   # add -l if it was installed with --local
$rm ~/.pi/agent/respan.json                  # optional: drop the saved settings

Delivery guarantees

Inside the pi process, spans are batched in memory and posted to Respan with retries. Nothing is written to your disk, so nothing piles up on the machine, and a session that sits idle for days costs nothing. The trade-off is that if Respan is unreachable for longer than the retry window while pi is running, that batch is lost.

If you need at-least-once delivery through outages and restarts, run the Respan Collector next to pi and point the extension at it:

$respan integrate pi --with-collector   # starts a local collector and sets base_url to it

The collector keeps a bounded on-disk queue that drains as soon as Respan acknowledges the data; it never grows without limit.

Troubleshooting

Traces do not appear. Check the following, in order:

  1. Verify the extension is installed: pi list should show npm:@respan/instrumentation-pi.
  2. Verify the key is available: RESPAN_API_KEY is set, or respan auth status shows you are logged in. Without a key the footer shows Respan: tracing off (run respan integrate pi).
  3. Verify tracing is enabled: enabled is not false in ~/.pi/agent/respan.json or .pi/respan.json, and RESPAN_PI_TRACING is not set to false.
  4. Restart pi after any configuration change, then run at least one prompt; the turn span is sent when the run ends.
  5. Run RESPAN_PI_DEBUG=1 pi to print the extension’s diagnostics to stderr (initialization, export errors).

Tracing failures never interrupt pi: the session keeps working even when traces do not appear, and the footer shows Respan: tracing unavailable: <reason>.

The trace link widget does not appear. The widget is only shown in interactive mode, after the first completed prompt, and only for the Respan cloud endpoint (self-hosted or collector-routed setups show the footer status only).

Resources