# pi-meter

`pi-meter` is a [Pi](https://github.com/earendil-works/pi-mono) extension that
shows provider allowance windows in a compact `/meter` overlay.

![The `/meter` overlay showing provider allowance windows](assets/preview.png)

## Features

- Shows OpenAI Codex subscription allowance and reset times through Pi's
  existing `openai-codex` login.
- Shows OpenCode Go rolling, weekly, and monthly allowance usage from the
  source-reviewed usage route, authenticated with the OpenCode Zen/Go API key
  resolved from Pi's auth store at read time.
- Shows xAI SuperGrok's shared weekly usage through Pi's SuperGrok / X Premium
  OAuth login.
- Keeps successful provider readings visible when another provider fails.
- Omits a live provider's row when it settles with no usable reading and a
  suppressed failure (`not-configured`, `unauthorized`, `network`, or
  `invalid-response`); those typed failures keep their internal facts but
  never produce a failure-derived display, and a usable cached reading stays
  visible.
- Keeps `timeout` and `rate-limited` failures visible as failure rows.
- Does not list Claude: it has no provider definition, auth resolution, source
  adapter, or network I/O until a qualifying first-party allowance contract and
  permitted credential-use policy exist.
- Fetches only when `/meter` opens or you request a refresh. It performs no
  startup requests, credential resolution, or background polling.

## Install

Pi packages run with full system access. Review the source before installing.

```sh
pi install npm:@wannfq/pi-meter
```

You can also install directly from GitHub:

```sh
pi install git:github.com/wannfq/pi-meter
```

To try the extension without installing it:

```sh
pi -e npm:@wannfq/pi-meter
```

## Use

Run Pi in interactive mode, then enter:

```text
/meter
```

Use `r` to request a refresh and `Esc` or `q` to close the overlay. You can also
open the overlay with a forced refresh:

```text
/meter refresh
```

A forced refresh bypasses cached freshness, but it still respects provider rate
protection. OpenAI Codex requires an `openai-codex` account in Pi. OpenCode Go
requires the OpenCode Zen/Go API key stored in Pi's auth store. SuperGrok
requires Pi's xAI OAuth login; an `XAI_API_KEY` alone does not grant access to
consumer subscription usage.

## Develop

This project requires Node.js and the pnpm version declared in `package.json`.

```sh
pnpm install
pnpm check
pnpm test
pnpm dev
```

`pnpm dev` starts Pi with only this extension loaded. See
[`docs/providers.md`](docs/providers.md) before adding or changing a provider.
Project conventions and validation requirements are in
[`AGENTS.md`](AGENTS.md).

## License

[MIT](LICENSE)