---
slug: "traceroot-ai-pi-extension"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/traceroot-ai/traceroot-pi-extension@main/README.md"
repo: "https://github.com/traceroot-ai/traceroot-pi-extension"
source_file: "README.md"
branch: "main"
---
# traceroot-pi-extension

TraceRoot extension for [pi](https://github.com/earendil-works/pi-coding-agent) that sends per-session traces to [TraceRoot](https://traceroot.ai).

Each pi session is traced with conversation turns, LLM calls, tool executions, token usage, and session continuity metadata.

---

## Installation

Install from npm:

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

Or, from a clone of this repo:

```bash
pi install .
```

---

## Configuration

Tracing is opt-in. Set the following environment variables before starting pi:

| Variable                  | Required | Description                                                                                                |
| ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `TRACEROOT_ENABLED`       | Yes      | Set to `true` to enable tracing.                                                                           |
| `TRACEROOT_API_KEY`       | Yes      | Your TraceRoot API key. Find it at [app.traceroot.ai](https://app.traceroot.ai) under Settings > API Keys. |
| `TRACEROOT_HOST_URL`      | No       | TraceRoot base URL. Defaults to the hosted service. Set this only when self-hosting.                       |
| `TRACEROOT_OTLP_ENDPOINT` | No       | Explicit OTLP traces endpoint override. Defaults to `<TRACEROOT_HOST_URL>/api/v1/public/traces`.           |

Example (add to `~/.zshrc`, `~/.bashrc`, or your shell profile):

```bash
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"
```

Restart pi, or open a new terminal session, after setting the variables.

---

## License

Apache-2.0