Usage Planner

What usage-planner does

usage-planner turns OpenAI Codex quota information into a forward-looking usage plan. It accounts for the remaining quota, the current usage pace, banked resets, normal weekly refreshes, and possible extra resets. The result is a two-week timeline showing daily usage, remaining capacity, predicted run-out points, outages, refills, and planned banked-reset use.

Five strategies change the resulting plan:

• Keep pace follows the current rate and shows when the quota is expected to run out.
• Keep available preserves capacity rather than spending it as quickly.
• Use it all schedules usage to empty the quota shortly before the next refill.
• Weekdays only concentrates planned use on weekdays.
• Weekend focus shifts planned use toward weekends.

The planner is unofficial and is not affiliated with OpenAI. It does not redeem resets or spend credits automatically.

How it works

The MCP interface uses the same planning rules as the website and Codex plugin page. A signed-in Codex CLI on the local machine supplies quota and banked-reset information; reading that information is local and read-only, and does not require a separate API key.

Extra-reset estimates use public reset history and public posts. A predicted reset is included only when its estimated chance of arriving before the applicable normal refresh reaches at least 60 percent. The timeline places it at a conservative time rather than simply using the most likely hour. The number of counted predicted resets can be changed to zero, one, or two.

Each refill starts a new seven-day window, whether it comes from a normal refresh, an extra reset, or a banked reset. Banked resets are assigned to cover outages, with the earliest expiry handled first. The planning rules normally retain the last banked reset for an outage lasting at least 24 hours, while a reset close to expiry may be used instead of wasted.

Forecasts are model estimates and are not guarantees. Public reset data is sourced from Codex Resets, including a bundled offline archive.

Setup and configuration

For the Codex plugin, use Node.js 20 or newer and a signed-in Codex app or CLI:

codex plugin marketplace add ItsOdeLeo/usage-planner
codex plugin add usage-planner@usage-planner

After installation, start a new Codex chat and ask to open quota planning. The plugin reads the local Codex quota and banked resets without an additional API key.

Other MCP clients can launch the npm package with a standard stdio configuration:

{
  "mcpServers": {
    "usage-planner": {
      "command": "npx",
      "args": ["-y", "usage-planner"]
    }
  }
}

The same planner is also available at usageplanner.com without installation. That browser version accepts quota values manually, performs calculations in the browser, and does not send those inputs elsewhere. To work on the project locally, install dependencies with npm install, then run npm run web for the local site or npm run mcp for the MCP server from source.

Tools and capabilities

• Plans Codex usage against the current weekly quota.
• Reads local quota and banked-reset values through a signed-in Codex CLI.
• Displays a two-week daily timeline with usage, remaining quota, refills, outages, and run-out points.
• Forecasts possible automatic resets within the next 48 hours.
• Supports five planning strategies and lets the timeline count zero, one, or two predicted resets.
• Applies consistent reset and banked-reset rules across the website, plugin page, and MCP tools.

Limitations and notes

The extra-reset forecast is an uncalibrated estimate based on public evidence, not a promise of when a reset will occur. The MCP workflow requires a signed-in Codex CLI on the same machine to read quota data. The project is an unofficial OpenAI Codex utility and does not perform quota changes, reset redemption, or credit spending. An optional X API token can provide direct access to a public timeline during site data collection; build-time keys are not sent to the browser.