# pi-token-stats

Token and cost statistics extension for [pi coding agent](https://pi.dev).

- GitHub: <https://github.com/reaishijie/pi-token-stats>
- npm: <https://www.npmjs.com/package/pi-token-stats>
- 中文文档: [README.zh-CN.md](./README.zh-CN.md)

## Features

- Adds `/tokens` and `/token-stats` commands.
- Scans pi session `.jsonl` files.
- Aggregates input, output, cache read, cache write, total tokens, and cost.
- Groups usage by provider/model.
- Supports recent-day filters or all history.

## Screenshot

![pi-token-stats screenshot](./docs/screenshot.png)

## Install

### From npm

```bash
pi install npm:pi-token-stats
```

### From git

```bash
pi install git:github.com/reaishijie/pi-token-stats
```

Install a pinned release/tag:

```bash
pi install git:github.com/reaishijie/pi-token-stats@v0.1.1
```

### Local development

```bash
pi install /path/to/pi-token-stats
# or test once without installing
pi -e /path/to/pi-token-stats
```

## Usage

```text
/tokens
/tokens 7
/tokens 30
/tokens 0
/token-stats --days 7
```

Arguments:

- no argument: last 30 days
- `7`: last 7 days
- `30`: last 30 days
- `0`: all history
- `--days N` or `-d N`: last N days

## Session directory

By default, the extension reads sessions from:

```text
~/.pi/agent/sessions
```

It respects pi environment overrides:

- `PI_CODING_AGENT_SESSION_DIR`
- `PI_CODING_AGENT_DIR`

## Package manifest

This package is discoverable as a pi package through the `pi-package` keyword and declares its extension entry under the `pi.extensions` field in `package.json`.

## License

MIT