Pi Coding Agent tracing with Langfuse

What is Pi? Pi is a minimal, extensible AI coding agent that runs in your terminal. It supports 15+ providers and hundreds of models, and adapts to your workflows through extensions, skills, prompt templates, and themes.

What is Langfuse? Langfuse is an open-source AI engineering platform. It helps teams trace agentic applications, debug issues, evaluate quality, and monitor costs in production.

What can this integration trace?

The plugin listens to Pi's core lifecycle events and sends every user prompt to Langfuse as its own trace:

• Agent turns: one trace per user prompt, with all turns of a Pi session grouped under one session ID. Turn numbering survives a Pi restart.
• Model generations: every model request with inputs, outputs, cost, time to first token, and token usage including cache-read and reasoning splits.
• Tool calls: each tool Pi invokes, with input, output, and an ERROR level when the call fails.
• Images: images you add to a prompt are uploaded as Langfuse media and render inside the trace.
• Subagents: Pi processes spawned by other extensions nest under the turn that started them.

Because the plugin listens to Pi's core events, it also records work added by other extensions — custom tools and subagents included.

Trace model

Each user prompt becomes one Langfuse trace. All traces of one Pi session share a session ID:

[trace]  "Pi - Turn 3 (a1b2c3d4)"          ← turn number survives a Pi restart
└─ span  "Conversational Turn"
   ├─ generation  "LLM Call 1"             ← tokens with cache and reasoning splits, cost, TTFT
   ├─ tool        "Tool: bash"             ← input, output, ERROR level on failure
   ├─ generation  "LLM Call 2"
   └─ ...

Quick start

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi   # then run /login inside the interactive session

pi install npm:@langfuse/pi-observability-plugin

{
  "publicKey": "pk-lf-...",
  "secretKey": "sk-lf-...",
  "baseUrl": "https://cloud.langfuse.com",
  "userId": "you",
  "environment": "dev",
  "release": "1.2.3"
}

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com" # 🇪🇺 EU region
# Other Langfuse data regions include 🇺🇸 US: https://us.cloud.langfuse.com, 🇯🇵 Japan: https://jp.cloud.langfuse.com and ⚕️ HIPAA: https://hipaa.cloud.langfuse.com

cd your-project
pi "Summarize this repository"

Debug a session: find failed tool calls

Real work spans many turns. Give Pi a task where something goes wrong, for example:

pi "Run the test suite and fix the first failing test"

When a tool invocation fails, its observation is recorded with level ERROR:

• Filter by error level in the trace view to jump straight to the failing Tool: bash call, with the exact input and output that caused it.
• Open the session to see every turn of your Pi session in order — including turns from before a Pi restart, since turn numbering continues.
• Include an image: paste a screenshot into the prompt (for example of a broken UI) — it is uploaded as Langfuse media and renders inside the trace, so the full context of the turn stays reviewable.

Trace Pi subagents across processes

A Pi subagent is a second Pi process, spawned by an orchestration extension (for example the subagent example extension from the Pi repository or an orchestration package from the Pi package gallery). Child processes inherit their parent's environment, and the plugin uses that to stitch traces together.

While a turn is active, the plugin exposes the turn's identifiers as environment variables:

A Pi process that finds these variables nests its trace under the turn that spawned it — the subagent's generations and tool calls appear inside the parent trace. Without them, the child writes a separate trace. The built-in flow needs no configuration.

You can also set these variables yourself to attach a Pi run to a trace created by another tool, for example a CI pipeline that already reports to Langfuse. The IDs must belong to the same Langfuse project the run exports to.

Configuration reference

The plugin resolves its configuration in this order: the kill switch LANGFUSE_TRACING_ENABLED=false first, then environment variables, then ~/.pi/agent/langfuse.json, then defaults.

Enable and disable tracing

The kill switch has priority over environment keys and the config file. When tracing is off, the status line shows langfuse: off (no keys) and nothing is sent — note that this message reads the same whether the kill switch is set or the keys are genuinely missing. To remove stored keys, delete ~/.pi/agent/langfuse.json.

Troubleshooting

No traces appearing in Langfuse

1. Check the status line. langfuse: off (no keys) means the plugin found no usable configuration. Two different causes produce this same message: the kill switch LANGFUSE_TRACING_ENABLED=false is set (check your shell profile and any inherited environment), or the credentials were not found — see credentials setup.
2. Plugin not registered. Run pi list and confirm the plugin appears.
3. Region mismatch. baseUrl (or LANGFUSE_BASE_URL) must match the region your keys belong to.
4. Inspect the plugin's steps. Run with PI_LANGFUSE_DEBUG=true to log its activity to standard error.

Authentication errors

Verify your API keys are correct and that the host matches the region your keys belong to:

• EU region: https://cloud.langfuse.com
• US region: https://us.cloud.langfuse.com
• Japan region: https://jp.cloud.langfuse.com
• HIPAA region: https://hipaa.cloud.langfuse.com

Data privacy

The plugin sends Pi session data to Langfuse, which includes prompts, model outputs, tool inputs and outputs, and prompt images. Your Langfuse API keys are masked from all captured payloads before upload. Use the kill switch for sessions you do not want stored in Langfuse, and keep ~/.pi/agent/langfuse.json private.

Next steps

• Sessions: review whole Pi sessions turn by turn.
• Users and environments: segment traces by teammate or by dev/CI stage via userId and environment.
• Evaluation: score captured turns, for example with LLM-as-a-judge, to monitor agent quality over time.

Resources

• pi-observability-plugin repository (GitHub)
• @langfuse/pi-observability-plugin on npm
• Pi documentation
• Langfuse TypeScript SDK