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.

Official integration

The @langfuse/pi-observability-plugin extension is built and maintained by the Langfuse team. If you run into issues, please open an issue on the repository.

Experimental release

This extension is an experimental release. Future versions can bring breaking changes to the setup and to the trace structure.

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.

How it works

Pi has an extension API with core lifecycle events. An extension that subscribes to them sees every user prompt, model request and tool call of a session.

You register the extension in your pi settings with pi install, or load it for a single run with pi -e.
On startup, pi loads the extension and subscribes it to its core lifecycle events.
The extension converts turns, generations, tool calls and images into Langfuse traces and sends them to your project using the Langfuse TypeScript SDK.
Credentials and options (userId, environment, release) are resolved from a config file or environment variables. See the environment variables.

Quick start

Prerequisites

Pi needs Node.js, and pi's package installer shells out to npm:

node --version   # must be 22.0.0 or newer
npm --version    # must print a version

If node is missing or older than 22, install Node.js 22+ with a version manager such as fnm, nvm, or mise. npm ships with Node.js, so it is present once Node.js is.

Set up Langfuse

Sign up for Langfuse Cloud or self-host Langfuse.
Create a new project and copy your API keys from the project settings.

Install pi

Install pi by following the pi documentation.

Log in to a model provider

Pi needs a model before it can run a session. Start it:

pi

Type /login and pick a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro, and GitHub Copilot. If you would rather use an API key, see pi's provider docs. Once the login succeeds, type /quit to leave pi and proceed with the setup.

Install the Langfuse extension

This downloads the extension and registers it in your pi settings (~/.pi/agent/settings.json):

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

Two variations, both optional:

Goal	Command
Install for one project only, not globally	`pi install -l npm:@langfuse/pi-observability-plugin`
Try it for a single run, without installing	`pi -e npm:@langfuse/pi-observability-plugin`

-l writes to .pi/settings.json inside the current project instead of your user settings, so you can commit it and share the setup with your team.

Add your Langfuse credentials

Create a credentials file at ~/.pi/agent/langfuse.json:

{
  "publicKey": "pk-lf-...",
  "secretKey": "sk-lf-...",
  "baseUrl": "https://cloud.langfuse.com",
  "userId": "your-user-id",
  "environment": "development"
}

Only publicKey and secretKey are required. If baseUrl is omitted, the plugin uses https://cloud.langfuse.com (EU region). userId, environment and release are optional labels that let you segment traces by teammate, stage or version. Keep the file private, because it holds a secret key.

Alternatively, set your credentials with environment variables:

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"
export LANGFUSE_TRACING_ENVIRONMENT="development"
export LANGFUSE_USER_ID="your-user-id"

Environment variables take precedence over the config file, so you can override a single value without editing the file. These exports only apply to the current shell session. Add them to your shell profile to keep them.

Run your first trace

Start pi in any project and give it a prompt:

cd your-project
pi "Summarize this repository"

View traces in Langfuse

Open your Langfuse project to see the captured traces. The structure mirrors how pi actually works:

Turn trace: one trace per user prompt, named Pi - Turn 1 (...), with a Conversational Turn span that holds the whole turn.
Generations: one LLM Call per model request, with its input, output, cost, time to first token, and token usage including the cache-read and reasoning splits.
Tool spans: a Tool: ... observation for every tool pi invokes, with its input, its output, and an ERROR level when the call fails.
Sessions: all turns of one pi session share a session_id, so you can replay the session in order. Turn numbering continues across a pi restart.
Environment and user: traces are labeled with the configured environment and userId, so you can filter your own sessions or separate dev from CI.

Environment variables

Variable	Description	Required
`LANGFUSE_PUBLIC_KEY`	Your Langfuse public key (`pk-lf-...`)	Yes
`LANGFUSE_SECRET_KEY`	Your Langfuse secret key (`sk-lf-...`)	Yes
`LANGFUSE_BASE_URL`	Langfuse host. EU: `https://cloud.langfuse.com`, US: `https://us.cloud.langfuse.com`, Japan: `https://jp.cloud.langfuse.com`, HIPAA: `https://hipaa.cloud.langfuse.com`	No (defaults to EU)
`LANGFUSE_TRACING_ENVIRONMENT`	Environment label for the traces (e.g. `production`)	No
`LANGFUSE_USER_ID`	User ID attached to all traces	No

Enable and disable tracing

Scope	How
One run	`LANGFUSE_TRACING_ENABLED=false pi`
The current shell	`export LANGFUSE_TRACING_ENABLED=false` (undo with `unset`)
Global or project scope	`pi config`, then switch the extension off
Remove the plugin	`pi remove npm:@langfuse/pi-observability-plugin`

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

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.
Plugin not registered. Run pi list and confirm the plugin appears.
Region mismatch. baseUrl (or LANGFUSE_BASE_URL) must match the region your keys belong to.
Malformed credentials file. A trailing comma or a missing quote makes ~/.pi/agent/langfuse.json unreadable and the extension falls back to "no keys". Validate it:
```
node -e "console.log(JSON.parse(require('fs').readFileSync(process.env.HOME + '/.pi/agent/langfuse.json', 'utf8')))"
```
Environment variables from a previous terminal. Variables set with export only live in that shell. If you configured credentials that way, either add them to your shell profile or use the credentials file instead.
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

Was this page helpful?

On this page