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

A [pi](https://github.com/earendil-works/pi-coding-agent) extension that registers the `/usage` command: an aggregated panel combining **real Kimi quota** (from the Kimi API) with **local pi session consumption** (scanned from your own session logs).

## Features

- **`/usage`** — aggregated report with two sections:
  - **KIMI** — live quota (plan, usage windows, booster wallet, parallelism) fetched from `GET https://api.kimi.com/coding/v1/usages`.
  - **PI-CODE** — local token/cost consumption aggregated from your pi session files (`~/.pi/agent/sessions`), grouped by today / week / month / total and by provider/model.
- **`/usage --json`** — raw aggregated JSON output (API key never included; deep redaction applied as defense in depth).
- **`/usage --refresh`** — bypasses the in-memory cache.
- **TUI panel** — in interactive (TUI) mode, results are shown in a compact scrollable panel with a caramel-colored frame (`↑`/`↓`/`PgUp`/`PgDn` to scroll, `Esc`/`q` to close). In RPC/print mode the same content is rendered as plain text. Usage windows are shown in the largest unit (e.g. `Janela 5h`), and identical aggregation periods (e.g. week = month = total) are deduplicated.

> Note: the panel's output labels are currently in Portuguese (pt-BR). Internationalization is on the roadmap — contributions welcome.

## Installation

From GitHub:

```
pi install git:github.com/ProCleiton/pi-usage-panel
```

From npm:

```
pi install npm:pi-usage-panel
```

Requires **Node.js >= 22** (the extension and its tests rely on native TypeScript type-stripping).

## Configuration

Configuration is done exclusively through environment variables. There is no fallback to credential files of any kind.

| Variable | Default | Description |
|---|---|---|
| `KIMI_CODE_API` | — | Kimi API key. **Required** for the KIMI section; without it, that section shows an "unavailable" notice. |
| `PI_USAGE_CACHE_TTL_MS` | `60000` | In-memory cache TTL in milliseconds (lazy; no timers). |
| `PI_SESSIONS_DIR` | `~/.pi/agent/sessions` | Root directory of pi session files (scanned recursively for `*.jsonl`). |
| `PI_USAGE_TIMEZONE` | `America/Fortaleza` | IANA timezone used for period boundaries (today/week/month) and displayed dates. |

The API key is never printed, logged, or included in errors/`--json` output — every error message and the JSON payload pass through a sanitizer that redacts any accidental occurrence of the key.

## Data sources & privacy

This extension reads from exactly two sources:

1. **Kimi API** — a single authenticated `GET` to `https://api.kimi.com/coding/v1/usages`, using the key from `KIMI_CODE_API`. This is the only network call and the only third party that ever receives anything (your API key, as a Bearer token, to Kimi itself).
2. **Local session files** — a read-only, streaming scan of `$PI_SESSIONS_DIR/**/*.jsonl` (default `~/.pi/agent/sessions`). Only lines with assistant `usage` records are parsed; malformed lines and unreadable files are skipped.

- **No data is sent anywhere besides the Kimi API call described above.** There is no telemetry, no analytics, no remote logging.
- **No credentials are stored in the code**, and no credential files are ever read — the key comes only from the environment variable.
- Session scanning is local and read-only; nothing is written back.

## Development

Run the test suite (pure Node, no dependencies):

```
node test/run-tests.mjs
```

## Screenshots

- [ ] TODO: TUI panel screenshot
- [ ] TODO: `--json` output sample
- [ ] TODO: print-mode output sample

## License

MIT — see [LICENSE](https://github.com/ProCleiton/pi-usage-panel/tree/HEAD/LICENSE). Copyright (c) 2026 ProCleiton.