pi-codex-usage

A Codex usage extension for pi: shows ChatGPT Codex subscription usage, remaining limits, credits, and reset times.

Packages

Package details

extension

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

npm repohome report
$ pi install npm:pi-codex-usage
Package
pi-codex-usage
Version
0.3.4
Published
Aug 8, 2026
Downloads
515/mo · 30/wk
Author
avhagedorn
License
MIT
Types
extension
Size
75.3 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/codex-usage.ts"
  ],
  "image": "https://raw.githubusercontent.com/avhagedorn/pi-codex-usage/main/assets/with-extension.png"
}

Security note

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

README

pi-codex-usage

A Codex usage extension for pi.

What it does:

  • Shows your current ChatGPT Codex usage windows from the local Codex CLI app-server.
  • Shows a compact usage card above the editor with used/left percentages, reset times, plan, credits, and banked resets.
  • Keeps itself hidden by default; the usage card disappears automatically when you send your next prompt.
  • Can enable a persistent compact footer status that refreshes automatically every 60 seconds.
  • Registers a codex_usage tool so the agent can answer usage-limit questions directly.

Example output:

Codex usage — updated 7/9/2026, 11:08:00 PM
Plan: plus
5h limit:     [██████████░░] 82% used · 18% left · resets Fri, Jul 10, 2:28 AM (in 3h 21m)
Weekly limit: [██░░░░░░░░░░] 13% used · 87% left · resets Thu, Jul 16, 9:28 PM (in 7d)
Banked resets: 2 available, next expires Sun, Jul 26, 4:38 PM (in 17d)

Requirements

  • Codex CLI on PATH.
  • Codex signed in with ChatGPT auth:
codex login

This extension calls:

codex app-server --listen stdio://
account/rateLimits/read

If Codex auth is expired, run codex login or codex logout && codex login and retry.

Install

pi install npm:pi-codex-usage

Or from GitHub:

pi install git:github.com/avhagedorn/pi-codex-usage

Or try it for one run:

pi -e git:github.com/avhagedorn/pi-codex-usage

Reload or restart pi after installing:

/reload

Commands

/codex-usage          # fetch usage and show the card above the editor
/codex-usage status   # enable persistent footer status, refreshed every 60s
/codex-usage help     # show command help

By default the extension is hidden: it does not show a footer item or widget until you ask for usage. /codex-usage shows the popup widget, while /codex-usage status enables the footer status persistently for the current session, including when that session is reopened or Pi is reloaded.

Agent tool

The package also registers a codex_usage tool. The agent should use it when you ask things like:

  • “How much Codex usage do I have left?”
  • “When does my 5h Codex window reset?”
  • “What is my weekly Codex usage?”
  • “Do I have banked resets or credits?”

Notes

  • The data is account-level Codex usage, not pi-session-specific usage.
  • The Codex app-server protocol is experimental and may change in future Codex CLI releases.
  • API-key-only Codex setups may not expose ChatGPT subscription usage windows.