# pi-kimi-code-console-usage

> ⚠️ **DEPRECATED** — this package is no longer maintained. Quota viewing is
> now provided by [pi-provider-kimi-code](https://github.com/Leechael/pi-provider-kimi-code)
> itself via the **`/kimi-settings`** command (v0.6.10 and later). Please
> uninstall this package:
>
> ```bash
> pi uninstall npm:pi-kimi-code-console-usage
> ```
>
> Version 0.2.0 is a final no-op release: it registers no commands and no
> footer status, and only prints a deprecation notice on load.

[![npm version](https://img.shields.io/npm/v/pi-kimi-code-console-usage)](https://www.npmjs.com/package/pi-kimi-code-console-usage)
[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

The following documents version 0.1.4, the last functional release. It is
kept for historical reference only.

---

A [pi](https://github.com/earendil-works/pi-coding-agent) extension that
monitors your [Kimi Code](https://www.kimi.com/code) coding-plan quota from
inside the terminal — no browser, no console tab.

```text
Current week
███████                                            14% used
Resets Aug 3 at 4:25am (UTC)

Current 5h window
██████▌                                            13% used
Resets 10:25am (UTC)

Membership: Intermediate
Parallel sessions: 0 / 20
```

## Features

- **Footer status** — `kimi 5h 13% · wk 14%`, always visible. Turns
  warning-colored when a quota runs low; dims to `kimi usage: error` on
  fetch failure.
- **Polling** — refreshes every 5 minutes (configurable), plus a throttled
  refresh after each agent run settles.
- **`/kimi-usage` command** — fresh fetch rendered as an overlay: weekly
  quota bar, rolling 5-hour window bar, localized reset times, membership
  tier, live parallel-session count, and booster-wallet balance if you have
  one. `Esc` / `q` / `Enter` closes.
- **Low-quota warnings** — one-shot notification when the 5h window drops to
  ≤15% remaining or the weekly quota to ≤20% remaining (both configurable).
  Latched per quota window, so each warning fires once and re-arms after the
  quota resets.
- **Zero auth setup** — reuses the OAuth credential from your existing
  `kimi-coding` login, including transparent token refresh on expiry.

## Prerequisites

- pi with the `kimi-coding` provider logged in (`/login kimi-coding`),
  normally via the
  [pi-provider-kimi-code](https://github.com/Leechael/pi-provider-kimi-code)
  package. This extension imports that package's auth and usage-client
  internals instead of duplicating them.

## Install

```bash
pi install npm:pi-kimi-code-console-usage
```

Then `/reload` (or restart pi). The footer status appears after the first
fetch; run `/kimi-usage` for the full view.

To install the bleeding-edge version straight from the repo instead:

```bash
pi install git:github.com/khaosoi/pi-kimi-code-console-usage
```

## Update

pi checks for package updates at startup and tells you when one is
available. To update:

```bash
pi update npm:pi-kimi-code-console-usage
```

## Configuration

Environment variables:

| Variable | Default | Meaning |
| --- | --- | --- |
| `KIMI_USAGE_POLL_MINUTES` | `5` | Poll interval in minutes (minimum 1; `0` disables polling) |
| `KIMI_USAGE_WARN_5H_PCT` | `15` | Warn when the rolling 5h window has ≤ N% remaining |
| `KIMI_USAGE_WARN_WEEK_PCT` | `20` | Warn when the weekly quota has ≤ N% remaining |

The token source and base URL are inherited from `pi-provider-kimi-code`:
the stored OAuth credential first, then `KIMI_API_KEY`; `KIMI_CODE_BASE_URL`
/ `KIMI_BASE_URL` overrides are respected.

## How it works

Kimi Code exposes the same usage data shown in the web console at a
read-only endpoint:

```text
GET https://api.kimi.com/coding/v1/usages
Authorization: Bearer <your OAuth access token>
```

The response carries the weekly quota, the rolling 5-hour window, membership
level, and active parallel sessions — all as plan-relative percentages with
reset timestamps. A fresh (0% used) 5h window comes back as a `limits`
row with only the `window` descriptor and no quota fields — the footer
renders that as `5h 0%` rather than hiding it. This extension fetches it
with the token pi already
stores for the `kimi-coding` provider (`~/.pi/agent/auth.json`), refreshing
the token through the provider's own file-locked refresh path when it
expires.

## Privacy

- The only network call this extension makes is `GET` to
  `api.kimi.com/coding/v1/usages`, authenticated with your own token.
- No telemetry, no third-party endpoints, no data leaves your machine
  except the usage query above.
- Your token is read from pi's auth store at runtime and is never logged,
  rendered, or written anywhere by this extension.

## Caveats

- The usages endpoint is undocumented (the provider package tracks the
  official Kimi Code CLI). If Kimi changes it, fetches fail gracefully:
  the footer shows `kimi usage: error` until it recovers.
- This package depends on `pi-provider-kimi-code` internals
  (`src/usage.ts`, `src/oauth.ts`, `src/device.ts`), pinned to `^0.6.9`.
  A provider upgrade that renames those exports would need a matching
  update here.
- Quota numbers are percentages of your plan's allocation; absolute token
  counts are not exposed by the endpoint.

## Development

```bash
git clone https://github.com/khaosoi/pi-kimi-code-console-usage
cd pi-kimi-code-console-usage
npm install          # installs pi-provider-kimi-code for import resolution
pi -e ./index.ts     # load from the working tree
```

The extension is a single `index.ts`, loaded by pi via jiti — no build step.

## License

[MIT](LICENSE)