A polished terminal dashboard for checking Codex usage limits, reset times, and reset-credit coupons.
The screenshots show the codex-limits terminal dashboards: clean, read-only TUIs that summarize 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.
- Quick start
- Requirements
- Overview
- Agent integrations
- How it works
- Environment
- Usage
- Troubleshooting
- Local development
- Security
- License
- Contributors
The package is available on npm as @simonesiega/codex-limits and supports Node.js 20 or newer.
Install codex-limits globally from npm:
npm install -g @simonesiega/codex-limits@latestThe @latest tag ensures you install the latest published version.
Then run it from any terminal:
codex-limitsThe list of available commands is shown when you run codex-limits --help or in the Usage section.
Install optional agent integrations with their named flag:
codex-limits init --<agent-name>For example, install the OpenCode integration:
codex-limits init --opencode| Requirement | Details |
|---|---|
| Node.js | Node.js 20 or newer is required to run the published CLI. Bun is only required for local development. |
| Codex | For normal use, Codex should already be installed and authenticated so codex-limits can discover its local data and credentials. Advanced setups can provide supported environment overrides instead. |
| Operating systems | Windows, macOS, and Linux are supported through their standard Codex data locations. Use CODEX_LIMITS_HOME or CODEX_HOME if your data is stored elsewhere. |
| Internet connection | Local usage fallback can work offline. An internet connection is required for current live usage and reset-credit coupon information; unavailable network data is reported safely without breaking the dashboard. |
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 | Init 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. |
Agent integrations are not enabled automatically during package installation. They must be installed with codex-limits init and are only available in the agent terminal after a restart. See Adding new agents if you want to add support for another agent.
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 guide 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 |
|---|---|---|
| CLI entry | src/package/cli.ts |
Starts the codex-limits command and routes to the dashboard, plain-text commands, JSON output, and init. |
| 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 optional coding-agent adapters that users install with codex-limits init. |
| 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 |
Overrides the local Codex data directory before all other candidates. |
CODEX_HOME |
Uses Codex's native home override when CODEX_LIMITS_HOME is not set. |
CODEX_LIMITS_ACCESS_TOKEN |
Provides an access token for authenticated live usage and reset-credit requests. |
CODEX_LIMITS_ACCOUNT_ID |
Provides the account ID paired with CODEX_LIMITS_ACCESS_TOKEN. |
CODEX_LIMITS_USAGE_ENDPOINT |
Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
CODEX_LIMITS_SKIP_INIT |
Suppresses optional global-install setup guidance from the non-interactive postinstall. |
Local Codex data is inspected read-only with bounded file, directory, JSONL, and response limits. Credentials, raw files, and private paths are excluded from public output. Live requests require HTTPS, except for loopback HTTP during local testing. See SECURITY.md for the complete data-access and network-safety model.
| 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 coupons --json |
Prints machine-readable reset-credit coupon data only. |
codex-limits --json |
Prints machine-readable usage and coupon data. |
codex-limits init |
Prompts for optional agent integrations in an interactive TTY. |
Use codex-limits init to install optional agent integrations. Installation only updates the selected agent configuration; it does not send a prompt to an LLM or modify Codex data.
| Command | What it does |
|---|---|
codex-limits init |
Prompts for every supported integration when stdin and stdout are interactive terminals. If no integration is selected, nothing is installed. |
codex-limits init --help or codex-limits init -h |
Prints the init command help without changing any configuration. |
codex-limits init --all |
Installs every supported integration without prompting. |
codex-limits init --opencode |
Installs only the OpenCode integration, which adds /codex-limits to OpenCode. |
codex-limits init --<agent-name> |
Installs only the named supported integration. Replace <agent-name> with an integration listed in Supported agents. |
--all cannot be combined with a named integration flag. Duplicate, unknown, and positional arguments are rejected. In a non-interactive terminal, use --all or a named integration flag instead of running codex-limits init without options.
Make sure Codex has been run and authenticated at least once. If its data is stored outside the standard location, set CODEX_LIMITS_HOME or CODEX_HOME to the Codex data directory, then run codex-limits status again.
Run codex-limits status to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
Confirm that your user can read the selected Codex directory and its session files. Do not run the CLI with elevated privileges unless your Codex installation explicitly requires it. Prefer correcting the directory permissions or selecting the correct directory with CODEX_LIMITS_HOME.
Run the named initializer again, for example codex-limits init --opencode, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
Clone the repository, install dependencies, and run the CLI locally:
git clone https://github.com/simonesiega/codex-limits.git
cd codex-limits
bun install
bun run devUseful development commands:
| Command | Description |
|---|---|
bun run dev |
Runs the CLI in development mode. |
bun run check |
Runs formatting, types, tests, builds, and package smoke checks. |
bun test |
Runs the test suite. |
bun run build |
Builds the package. |
bun run format |
Formats the repository with Prettier. |
bun run format:check |
Checks formatting without changing files. |
For vulnerability reports and local data safety details, see SECURITY.md.
This project is licensed under the MIT License. See LICENSE.