pi-usage-limits

[![npm](https://img.shields.io/npm/v/pi-usage-limits)](https://www.npmjs.com/package/pi-usage-limits)

Packages

Package details

extension

Install pi-usage-limits from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:pi-usage-limits
Package
pi-usage-limits
Version
0.1.5
Published
Nov 3, 2026
Downloads
376/mo · 265/wk
Author
ailinykh
License
MIT
Types
extension
Size
16.8 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-usage-limits

npm

A pi extension that shows your Claude and Codex subscription limits in pi's status line and updates them after every prompt.

5h: 12%, 7d: 25%

Why use it

  • Works with Claude through the Claude Agent SDK. It reads limits with your existing Claude Code login, so it works when pi runs Claude models through the SDK, including pi-claude-bridge. You don't need a separate Anthropic login or API key in pi.
  • Codex support, no CLI needed. Reads 5-hour and weekly Codex limits over HTTPS with pi's own openai-codex login. pi refreshes the token; ~/.codex/auth.json is never read or touched.
  • Never slows pi down. Usage is fetched in the background, and pi doesn't wait for it.
  • Updates after each prompt. It refreshes when a session starts, when you switch models, and once each prompt finishes, instead of on every turn or tool call.
  • Fewer calls with several sessions. Results are cached on disk for 60 seconds, and the cache is shared between all running pi sessions. A cached value is marked with 󰃨.
  • Doesn't replace your footer. It adds one status entry, so pi's built-in footer and other extensions keep working.
  • No tokens used. Reading limits sends no prompt and doesn't touch your quota.
  • Clear errors. If a lookup fails, the status line shows the reason in red, such as the Claude CLI's own error.
  • Small and readable. A few hundred lines of plain TypeScript, with no build step.

Supported models

Active model Source Shows
openai provider, including gpt-6.1-sol No quota lookup OpenAI usage unavailable; check usage dashboard
openai-codex provider, or a non-openai model id containing codex ChatGPT usage endpoint (pi's openai-codex login) 5-hour and weekly usage
Model id contains claude Claude Agent SDK (Claude Code login) 5-hour and 7-day utilization

The openai provider's Sign in with ChatGPT flow has no documented quota endpoint. Check ChatGPT → Settings → Usage, as OpenAI recommends. For API-key authentication, check the OpenAI API usage dashboard instead. This extension never substitutes openai-codex credentials or cached limits for openai, even when the model id contains codex.

Other models show <model> not supported yet.

Requirements

  • pi
  • For Claude: @anthropic-ai/claude-agent-sdk installed alongside pi (for example as a pi-claude-bridge dependency), signed in to a Claude subscription. API-key logins have no subscription limits to show.
  • For Codex: signed in to pi's openai-codex provider (/login in pi) with a ChatGPT subscription.

Install

pi install npm:pi-usage-limits

Try it for a single session without installing:

pi -e npm:pi-usage-limits

How it works

Event Action
session_start Show current usage
model_select Show usage for the new model
agent_settled Refresh after a prompt completes

The cache lives at ~/.pi/agent/cache/pi-usage-limits.json. Entries pair each source's limits with a fetch timestamp and expire after 60 seconds. Codex entries also record the account ID and are used only after checking the current login. Limits are shared across models using the same usage source, never between openai and openai-codex.

Writes use atomic replacement and a lockfile for read-modify-write updates. The lock does not deduplicate concurrent API refreshes. Malformed or incompatible entries are treated as cache misses; the old cache format is discarded on the next save. Cache I/O failures produce console diagnostics but do not prevent displaying freshly fetched limits. Refresh failures still surface as errors rather than silently serving stale limits.

Caveats

  • Claude limits come from an experimental Claude Agent SDK API, which may change in a future SDK release. The cache assumes one Claude Code login per agent directory; switching Claude accounts may show the previous account's limits for up to 60 seconds.
  • Codex limits come from an undocumented ChatGPT endpoint (chatgpt.com/backend-api/wham/usage, the same one the Codex CLI uses), which may change without notice.
  • Each uncached Claude lookup starts a short-lived claude process, which takes about a second. It runs in the background.

Development

Run the cache regression tests with npm test. Tests use a temporary agent directory and mocked HTTP responses; they do not access your real cache or subscription endpoints.

License

MIT