---
title: Pi
description: How ClawMetry observes Pi — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
eyebrow: Runtime reference
---

# Pi

Pi stores sessions as append-only JSONL trees, one directory per working directory. Versions 2 and 3 of the format are a real tree that supports in-place branching, so the active conversation is a path from the root to the current leaf — not the whole file.

| | |
|---|---|
| **Runtime id** | `pi` |
| **Category** | TypeScript coding agent |
| **Vendor** | Earendil |
| **Tier** | Paid tier (Starter and up) |
| **Upstream** | [pi.dev](https://pi.dev) |

## Where the data comes from

ClawMetry reads these locations, in order, and never writes to any of them.

- `~/.pi/agent/sessions/--<encoded-cwd>--/<timestamp>_<uuid>.jsonl`

**Format.** JSONL with a `SessionHeader` first line; v2/v3 entries carry `id` and `parentId` and form a tree.

## Environment variables

| Variable | Effect |
|---|---|
| `CLAWMETRY_PI_DIR` | ClawMetry-side override, checked first |
| `PI_CODING_AGENT_SESSION_DIR` | Pi's own env |
| `CLAWMETRY_PI_SUBAGENT_TOOLS` | which tool names count as delegation |

See [Environment variables](/docs/config/environment/) for the variables that apply to every runtime.

## Tokens and cost

**Tokens.** Real, with cache read/write, one-hour-TTL cache writes and reasoning tokens.

**Cost.** Real — Pi stores a per-turn cost object, which ClawMetry sums directly and only derives when the object is absent.

:::note Why this section exists
Runtimes differ enormously in what they persist. Rather than showing a plausible number everywhere, ClawMetry reports what the store actually contains and marks the rest unknown. A cost of `$0.00` and a cost of *unknown* mean different things, and the dashboard keeps them different.
:::

## Sub-agents and delegation

Pi core has no delegation primitive. The bundled `subagent` extension spawns child processes that write no session file, so children are synthesised from the parent's tool result and its embedded per-child usage.

## Things worth knowing

- Reading all lines linearly pollutes counts with abandoned branches. ClawMetry walks `parentId` back from the last entry to find the active path; v1 files have no ids and stay linear.
- A failed delegation persists `exitCode: 1` and `stderr` while the message-level `isError` stays false — failure must be read from the exit code.

## Verify it is being read

```bash
# Is this runtime detected, and would this install unlock it?
clawmetry runtimes --json | jq '.runtimes[] | select(.id=="pi")'

# Why is it locked, if it is?
clawmetry runtimes --why pi

# Any sessions ingested yet?
curl -s 'http://localhost:8900/api/local/sessions?limit=5' \
  | jq '.rows[] | {session_id, agent_id, events, cost_usd}'
```

If detection succeeds but no sessions appear, work through [Troubleshooting](/docs/ops/troubleshooting/) — the usual causes are a relocated data directory (set the override above), a session limit that is hiding older runs, or a runtime that simply has not written anything yet.