Skip to main content
plugin CX Codex

codex-quota-title — Codex plugin: quota display and setup

codex-quota-title shows remaining Codex quota and reset time in the Codex Desktop window title on Windows. The original title stays visible.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-quota-title@awesome-codex-plugins
Open on GitHub

What codex-quota-title does

The plugin adds quota details to a Codex Desktop window title, including the remaining percentage and reset date. It keeps the original title through %base_title%, while a configurable template can show weekly or five-hour quota fields. Profile settings are stored under %LOCALAPPDATA%\CodexQuotaTitle\<ProfileIdentity>\settings.json.

A profile-scoped helper starts with the Codex task and reads live rate-limit updates from Codex App Server. If App Server is unavailable, the helper uses the newest quota snapshot from Codex session rollouts. You can edit settings.json or use the bundled MCP tools codex_quota_title_get_settings and codex_quota_title_set_template.

Windows and Codex Desktop are required. The plugin changes a title only when exactly one visible Codex window can be matched to the Desktop process; ambiguous matches leave the title untouched. No API key is needed.

What it helps with

  • show remaining Codex quota beside the window title
  • display the next weekly or five-hour reset
  • keep the original Codex Desktop title in the template
  • change title formatting without restarting the helper
  • separate settings for different Codex profiles

Example prompts for the agent

  • Show the remaining weekly quota and its reset date in the Codex window title.
  • Open my CodexQuotaTitle settings.
  • Set the title template to %base_title% | 5h %5h_percent_remaining% (%5h_reset_relative%).

How to install codex-quota-title

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-quota-title@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about codex-quota-title

How do I install codex-quota-title in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins and then /plugin install codex-quota-title@awesome-codex-plugins. The two commands add the marketplace and install the plugin from it.

What does codex-quota-title do?

It places remaining Codex quota and reset information in the Codex Desktop window title. The original title can stay in place through %base_title%, and the layout is controlled by a template.

What does codex-quota-title require?

It requires Windows, Codex Desktop, and permission for the bundled MCP. The plugin starts the local codex app-server; an API key is not required.

Source text

CodexQuotaTitle · MIT
# CodexQuotaTitle

CodexQuotaTitle is a free, open-source Windows plugin for Codex Desktop. It automatically displays your remaining Codex quota in the title of the correctly correlated Codex window while preserving the title managed by Codex.

For example:

```text
Codex - Project | W 89% • 24/08 18:00
```

## Install in Codex Desktop

1. Open **Plugins** in Codex Desktop, then choose **Add Marketplace**.
2. Select **GitHub URL**.
3. Enter `https://github.com/nokisenpai/CodexQuotaTitle`.
4. Install **CodexQuotaTitle** from the marketplace and approve the requested plugin access.
5. Create or reopen a Codex Desktop task. The bundled MCP starts the profile-scoped helper automatically when the task/session is opened or resumed.

### Development installation

Development uses the local marketplace already configured on the developer machine. It is intentionally separate from the public marketplace above. Build the package locally with:

```powershell
.\scripts\publish-dev-plugin.ps1
```

## Automatic quota updates

The helper starts automatically when a Codex Desktop task/session is opened or resumed. It uses Codex App Server rate-limit updates and periodic resynchronization when App Server is available. Session rollout readers and watchers are started only when App Server is unavailable, so a working live connection never scans session history. If App Server cannot start or later becomes unavailable, the helper falls back to the newest profile-scoped quota snapshot from Codex session rollouts without discarding a newer App Server value. The fallback caches each rollout and reads appended bytes with a bounded rewrite check after its first scan; unchanged history is not reread. It updates a title only when it can correlate exactly one visible Codex Desktop window to the Desktop host process. If correlation is ambiguous, the title is left unchanged.

## Profile behavior

CodexQuotaTitle resolves the active profile from `CODEX_HOME`. When Codex Desktop does not pass that variable, it uses the current user's default `.codex` directory only if that directory exists. Each resolved profile has a stable, hashed `ProfileIdentity` and exactly one helper process, so separate Codex profiles keep separate settings and runtime state.

## Title template

The default template is:

```text
%base_title% | W %week_percent_remaining% • %week_reset_date%
```

`%base_title%` is the original Codex window title. This placeholder is optional; when omitted, the template becomes the complete visible window title. It can appear at most once. The renderer supports these quota placeholders:

- `%primary_percent_used%`, `%primary_percent_remaining%`, `%primary_reset_date%`
- `%secondary_percent_used%`, `%secondary_percent_remaining%`, `%secondary_reset_date%`
- `%5h_percent_used%`, `%5h_percent_remaining%`, `%5h_reset_date%`, `%5h_reset_relative%`
- `%week_percent_used%`, `%week_percent_remaining%`, `%week_reset_date%`, `%week_reset_relative%`

Missing quota values render as `—`. Unknown placeholders are retained literally so they remain visible for correction.

Examples:

```text
W %week_percent_remaining% | %base_title%
%base_title% | 5h %5h_percent_remaining% (%5h_reset_relative%)
Codex1 • %week_percent_remaining% • %week_reset_date%
```

## Configuration

Settings are profile-scoped and stored at:

```text
%LOCALAPPDATA%\CodexQuotaTitle\<ProfileIdentity>\settings.json
```

You can either ask Codex to **“Open my CodexQuotaTitle settings.”** (or equivalent), or open the file manually at the path above. The bundled `codex_quota_title_get_settings` MCP tool returns the exact resolved path for the current profile.

The file is created with these supported keys:

```json
{
  "template": "%base_title% | W %week_percent_remaining% • %week_reset_date%",
  "dateFormat": "dd/MM HH:mm",
  "enabled": true
}
```

When it is first created, `settings.json` includes a commented list of the supported placeholders. You can update the template through the bundled `codex_quota_title_set_template` MCP tool or by editing `settings.json`. The helper watches the file and applies valid changes without restarting.

## App Server and privacy

CodexQuotaTitle requires no API key. It launches the locally installed `codex app-server` for the active Codex profile and communicates with it through standard input/output to read the account summary and rate limits.

The plugin contains no custom telemetry, analytics SDK, HTTP client, or remote upload. Its diagnostics redact token-, cookie-, API-key-, and secret-like values. Codex App Server itself remains part of the Codex product and follows its own configuration and policies.

## Requirements and known limitations

- Windows and Codex Desktop are required; macOS and Linux are not supported.
- The plugin updates only one visible, unambiguously correlated Codex Desktop window. It does nothing when there are zero or multiple candidate windows.
- Codex Desktop must allow the bundled MCP. A usable Codex App Server provides the freshest values; session rollout snapshots are used as a fallback when it is unavailable.
- The rendered quota text depends on the quotas returned by the current Codex account; unavailable values display as `—`.
- Settings are local to the Windows user and the resolved Codex profile.

## Development

Prerequisites: Windows and the .NET 8 SDK.

```powershell
dotnet restore CodexQuotaTitle.sln
dotnet build CodexQuotaTitle.sln --configuration Release --no-restore
dotnet run --project tests\CodexQuotaTitle.Tests\CodexQuotaTitle.Tests.csproj --configuration Release --no-build
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidance.

## Support the project

CodexQuotaTitle is free and open source. If it is useful to you, you can support its development on [Ko-fi](https://ko-fi.com/nokisenpai).

© NoKi · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
codex-tasklist codex-tasklist is a plugin for Codex CLI that creates a live task panel, saves state to SQLite, and switches to tmux when native terminal panels are unavailable. CX Codex ★ 1,596repo stars codex-skin-pack-installer The codex-skin-pack-installer plugin stages and checks public-safe Codex skin packs from GitHub releases. Use it when a custom background, artwork, and a visible restore path matter. CX Codex ★ 1,596repo stars codex-rg-guard codex-rg-guard is a Claude Code plugin that narrows broad repository searches through a budgeted MCP tool. It selects files before returning bounded line matches. CX Codex ★ 1,596repo stars codex-reviewer codex-reviewer runs a secondary audit over AI-authored plans and pull requests. Catches architectural blind spots and unverified code before merge. CX Codex ★ 1,596repo stars codex-quota-optimizer codex-quota-optimizer is a Claude Code plugin that routes tasks to an adequate model and narrows repository context. It also applies layered checks. CX Codex ★ 1,596repo stars codex-process-jobs codex-process-jobs runs local builds, tests, and benchmarks as detached background processes on macOS and Linux, keeping status and logs after the agent turn ends. CX Codex ★ 1,596repo stars codex-multi-auth codex-multi-auth is a Claude Code and Codex plugin for managing ChatGPT accounts used by the official Codex CLI. It switches accounts and checks their health. CX Codex ★ 1,596repo stars codex-howto codex-howto is a plugin for Claude Code and Codex with nine skills that take Codex tasks from scoping through tests and diff review to an evidence handoff. It takes work beyond code generation. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open