English | 中文

Codex Usage, Not Guesswork

A local Codex Skill that turns your Codex remaining usage, reset times, token activity, and streaks into a compact dashboard you can keep open while working.

Philosophy: Keep your limits visible, so you can plan the work instead of discovering quota surprises in the middle of a long task.

Download the latest release · Installation · Changelog

The author's panel, captured in September 2026. The bundled skill starts with sample data and switches to your own Codex account and local session activity after sync. Available quota windows and reset credits depend on the account.

What You Get

A local dashboard for Codex with:

• Remaining usage for the current short window and weekly window
• Progress bars and reset times that match Codex's local usage data
• Local profile display generated from your Codex account, with optional name/avatar override
• A 26-week Token activity heatmap
• Lifetime tokens, peak token day, longest task, and streak stats
• One-click refresh and a compact collapsed view
• Optional auto-open hook for new Codex conversations
• English and Chinese docs

Quick Start

1. Install the skill in Codex
2. Say "install Codex usage panel" or invoke $codex-usage-panel
3. The agent installs the dashboard conversationally — no config files to edit

The agent will:

• Copy the panel to ~/.codex-usage-panel
• Start a local dashboard server
• Start a background usage sync process
• Open the panel at http://127.0.0.1:8765/index.html

No API keys needed. Your first sync runs immediately after setup.

Changing Settings

The panel can be managed through conversation. Just tell Codex:

• "Open my Codex usage panel"
• "Repair the usage panel"
• "Use port 8876"
• "Refresh usage data"
• "Auto-open the panel in new conversations"
• "Set my panel profile name and avatar"
• "Package this skill for sharing"

If port 8765 is busy, the installer automatically chooses a nearby available port and prints the final dashboard URL.

On macOS, the installer now avoids accidental port drift by stopping its own old service before selecting a port. If a previous install used another port, it also keeps that old URL alive as a compatibility alias. You can add one explicitly:

node ~/.codex/skills/codex-usage-panel/scripts/install-panel.mjs --port 8765 --alias-port 8766 --open

Reinstalling keeps ~/.codex-usage-panel/profile.json and preserves local avatar files referenced from it, such as ./profile-avatar.png.

Auto-Open in New Conversations

Codex does not currently have a built-in setting that pins a custom HTML panel inside every conversation. This skill includes a local SessionStart hook that gets you close: when Codex starts or resumes a conversation, the hook opens the usage panel URL in Codex.

Enable it:

node ~/.codex/skills/codex-usage-panel/scripts/install-auto-open-hook.mjs

Remove it:

node ~/.codex/skills/codex-usage-panel/scripts/install-auto-open-hook.mjs --remove

The first time the hook runs, Codex may ask you to review and trust it. By default, the hook reads the panel's current local port whenever it runs, so it follows automatic port selection and later port changes. If no valid configuration exists, it falls back to http://127.0.0.1:8765/index.html.

For a custom panel install directory, pass --root /path/to/panel when enabling the hook. Use --url to pin a specific dashboard URL, or set CODEX_USAGE_PANEL_URL to override it at runtime.

Customizing the Panel

You can customize it two ways:

Through conversation (recommended): Tell Codex what you want — "Make it more compact", "show only 3 months", "change the accent color", or "hide streak stats". Codex can edit the panel for you.

Direct editing (power users): Edit the files in assets/panel/:

• index.html — panel structure
• panel.css — layout and visual style
• panel.js — refresh, collapse, heatmap, and rendering logic
• usage-data.js — sample fallback data, overwritten by sync after install

Changes take effect after reinstalling or reloading the local panel.

Profile Display

Codex's local app-server currently exposes account email and plan, but not the ChatGPT display nickname or avatar URL. The panel uses that local account data to generate a personal display name, handle, and initials avatar instead of a shared default.

For exact profile details, create ~/.codex-usage-panel/profile.json:

{
  "name": "Luke_Ji",
  "handle": "@jasondongsheng",
  "avatarUrl": "https://example.com/avatar.png"
}

Then run:

node ~/.codex-usage-panel/scripts/sync-usage.mjs --root ~/.codex-usage-panel

You can also set it during install. --profile-avatar accepts either an image URL or a local image path:

node ~/.codex/skills/codex-usage-panel/scripts/install-panel.mjs --profile-name "Luke_Ji" --profile-handle "@jasondongsheng" --profile-avatar ~/Pictures/avatar.png --open

Default Views

Remaining Usage

Shows the current short-window quota, weekly quota, reset credits, progress bars, and reset times.

Token Activity

Shows 26 weeks of daily Token activity as a compact heatmap, with daily, weekly, and cumulative display modes.

Token Summary

Shows lifetime tokens, peak token day, longest task, current streak, and longest streak.

See examples/sample-panel.md for a quick output tour.

Installation

Codex

git clone https://github.com/noskinodesign/codex-usage-panel-skill.git ~/.codex/skills/codex-usage-panel

Then open Codex and say:

Use $codex-usage-panel to install and open a local Codex usage dashboard.

You can also run the installer directly:

node ~/.codex/skills/codex-usage-panel/scripts/install-panel.mjs --open

Release Zip

Download codex-usage-panel-skill.zip from the latest GitHub release, then:

mkdir -p ~/.codex/skills
unzip codex-usage-panel-skill.zip -d ~/.codex/skills

Update an Existing Installation

For a Git clone, update the skill and run the installer again:

git -C ~/.codex/skills/codex-usage-panel pull --ff-only
node ~/.codex/skills/codex-usage-panel/scripts/install-panel.mjs

For a release zip, replace the skill folder with the latest download, then run the same installer. If auto-open is enabled, run its installer again to update the hook. Reinstalling preserves the panel's local profile and avatar.

Requirements

• macOS
• Codex desktop app installed
• Node.js

That's it. No external account, cloud backend, or usage API key required.

How It Works

1. The installer copies the dashboard to ~/.codex-usage-panel
2. A local server serves the HTML panel on 127.0.0.1
3. A sync process reads Codex desktop app-server usage and local account metadata every 10 seconds
4. The panel reloads the local usage-data.js file and updates itself

When upgrading on macOS, the installer also disables the early prototype com.lukeji.codex-usage-panel-* LaunchAgents and keeps a previous dashboard port alive when it changed, so old links in Codex conversations keep working.

The sync process reads local Codex app-server methods such as account/rateLimits/read, account/usage/read, and account/read.

Privacy

• No API keys are required
• No external analytics
• No usage data is uploaded by this project
• No account credentials are stored by this project
• Profile overrides stay local in ~/.codex-usage-panel/profile.json
• Usage data stays on your machine in ~/.codex-usage-panel

Limitations

Codex does not currently support injecting a custom HTML panel into every conversation body. The recommended setup is to keep the panel open in the Codex side browser, use the included auto-open hook, or keep it in a small browser window.

License

MIT