A polished terminal dashboard for checking Codex usage limits, reset times, and reset-credit coupons.
The screenshot shows the final codex-limits terminal dashboard: a clean, read-only TUI that summarizes Codex usage limits and reset-credit coupons in one place. The top section displays the current 5-hour and weekly usage windows with remaining percentages, visual progress bars, and reset times, while the lower section shows available reset coupons, their expiration dates, and the next coupon deadline.
When you are working with Codex or agent-based coding tools, usage limits can interrupt your flow if you do not know what is left or when the next reset happens.
codex-limits gives you that information in one clean terminal view. It shows your current 5-hour and weekly usage windows, remaining percentages, progress bars, reset times, and reset-credit coupons when available, so you can quickly check your status and continue coding without leaving the terminal.
It also includes plain-text commands for quick checks, JSON output for scripts and automation, optional agent integrations through codex-limits init, and safe output that never prints tokens, account IDs, auth headers, cookies, or raw local files.
| Agent | Status | Agent command | Initi Command | Description |
|---|---|---|---|---|
| OpenCode | Supported | /codex-limits |
codex-limits init --opencode |
Opens a fast, read-only Codex limits dashboard directly inside OpenCode without sending the request to the LLM. |
The OpenCode integration adds a /codex-limits command that opens a compact modal inside the agent interface. It gives a quick read-only summary of the current 5-hour limit, weekly limit, and reset-credit coupons, then lets you close the view and return immediately to the conversation.
New agents can be added by creating a dedicated adapter under src/agents/<agent-name> and registering it in src/agents/index.ts. Each integration should keep the same goal: show Codex limit information quickly, safely, and without exposing tokens, account IDs, cookies, auth headers, or raw local files.
See the Contributing section if you want to add support for another agent.
codex-limits is built around a shared core with different output surfaces on top of it.
| Area | Path | Purpose |
|---|---|---|
| Package entry | src/package/index.ts |
Exports the CLI, TUI, and agent integration entry points. |
| Core logic | src/package/core |
Detects Codex data, reads local usage, fetches optional live information, normalizes usage windows, and keeps sensitive values out of the output. |
| CLI commands | src/package/commands |
Handles the dashboard, status, coupons, --json, and init commands. |
| Terminal UI | src/package/tui |
Renders the clean Ink-based dashboard from normalized usage data. |
| Agent integrations | src/agents |
Contains the shared agent integration layer and registers supported coding-agent adapters. |
| Tests | tests |
Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
This structure keeps the project easy to extend: the core decides what the data means, while the CLI, TUI, and agents only decide how that information is shown.
codex-limits works out of the box when it can find the required Codex data automatically. By default, it tries to detect the local Codex data directory and discover the information needed to show usage limits and reset-credit coupons. Most users do not need to configure anything manually.
Environment variables are only used as a fallback when automatic discovery is not enough, or when you want to override the default behavior.
| Variable | Purpose |
|---|---|
CODEX_LIMITS_HOME |
Manually sets the local Codex data directory when it cannot be detected automatically. |
CODEX_LIMITS_ACCESS_TOKEN |
Manually provides an access token for live reset-credit coupon data. |
CODEX_LIMITS_ACCOUNT_ID |
Manually provides the account ID used for live reset-credit coupon data. |
CODEX_LIMITS_USAGE_ENDPOINT |
Overrides the live usage endpoint, mainly for testing or advanced setups. |
Install codex-limits globally from npm:
npm install -g codex-limitsThen run it from any terminal:
codex-limits| Command | Description |
|---|---|
codex-limits |
Opens the interactive terminal dashboard. |
codex-limits status |
Prints a plain usage summary. |
codex-limits coupons |
Prints reset-credit coupon information. |
codex-limits --json |
Prints machine-readable usage data for scripts and automation. |
codex-limits init |
Installs optional agent integrations. |
codex-limits init --opencode |
Installs the OpenCode integration directly. |
codex-limits --help |
Prints the help text. |
codex-limits --version |
Prints the installed package version. |
Clone the repository, install dependencies, and run the CLI locally:
bun install
bun run devUseful development commands:
| Command | Description |
|---|---|
bun run dev |
Runs the CLI in development mode. |
bun run check |
Runs type checking, tests, and build validation. |
bun test |
Runs the test suite. |
bun run build |
Builds the package. |
This project is licensed under the MIT License. See LICENSE.