Monitor Codex usage limits, reset times, and reset credits without leaving your terminal.
Installation · Showcase · Usage · Integrations · Documentation · Contributing
## Overview
**Codex Limits** gives you a fast view of your Codex usage without interrupting your coding flow. Check remaining capacity, reset times, and reset credits through an interactive dashboard or lightweight terminal commands.
It also provides stable JSON output for automation, safe diagnostics, shell completions, and optional integrations for supported coding agents. Reset-credit redemption is isolated behind an explicit interactive confirmation flow, and public output excludes sensitive credentials, account IDs, private paths, and raw local files.
See the dedicated [visual showcase](SHOWCASE.md) to compare the dashboard, compact CLI, and agent-integrated experience.
## Quick start
Install the published npm package globally:
```bash
npm install -g @simonesiega/codex-limits@latest
```
Open the dashboard:
```bash
codex-limits
```
For a quick non-interactive check:
```bash
codex-limits status
```
## Requirements
The published CLI requires Node.js 20 or newer. It supports Windows, macOS, and Linux and discovers existing Codex authentication and usage data automatically when available.
See [Compatibility](docs/guides/compatibility.md) for the canonical runtime, installation, platform, Codex-data, terminal, network, and agent-host requirements.
## Usage
| Command | Description |
| --------------------------------------------- | ----------------------------------------------------- |
| `codex-limits` | Opens the interactive terminal dashboard. |
| `codex-limits status` | Prints a plain usage summary. |
| `codex-limits status --threshold ` | Checks a remaining-usage threshold for automation. |
| `codex-limits coupons` | Prints available reset credits. |
| `codex-limits coupons --json` | Prints machine-readable reset-credit data. |
| `codex-limits reset ` | Reviews and redeems the selected reset credit. |
| `codex-limits reset --soonest` | Reviews and redeems the credit that expires first. |
| `codex-limits --json` | Prints machine-readable usage and reset-credit data. |
| `codex-limits doctor` | Prints safe environment and connectivity diagnostics. |
| `codex-limits doctor --json` | Prints machine-readable diagnostics. |
| `codex-limits completions ` | Generates completions for five supported shells. |
| `codex-limits agents` | Shows agent integration management commands. |
| `codex-limits agents install ` | Installs one or more named agent integrations. |
| `codex-limits agents install --all` | Installs every supported agent integration. |
| `codex-limits agents uninstall ` | Removes one or more recognized agent integrations. |
| `codex-limits agents uninstall --all` | Removes every recognized agent integration. |
| `codex-limits init` | Runs the compatible integration installation flow. |
Run `codex-limits --help` or a command-specific `--help` option for generated CLI help.
### Reset credit redemption
`codex-limits reset` is the only remote-mutation command. It refreshes reset-credit data, displays a recap, and proceeds only in an interactive terminal after an explicit `y` or `yes`.
See [Command safety boundaries](SECURITY.md#command-safety-boundaries) for the canonical safety behavior.
### Diagnostics and automation
Use the read-only diagnostic command when Codex data, authentication, connectivity, or an integration is unavailable:
```bash
codex-limits doctor
```
For scripts and automation, use the supported JSON commands and threshold checks documented in [JSON output](docs/guides/json-output.md), including their stable contracts, schemas, sanitized examples, and exit-code behavior.
### Shell completions
Generate a completion script for Bash, Zsh, Fish, PowerShell, or Nushell:
```text
codex-limits completions
```
See [Shell completions](docs/guides/shell-completions.md) for installation steps and an explanation of how registry-driven generation works.
## Agent integrations
Codex Limits can expose the same local, read-only summary inside supported coding agents. Integrations are optional, do not receive reset capabilities, and must be installed separately.
Supported integrations expose `/codex-limits` directly inside the agent:
| Agent | Install command | Guide |
| ------------------ | -------------------------------------- | ---------------------------------------------------------- |
| OpenCode | `codex-limits agents install opencode` | [OpenCode setup and usage](docs/guides/agents/opencode.md) |
| pi | `codex-limits agents install pi` | [pi setup and usage](docs/guides/agents/pi.md) |
| GitHub Copilot CLI | `codex-limits agents install copilot` | [Copilot setup and usage](docs/guides/agents/copilot.md) |
Restart the agent after installation or removal so it reloads its configuration.
See the [Agent integrations guide](docs/guides/agent-integrations.md) for shared lifecycle modes, safety boundaries, and integration architecture.
## Architecture overview
Codex Limits keeps shared behavior centralized and exposes it through focused output surfaces:
| Area | Path | Responsibility |
| ------------------ | ---------------------- | ----------------------------------------------------------------------- |
| CLI entry | `src/package/cli.ts` | Starts `codex-limits` and delegates to the command registry. |
| Core | `src/package/core` | Discovery, normalization, authenticated reads, warnings, and redaction. |
| Commands | `src/package/commands` | CLI parsing, help, safety categories, and command orchestration. |
| Terminal UI | `src/package/tui` | Rendering normalized data with Ink. |
| Agent integrations | `src/agents` | Thin host-specific installation and read-only presentation layers. |
| Tests | `tests` | Behavior, output, safety, and integration coverage. |
Supported public interfaces and package compatibility boundaries are documented in [Compatibility](docs/guides/compatibility.md#runtime-and-installation).
## Documentation
Start with the [documentation hub](docs/README.md), or jump directly to:
- [Compatibility](docs/guides/compatibility.md) for runtime, platform, Codex-data, network, terminal, and agent-host requirements.
- [JSON output](docs/guides/json-output.md) for stable machine-readable contracts, schemas, thresholds, and automation.
- [Troubleshooting](docs/guides/troubleshooting.md) for Codex data, authentication, network, terminal, reset-credit, and integration problems.
- [Agent integrations](docs/guides/agent-integrations.md) for supported agents, lifecycle behavior, safety boundaries, and adapter architecture.
Contributor, security, changelog, schema, example, and integration-specific documentation are also indexed from the documentation hub.
## Local development
```bash
git clone https://github.com/simonesiega/codex-limits.git
cd codex-limits
bun install
bun run dev
```
Use Bun for repository development. See [Contributing](CONTRIBUTING.md#local-development) for the full development and validation workflow.
## Security
Inspection commands are read-only. Agent lifecycle commands write only recognized host configuration, and reset-credit redemption is isolated behind explicit interactive confirmation.
See [`SECURITY.md`](SECURITY.md) for data-access safeguards, command boundaries, and private vulnerability reporting.
## License
Codex Limits is licensed under the [MIT License](LICENSE).
## Contributors
