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

> A lightweight [pi coding agent](https://pi.dev) extension that monitors your Z.ai token quota in real time and displays a color-coded progress bar in the terminal footer via [pi-powerline](https://github.com/harms-haus/pi-powerline).

## Features

- Fetches Z.ai token quota usage from the official API
- Displays a color-coded progress bar in the pi-powerline footer (Line 2, right-aligned)
- Caches responses for 60 seconds to minimize API calls
- Automatically activates only when a Z.ai provider is selected
- Gracefully handles network errors, missing API keys, and headless sessions

## Installation

```bash
pi install git:github.com/harms-haus/pi-zai-usage
```

Then restart pi or run `/reload`.

## How It Works

When a Z.ai model is selected (provider name starts with `"zai"`), this extension:

1. Fetches your current token quota from `GET https://api.z.ai/api/monitor/usage/quota/limit`
2. Extracts the `TOKENS_LIMIT` entry from the response
3. Publishes the usage percentage and reset time to the UI via `ctx.ui.setStatus()`

The published status is consumed by [pi-powerline](https://github.com/harms-haus/pi-powerline), which renders it as a color-coded progress bar on footer **Line 2**, right-aligned.

### Caching

Responses are cached for **60 seconds**. Within the TTL, cached data is returned immediately without an API call. The cache is cleared when the selected provider changes (e.g., switching from Z.ai to another provider). Switching between Z.ai models preserves the cache.

## Events

The extension listens to the following pi lifecycle events:

| Event              | Behavior                                                                        |
| ------------------ | ------------------------------------------------------------------------------- |
| `session_start`    | Fetches and publishes usage data                                                |
| `model_select`     | Clears the cache if the provider changed, then fetches and publishes usage data |
| `turn_end`         | Fetches and publishes usage data (respects cache TTL)                           |
| `session_shutdown` | Clears the status display                                                       |

When no UI is available, all events return early. When the active provider is not Z.ai, the handlers clear any previously published status rather than fetching new data.

## Status Payload

The extension publishes under the status key `"zai-usage"`:

```json
{ "percentage": 42.5, "resetTimeMs": 1719360000000 }
```

| Field         | Type                  | Description                                                            |
| ------------- | --------------------- | ---------------------------------------------------------------------- |
| `percentage`  | `number`              | Token quota used, rounded to one decimal place and clamped to [0, 100] |
| `resetTimeMs` | `number \| undefined` | Unix timestamp (ms) when the quota resets                              |

## Requirements

- **Z.ai API key** — configure via `/login` for the `zai` provider in pi
- **pi-powerline** — renders the progress bar in the footer (optional; without it the status is still published but not displayed)

## Integration with pi-powerline

The progress bar is rendered by [pi-powerline](https://github.com/harms-haus/pi-powerline) on footer **Line 2**, right-aligned. Install both extensions for the full experience:

```bash
pi install git:github.com/harms-haus/pi-powerline
pi install git:github.com/harms-haus/pi-zai-usage
```

## License

MIT

## Contributing

See [CONTRIBUTING.md](https://github.com/harms-haus/pi-zai-usage/blob/HEAD/CONTRIBUTING.md) for development setup and PR guidelines.