@hk_net/pi-usage-bars 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +103 -77
  2. package/LICENSE +21 -21
  3. package/README.md +127 -126
  4. package/docs/releasing.md +84 -106
  5. package/extensions/usage-bars/core.ts +1274 -1240
  6. package/extensions/usage-bars/index.ts +665 -656
  7. package/package.json +66 -67
  8. package/docs/financial-metrics-plan.md +0 -75
package/CHANGELOG.md CHANGED
@@ -1,77 +1,103 @@
1
- # Changelog
2
-
3
- ## [0.4.0] - 2026-07-22
4
-
5
- ### Added
6
-
7
- - Added Kimi For Coding quota support through Pi's `kimi-coding` credential and the first-party five-hour/weekly usage endpoint.
8
- - Added separate MiniMax Global and China Coding/Token Plan support, including the current token-plan endpoint and legacy coding-plan fallback.
9
- - Added provider-specific quota labels and support for MiniMax responses that expose an interval quota without a weekly quota.
10
- - Added neutral MiniMax purchased-Credits balance rendering when a key-authenticated first-party response exposes a balance.
11
- - Added OpenRouter account balance and daily/weekly/monthly key spend using the first-party Credits and Key APIs.
12
- - Added OpenRouter per-key limit bars only when the key has a real configured credit limit.
13
- - Added DeepSeek total, topped-up, and granted balance support through the official key-authenticated balance API.
14
- - Added separate Moonshot/Kimi API Global and China available, cash, and voucher balance support.
15
- - Added a typed financial-metrics roadmap for further balance/spend providers.
16
- - Added provider parsing, regional routing, endpoint fallback, financial rendering, authentication lifecycle, and smoke tests.
17
- - Added CI, reproducible installs, production auditing, and a maintainer release guide.
18
-
19
- ### Changed
20
-
21
- - Treat MiniMax status `2062` as a neutral “No active Token Plan” account state rather than an API error; the cookie-only console balance endpoint remains out of scope.
22
- - Expanded endpoint configuration documentation for Kimi, MiniMax, OpenRouter, DeepSeek, and Moonshot.
23
- - Changed npm publishing to an explicit manual workflow so source tags cannot accidentally republish an already released version.
24
- - Bumped the package version to 0.4.0.
25
-
26
- ## [0.3.0] - 2026-07-22
27
-
28
- ### Breaking changes
29
-
30
- - Renamed the npm package to `@hk_net/pi-usage-bars`; install it with `pi install npm:@hk_net/pi-usage-bars`.
31
- - Updated the minimum supported Pi release to 0.81.1.
32
- - Removed Google Gemini CLI and Google Antigravity usage support, matching their removal from Pi 0.71.0.
33
- - Refactored core usage orchestration to accept resolved provider tokens instead of reading or refreshing Pi credentials directly.
34
-
35
- ### Added
36
-
37
- - Added ZAI Coding Plan (China) provider and quota endpoint support.
38
- - Added abort-aware polling and provider requests.
39
- - Added strict TypeScript checking, a current-Pi smoke test, pinned development dependencies, and reproducible npm installs.
40
- - Added Pi package gallery image metadata and documented endpoint/security behavior.
41
-
42
- ### Changed
43
-
44
- - Authentication now goes through `ctx.modelRegistry.getProviderAuth()`, allowing Pi to safely resolve and refresh credentials with its canonical locked credential store.
45
- - Renamed Z.AI to the current Pi labels, ZAI Coding Plan (Global) and ZAI Coding Plan (China).
46
- - Limited polling and custom `/usage` UI to interactive TUI mode.
47
- - Made startup and model-change polling non-blocking and added complete session shutdown cleanup.
48
- - Updated the selector to use typed TUI APIs, explicit render requests, abortable loading, and theme-safe invalidation.
49
-
50
- ### Fixed
51
-
52
- - Fixed OAuth refresh failures on Pi 0.81.1 caused by the removed runtime `getOAuthApiKey` export.
53
- - Fixed potential credential races and permission changes caused by direct `auth.json` writes.
54
- - Fixed in-flight polling and selector requests surviving session shutdown or dialog disposal.
55
-
56
- ## [0.2.3] - 2026-06-10
57
-
58
- ### Fixed
59
-
60
- - **`DynamicBorder` is not defined** — added missing import of `DynamicBorder` from `@earendil-works/pi-coding-agent`. This fixes the `DynamicBorder is not defined` error when calling `/usage`.
61
-
62
- ### Changed
63
-
64
- - Updated repository URLs from `ajarellanod` to `hknet` in `package.json` and `README.md`.
65
- - Updated README image URLs to point to the `hknet` repository.
66
- - Updated LICENSE copyright to `ajarellanod (secondary: hknet)`.
67
-
68
- ### Removed
69
-
70
- - Removed stale tgz build artifacts and `package-lock.json` from the repository.
71
- - Removed `NOTE.md` compliance report (development artifact).
72
-
73
- ## [0.2.2] - 2026-06-10
74
-
75
- ### Fixed
76
-
77
- - **Keybinding violation in `UsageSelectorComponent`** — replaced `getKeybindings()` with the `keybindings` parameter injected by `ctx.ui.custom()`. Per the Pi extension docs, custom components must use the injected `KeybindingsManager` directly rather than calling `getKeybindings()` or `setKeybindings()`. This fixes a compliance issue that could cause unexpected behavior under custom keybinding configurations.
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ ## [0.4.2] - 2026-08-13
6
+
7
+ ### Fixed
8
+
9
+ - Added support for credit-based ZAI plan tiers that report `CREDIT_LIMIT` quota windows. Thanks to [@chrislucca](https://github.com/chrislucca) for the contribution in [#1](https://github.com/hknet/pi-usage-bars/pull/1).
10
+
11
+ ### Changed
12
+
13
+ - Updated the development and test baseline to Pi SDK 0.84.1 while retaining runtime compatibility with Pi 0.81.1 and newer.
14
+
15
+ ### Security
16
+
17
+ - Updated the Pi SDK development dependency chain to use `undici` 8.9.0, resolving the advisories affecting earlier 8.x releases.
18
+
19
+ ## [0.4.1] - 2026-07-31
20
+
21
+ ### Fixed
22
+
23
+ - Classify Codex quota windows by `limit_window_seconds` instead of assuming `primary_window` is always the session limit. Codex accounts that expose only a seven-day primary window now show it as Weekly and no longer display a fabricated `Session 0%` lane.
24
+
25
+ ### Changed
26
+
27
+ - Updated the development and test baseline to Pi SDK 0.83.0 while retaining runtime compatibility with Pi 0.81.1 and newer.
28
+
29
+ ## [0.4.0] - 2026-07-22
30
+
31
+ ### Added
32
+
33
+ - Added Kimi For Coding quota support through Pi's `kimi-coding` credential and the first-party five-hour/weekly usage endpoint.
34
+ - Added separate MiniMax Global and China Coding/Token Plan support, including the current token-plan endpoint and legacy coding-plan fallback.
35
+ - Added provider-specific quota labels and support for MiniMax responses that expose an interval quota without a weekly quota.
36
+ - Added neutral MiniMax purchased-Credits balance rendering when a key-authenticated first-party response exposes a balance.
37
+ - Added OpenRouter account balance and daily/weekly/monthly key spend using the first-party Credits and Key APIs.
38
+ - Added OpenRouter per-key limit bars only when the key has a real configured credit limit.
39
+ - Added DeepSeek total, topped-up, and granted balance support through the official key-authenticated balance API.
40
+ - Added separate Moonshot/Kimi API Global and China available, cash, and voucher balance support.
41
+ - Added a typed financial-metrics roadmap for further balance/spend providers.
42
+ - Added provider parsing, regional routing, endpoint fallback, financial rendering, authentication lifecycle, and smoke tests.
43
+ - Added CI, reproducible installs, production auditing, and a maintainer release guide.
44
+
45
+ ### Changed
46
+
47
+ - Treat MiniMax status `2062` as a neutral “No active Token Plan” account state rather than an API error; the cookie-only console balance endpoint remains out of scope.
48
+ - Expanded endpoint configuration documentation for Kimi, MiniMax, OpenRouter, DeepSeek, and Moonshot.
49
+ - Changed npm publishing to an explicit manual workflow so source tags cannot accidentally republish an already released version.
50
+ - Bumped the package version to 0.4.0.
51
+
52
+ ## [0.3.0] - 2026-07-22
53
+
54
+ ### Breaking changes
55
+
56
+ - Renamed the npm package to `@hk_net/pi-usage-bars`; install it with `pi install npm:@hk_net/pi-usage-bars`.
57
+ - Updated the minimum supported Pi release to 0.81.1.
58
+ - Removed Google Gemini CLI and Google Antigravity usage support, matching their removal from Pi 0.71.0.
59
+ - Refactored core usage orchestration to accept resolved provider tokens instead of reading or refreshing Pi credentials directly.
60
+
61
+ ### Added
62
+
63
+ - Added ZAI Coding Plan (China) provider and quota endpoint support.
64
+ - Added abort-aware polling and provider requests.
65
+ - Added strict TypeScript checking, a current-Pi smoke test, pinned development dependencies, and reproducible npm installs.
66
+ - Added Pi package gallery image metadata and documented endpoint/security behavior.
67
+
68
+ ### Changed
69
+
70
+ - Authentication now goes through `ctx.modelRegistry.getProviderAuth()`, allowing Pi to safely resolve and refresh credentials with its canonical locked credential store.
71
+ - Renamed Z.AI to the current Pi labels, ZAI Coding Plan (Global) and ZAI Coding Plan (China).
72
+ - Limited polling and custom `/usage` UI to interactive TUI mode.
73
+ - Made startup and model-change polling non-blocking and added complete session shutdown cleanup.
74
+ - Updated the selector to use typed TUI APIs, explicit render requests, abortable loading, and theme-safe invalidation.
75
+
76
+ ### Fixed
77
+
78
+ - Fixed OAuth refresh failures on Pi 0.81.1 caused by the removed runtime `getOAuthApiKey` export.
79
+ - Fixed potential credential races and permission changes caused by direct `auth.json` writes.
80
+ - Fixed in-flight polling and selector requests surviving session shutdown or dialog disposal.
81
+
82
+ ## [0.2.3] - 2026-06-10
83
+
84
+ ### Fixed
85
+
86
+ - **`DynamicBorder` is not defined** — added missing import of `DynamicBorder` from `@earendil-works/pi-coding-agent`. This fixes the `DynamicBorder is not defined` error when calling `/usage`.
87
+
88
+ ### Changed
89
+
90
+ - Updated repository URLs from `ajarellanod` to `hknet` in `package.json` and `README.md`.
91
+ - Updated README image URLs to point to the `hknet` repository.
92
+ - Updated LICENSE copyright to `ajarellanod (secondary: hknet)`.
93
+
94
+ ### Removed
95
+
96
+ - Removed stale tgz build artifacts and `package-lock.json` from the repository.
97
+ - Removed `NOTE.md` compliance report (development artifact).
98
+
99
+ ## [0.2.2] - 2026-06-10
100
+
101
+ ### Fixed
102
+
103
+ - **Keybinding violation in `UsageSelectorComponent`** — replaced `getKeybindings()` with the `keybindings` parameter injected by `ctx.ui.custom()`. Per the Pi extension docs, custom components must use the injected `KeybindingsManager` directly rather than calling `getKeybindings()` or `setKeybindings()`. This fixes a compliance issue that could cause unexpected behavior under custom keybinding configurations.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 ajarellanod and hknet
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ajarellanod and hknet
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,126 +1,127 @@
1
- # pi-usage-bars
2
-
3
- Quota, balance, and spend indicators for [Pi](https://github.com/earendil-works/pi).
4
-
5
- ![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)
6
-
7
- It adds:
8
-
9
- - a footer status bar for the active supported provider
10
- - a `/usage` command showing configured quota, balance, and spend data
11
-
12
- ## Supported providers
13
-
14
- | Provider | Pi provider ID | Authentication |
15
- | --- | --- | --- |
16
- | OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
17
- | Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
18
- | ZAI Coding Plan (Global) | `zai` | ZAI API key |
19
- | ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
20
- | Kimi For Coding | `kimi-coding` | Kimi Coding Plan API key |
21
- | MiniMax Coding Plan (Global) | `minimax` | MiniMax Global API key |
22
- | MiniMax Coding Plan (China) | `minimax-cn` | MiniMax China API key |
23
- | OpenRouter | `openrouter` | OpenRouter API key |
24
- | DeepSeek | `deepseek` | DeepSeek API key |
25
- | Moonshot/Kimi API (Global) | `moonshotai` | Moonshot Global API key |
26
- | Moonshot/Kimi API (China) | `moonshotai-cn` | Moonshot China API key |
27
-
28
- DeepSeek shows total, topped-up, and granted balances in the currency returned by the API. Moonshot shows available, cash, and voucher balances; this is separate from the Kimi For Coding subscription provider. Pi uses `MOONSHOT_API_KEY` for both Moonshot regions, so `/usage` automatically hides the expected authentication failure from the region where a shared environment key is not valid.
29
-
30
- OpenRouter shows the account credit balance and current daily, weekly, and monthly key spend. If the API key has a configured credit limit, that limit is also rendered as a usage bar.
31
-
32
- MiniMax Subscription Keys can represent an active Token Plan, purchased Credits, or both. The extension shows quota windows when present and a neutral credit-balance line if a first-party key-authenticated response exposes `points_balance`/`credits_balance`. MiniMax currently exposes Credits-only balances through a console endpoint requiring browser-cookie authentication, so a key-only Credits account is shown as “No active Token Plan” with a direction to check the console rather than a fabricated percentage. The extension does not import browser cookies.
33
-
34
- Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0.
35
-
36
- ## Requirements
37
-
38
- - Pi 0.81.1 or newer
39
- - Node.js 22.19 or newer when using the npm-distributed Pi CLI
40
-
41
- Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.
42
-
43
- ## Install
44
-
45
- Install the npm package:
46
-
47
- ```bash
48
- pi install npm:@hk_net/pi-usage-bars
49
- ```
50
-
51
- Or install the latest source directly from GitHub:
52
-
53
- ```bash
54
- pi install https://github.com/hknet/pi-usage-bars
55
- ```
56
-
57
- Restart Pi after installation, or use `/reload` when the package is already installed.
58
-
59
- Update an existing npm installation with:
60
-
61
- ```bash
62
- pi update npm:@hk_net/pi-usage-bars
63
- ```
64
-
65
- ## Use
66
-
67
- ### Footer usage bars
68
-
69
- When the active model belongs to a configured supported provider, the footer shows its available quota windows with reset countdowns when provided by the service.
70
-
71
- ![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)
72
-
73
- Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode.
74
-
75
- ### `/usage`
76
-
77
- Run `/usage` to open a searchable list of configured supported providers.
78
-
79
- ![/usage command](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
80
-
81
- ## Endpoint configuration
82
-
83
- First-party monitoring endpoints can be overridden:
84
-
85
- | Variable | Default |
86
- | --- | --- |
87
- | `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
88
- | `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
89
- | `PI_KIMI_USAGE_ENDPOINT` | `https://api.kimi.com/coding/v1/usages` |
90
- | `PI_MINIMAX_USAGE_ENDPOINT` | `https://api.minimax.io/v1/token_plan/remains` |
91
- | `PI_MINIMAX_LEGACY_USAGE_ENDPOINT` | `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` |
92
- | `PI_MINIMAX_CN_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/token_plan/remains` |
93
- | `PI_MINIMAX_CN_LEGACY_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` |
94
- | `PI_OPENROUTER_CREDITS_ENDPOINT` | `https://openrouter.ai/api/v1/credits` |
95
- | `PI_OPENROUTER_KEY_ENDPOINT` | `https://openrouter.ai/api/v1/key` |
96
- | `PI_DEEPSEEK_BALANCE_ENDPOINT` | `https://api.deepseek.com/user/balance` |
97
- | `PI_MOONSHOT_BALANCE_ENDPOINT` | `https://api.moonshot.ai/v1/users/me/balance` |
98
- | `PI_MOONSHOT_CN_BALANCE_ENDPOINT` | `https://api.moonshot.cn/v1/users/me/balance` |
99
-
100
- **Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.
101
-
102
- The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials.
103
-
104
- ## Financial metrics roadmap
105
-
106
- Quota percentages and monetary account data have different meaning and color semantics. OpenRouter, DeepSeek, Moonshot, and MiniMax financial data are rendered as neutral account values; percentages are used only when an actual limit exists. See [Financial metrics plan](docs/financial-metrics-plan.md) for the normalized model and future provider rollout.
107
-
108
- ## Development
109
-
110
- Install Node.js 22.19+ and Bun 1.3, then run:
111
-
112
- ```bash
113
- npm install
114
- npm run check
115
- ```
116
-
117
- `npm run check` performs a strict TypeScript check, runs the Bun test suite, and smoke-loads the extension with the pinned current Pi release.
118
-
119
- Maintainers should follow the complete [release and npm publication guide](docs/releasing.md). npm publication is manual; pushing a Git tag does not publish automatically.
120
-
121
- ## Credits
122
-
123
- This extension is based on and inspired by:
124
-
125
- - [CodexBar](https://github.com/steipete/CodexBar)
126
- - [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)
1
+ # pi-usage-bars
2
+
3
+ Quota, balance, and spend indicators for [Pi](https://github.com/earendil-works/pi).
4
+
5
+ ![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)
6
+
7
+ It adds:
8
+
9
+ - a footer status bar for the active supported provider
10
+ - a `/usage` command showing configured quota, balance, and spend data
11
+
12
+ ## Supported providers
13
+
14
+ | Provider | Pi provider ID | Authentication |
15
+ | --- | --- | --- |
16
+ | OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
17
+ | Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
18
+ | ZAI Coding Plan (Global) | `zai` | ZAI API key |
19
+ | ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
20
+ | Kimi For Coding | `kimi-coding` | Kimi Coding Plan API key |
21
+ | MiniMax Coding Plan (Global) | `minimax` | MiniMax Global API key |
22
+ | MiniMax Coding Plan (China) | `minimax-cn` | MiniMax China API key |
23
+ | OpenRouter | `openrouter` | OpenRouter API key |
24
+ | DeepSeek | `deepseek` | DeepSeek API key |
25
+ | Moonshot/Kimi API (Global) | `moonshotai` | Moonshot Global API key |
26
+ | Moonshot/Kimi API (China) | `moonshotai-cn` | Moonshot China API key |
27
+
28
+ DeepSeek shows total, topped-up, and granted balances in the currency returned by the API. Moonshot shows available, cash, and voucher balances; this is separate from the Kimi For Coding subscription provider. Pi uses `MOONSHOT_API_KEY` for both Moonshot regions, so `/usage` automatically hides the expected authentication failure from the region where a shared environment key is not valid.
29
+
30
+ OpenRouter shows the account credit balance and current daily, weekly, and monthly key spend. If the API key has a configured credit limit, that limit is also rendered as a usage bar.
31
+
32
+ MiniMax Subscription Keys can represent an active Token Plan, purchased Credits, or both. The extension shows quota windows when present and a neutral credit-balance line if a first-party key-authenticated response exposes `points_balance`/`credits_balance`. MiniMax currently exposes Credits-only balances through a console endpoint requiring browser-cookie authentication, so a key-only Credits account is shown as “No active Token Plan” with a direction to check the console rather than a fabricated percentage. The extension does not import browser cookies.
33
+
34
+ Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0.
35
+
36
+ ## Requirements
37
+
38
+ - Pi 0.81.1 or newer (tested with the current Pi 0.83.0 release)
39
+ - Node.js 22.19 or newer when using the npm-distributed Pi CLI
40
+
41
+ Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.
42
+
43
+ ## Install
44
+
45
+ Install the npm package:
46
+
47
+ ```bash
48
+ pi install npm:@hk_net/pi-usage-bars
49
+ ```
50
+
51
+ Or install the latest source directly from GitHub:
52
+
53
+ ```bash
54
+ pi install https://github.com/hknet/pi-usage-bars
55
+ ```
56
+
57
+ Restart Pi after installation, or use `/reload` when the package is already installed.
58
+
59
+ Update an existing npm installation with:
60
+
61
+ ```bash
62
+ pi update npm:@hk_net/pi-usage-bars
63
+ ```
64
+
65
+ ## Use
66
+
67
+ ### Footer usage bars
68
+
69
+ When the active model belongs to a configured supported provider, the footer shows its available quota windows with reset countdowns when provided by the service.
70
+
71
+ ![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)
72
+
73
+ Usage refresh runs in interactive TUI sessions every two minutes. It does not run in print, JSON, or RPC mode.
74
+
75
+ ### `/usage`
76
+
77
+ Run `/usage` to open a searchable list of configured supported providers.
78
+
79
+ ![/usage command](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
80
+
81
+ ## Endpoint configuration
82
+
83
+ First-party monitoring endpoints can be overridden:
84
+
85
+ | Variable | Default |
86
+ | --- | --- |
87
+ | `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
88
+ | `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
89
+ | `PI_KIMI_USAGE_ENDPOINT` | `https://api.kimi.com/coding/v1/usages` |
90
+ | `PI_MINIMAX_USAGE_ENDPOINT` | `https://api.minimax.io/v1/token_plan/remains` |
91
+ | `PI_MINIMAX_LEGACY_USAGE_ENDPOINT` | `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` |
92
+ | `PI_MINIMAX_CN_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/token_plan/remains` |
93
+ | `PI_MINIMAX_CN_LEGACY_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` |
94
+ | `PI_OPENROUTER_CREDITS_ENDPOINT` | `https://openrouter.ai/api/v1/credits` |
95
+ | `PI_OPENROUTER_KEY_ENDPOINT` | `https://openrouter.ai/api/v1/key` |
96
+ | `PI_DEEPSEEK_BALANCE_ENDPOINT` | `https://api.deepseek.com/user/balance` |
97
+ | `PI_MOONSHOT_BALANCE_ENDPOINT` | `https://api.moonshot.ai/v1/users/me/balance` |
98
+ | `PI_MOONSHOT_CN_BALANCE_ENDPOINT` | `https://api.moonshot.cn/v1/users/me/balance` |
99
+
100
+ **Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.
101
+
102
+ The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials.
103
+
104
+ ## Financial metrics roadmap
105
+
106
+ Quota percentages and monetary account data have different meaning and color semantics. OpenRouter, DeepSeek, Moonshot, and MiniMax financial data are rendered as neutral account values; percentages are used only when an actual limit exists.
107
+
108
+ ## Development
109
+
110
+ Install Node.js 22.19+ and Bun 1.3, then run:
111
+
112
+ ```bash
113
+ npm install
114
+ npm run check
115
+ ```
116
+
117
+ `npm run check` performs a strict TypeScript check and runs the Bun test suite.
118
+
119
+ Maintainers should follow the complete [release and npm publication guide](docs/releasing.md): prepare the release, stage it for npm browser approval, then finalize it after 2FA approval. Pushing a Git tag does not publish automatically.
120
+
121
+ ## Credits
122
+
123
+ This extension is based on and inspired by:
124
+
125
+ - [CodexBar](https://github.com/steipete/CodexBar)
126
+ - [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)
127
+ - [ajarellanod/pi-usage-bars](https://github.com/ajarellanod/pi-usage-bars)