pi-openai-usage

Shows your remaining OpenAI Codex subscription usage in Pi.

Usage: 5h ████████░░ 88% | 7d ███████░░░ 73% | 5h ↺ 42m | 7d ↺ 2d4h

Prerequisites

• Pi CLI.
• An OpenAI subscription.

Install

pi install npm:pi-openai-usage

Login

This extension uses Pi's existing OpenAI Codex login. If you have not logged in yet, run:

/login openai-codex

Command

/openai-usage-settings is the command for OpenAI usage and settings.

Run it with no arguments in Pi's interactive UI to open the settings menu. In non-UI runs, it shows a read-only fallback with the available utility subcommands.

/openai-usage-settings
/openai-usage-settings usage
/openai-usage-settings refresh
/openai-usage-settings diagnostics
/openai-usage-settings help

Utility subcommands

Use utility subcommands when you want a direct status check, refresh, diagnostics, or help:

Subcommand	What it does
usage	Show cached usage, refreshing first if the cache is missing or stale.
refresh	Force a usage refresh and show the updated usage status.
diagnostics	Show setup, auth, config-path, timestamp, and last-error diagnostics without printing tokens.
help	Show command help for the one-command workflow.

Example form: /openai-usage-settings usage.

Interactive settings menu

Running /openai-usage-settings with no arguments opens a ten-row menu for common settings:

Row	Visible values
Display	On, Off, Always
Color scheme	traffic, cyan, green, mono, none
Bar style	blocks, thin, ascii, dots, squares, braille
Bar width	4, 6, 8, 10, 12, 16, 20
5h display	hidden, percent, bar, bar + percent
7d display	hidden, percent, bar, bar + percent
5h reset display	hidden, countdown, clock, both
7d reset display	hidden, countdown, clock, both
Refresh interval	15s, 30s, 1m, 2m, 5m, 10m
Hide label	No, Yes

Display controls whether the status line is shown normally, hidden, or always shown. Normal display appears for OAuth-backed openai and openai-codex models; Always shows usage regardless of the selected model. Hide label controls the Usage: prefix. If a JSON config uses a custom color scheme or custom bar style, the menu may show custom (JSON) as the current value; selecting a preset replaces it with that preset.

Configuration files

Configuration is read from:

1. Project config: .pi/extensions/pi-openai-usage.json
2. Global config: ~/.pi/agent/extensions/pi-openai-usage.json

Project config overrides global config.

The interactive menu writes to the project config only when .pi/extensions/pi-openai-usage.json already exists. Otherwise, menu changes are written to the global config. Create the project config file first if you want menu changes to stay project-local.

Use the interactive menu for common display settings. Advanced visual customization is JSON-file-only: edit the project or global config file for custom label text, widget labels, separators, partial bars, custom bar glyphs, custom color stops or targets, and bar-gradient controls. Slash-command setting writes are not supported.

JSON configuration reference

Top-level settings

Key	Type	Default	Accepted values / notes
enabled	boolean	true	Enables or hides the status-line entry.
refreshIntervalMs	number	60000	15000, 30000, 60000, 120000, 300000, 600000.
display	object	see below	Status-line label and visibility presentation.
widgets	object	see below	Usage and reset widgets.
bar	object	see below	Progress-bar style and width.
colors	object	see below	Color scheme, target, gradients, and custom stops.

display

Key	Type	Default	Accepted values / notes
display.showAlways	boolean	false	true shows usage even when the selected model is not an OAuth-backed OpenAI/Codex model.
display.showLabel	boolean	true	Controls the label prefix.
display.label	string	"Usage"	Non-empty string.
display.separator	string	`"	"`

widgets

Key	Type	Default	Accepted values / notes
widgets.fiveHour.enabled	boolean	true	Shows or hides the 5h usage widget.
widgets.fiveHour.label	string	"5h"	Non-empty string.
widgets.fiveHour.mode	string	"bar-percent"	percent, bar, bar-percent, hidden.
widgets.sevenDay.enabled	boolean	true	Shows or hides the 7d usage widget.
widgets.sevenDay.label	string	"7d"	Non-empty string.
widgets.sevenDay.mode	string	"bar-percent"	percent, bar, bar-percent, hidden.
widgets.fiveHourReset.enabled	boolean	true	Shows or hides the 5h reset widget.
widgets.fiveHourReset.label	string	"5h ↺"	Non-empty string.
widgets.fiveHourReset.mode	string	"countdown"	countdown, clock, both, hidden.
widgets.sevenDayReset.enabled	boolean	true	Shows or hides the 7d reset widget.
widgets.sevenDayReset.label	string	"7d ↺"	Non-empty string.
widgets.sevenDayReset.mode	string	"countdown"	countdown, clock, both, hidden.

bar

Key	Type	Default	Accepted values / notes
bar.style	string	"blocks"	blocks, thin, ascii, dots, squares, braille, custom.
bar.width	number	10	4, 6, 8, 10, 12, 16, 20.
bar.partials	boolean	true	Uses partial glyphs when the selected style supports them.
bar.custom.filled	string	"▰"	Filled glyph used when bar.style is custom.
bar.custom.empty	string	"▱"	Empty glyph used when bar.style is custom.
bar.custom.partials	string[]	[]	Optional partial glyphs used when bar.style is custom and bar.partials is true.

colors

Key	Type	Default	Accepted values / notes
colors.scheme	string	"traffic"	traffic, cyan, green, mono, none, custom.
colors.target	string	"value"	value, widget, bar, percent, none.
colors.barGradient.enabled	boolean	false	Colors filled bar cells across the selected color scale.
colors.barGradient.direction	string	"low-to-high"	low-to-high, high-to-low.
colors.custom.mode	string	"step"	step, gradient.
colors.custom.stops	array	see below	Array of color stops sorted by percent.

Default colors.custom.stops:

percent	color	label
80	success	success
60	#65a30d	lime/olive
40	warning	warning
20	#c2410c	orange
0	error	error

Each custom color stop has this shape:

Key	Type	Accepted values / notes
percent	number	Clamped to 0 through 100.
color	string or number	Pi theme token (success, warning, error, muted, dim, text, accent) for step mode, #RRGGBB, or xterm color number 0 through 255. Gradient mode supports interpolating #RRGGBB and xterm colors.
label	string	Optional label for your own reference.

Display customization

The default display uses progress bars and percentages:

Usage: 5h ████████░░ 88% | 7d ███████░░░ 73% | 5h ↺ 42m | 7d ↺ 2d4h

To simplify it in the interactive menu, set:

• Hide label: Yes
• 5h display: percent
• 7d display: percent
• 5h reset display: hidden
• 7d reset display: hidden

Result:

5h: 88% | 7d: 73%

To use the neutral footer text colour instead of usage-coloured values, set Color scheme to none.

Privacy and auth

The extension uses Pi's existing openai-codex OAuth credentials to request Codex usage from ChatGPT's usage endpoint. Diagnostics are designed for troubleshooting and do not print access tokens.

Reference attribution

Inspired by pi-better-openai.