Usage Planner — Codex quota & reset planner
Usage Planner (formerly Codex4ever) is a planner for your OpenAI Codex weekly quota. It shows when your quota runs out at your current pace, whether a predicted extra reset is likely to arrive first, and when a banked reset is worth redeeming.
Unofficial; not affiliated with OpenAI. MIT licensed.
Pick a strategy
Ask once in Codex and the planner opens beside the chat. Pick a strategy and the plan changes: daily usage, refills and run-out points.
What it does
- Timeline of your next two weeks — daily usage, remaining quota, run-out points, outages, normal refreshes and banked-reset uses, one column per day.
- Extra-reset forecast — the chance of an automatic reset in the next 48 hours, the likely window, and a second reset conditioned on the first, built from public reset history and Tibo's public posts.
- Five strategies — Keep pace (your current pace: see when quota runs out), Keep available, Use it all (empty quota just before the next refill), Weekdays only, Weekend focus.
- Codex plugin — reads your local, signed-in quota and banked resets, plans in the conversation, and opens the same visual planner.
How it plans
- A predicted reset is counted only when it is at least 60% likely before the refresh in effect, and it is placed at a conservative time (where it has most probably already happened), not at its single most likely hour. You can switch the count to 0, 1 or 2 on the timeline.
- Every refill restarts the seven-day window — a banked reset, an extra reset or the normal refresh.
- Banked resets: extras cover outages, earliest expiry first; the last one is kept for a real outage (24 h or more), and a bank about to expire can be used rather than wasted.
- One rule everywhere: the website, the plugin page and the plugin's MCP tools always give the same plan for the same inputs.
The forecast is an uncalibrated model estimate, not a promise. Usage Planner never redeems a reset or spends credits for you.
Use it
Codex plugin (Node.js 20+ and a signed-in Codex app or CLI):
codex plugin marketplace add ItsOdeLeo/usage-planner
codex plugin add usage-planner@usage-planner
Start a new Codex chat and ask: "Open quota planning." Reading your quota is local and read-only; no separate API key is needed.
Other MCP clients (Claude Code, Claude Desktop, Cursor and others): the same server is on npm as usage-planner and in the MCP Registry as io.github.ItsOdeLeo/usage-planner. Reading your quota still needs a signed-in Codex CLI on the same machine.
{ "mcpServers": { "usage-planner": { "command": "npx", "args": ["-y", "usage-planner"] } } }
Website: usageplanner.com, no install. Enter your quota by hand; everything is calculated in your browser and your inputs are not sent anywhere.
Run locally:
npm install
npm run web # http://127.0.0.1:4173/
npm test
Data sources
Public reset data comes from Codex Resets, including the bundled offline archive (npm run archive:refresh). Thanks to its maintainer. With an optional X API token, Tibo's full timeline is read directly from X.
Development
| Command | What it does |
|---|
npm run web | Local site with live reset evidence (cached 30 minutes) |
npm run site:build | Static site in dist/, evidence collected at build time |
npm run plugin:build | Self-contained Codex plugin in plugins/usage-planner/ |
npm run mcp | MCP server from source |
npm run backtest:public | Day-by-day replay of the forecast against public history |
.github/workflows/deploy-site.yml rebuilds the static site every 30 minutes and deploys it to Cloudflare Pages. Optional settings (LLM classification of posts, X timeline access) are listed in .env.example; keys are only read at build time and never reach the browser.
Design and algorithm details: docs/technical-notes.zh.md (Chinese).
中文简介
Usage Planner（原名 Codex4ever）是 OpenAI Codex 每周额度的本地规划器：按你当前的速度显示额度什么时候用完、额外 reset 是否可能先到，以及备用 reset 什么时候值得用。预测的 reset 只在“正常刷新前发生的概率 ≥ 60%”时计入，并放在保守时刻；任何一次补满都会重新开始 7 天周期；备用默认至少保留一个。网页、插件页面和插件的 MCP 工具始终使用同一套规则。非官方工具，与 OpenAI 无隶属关系。详细设计见 技术说明。
Author
Built by 欧的Leo — @ItsOdeLeo on X · 小红书 ItsOdeLeo. Feedback and ideas are welcome there or in GitHub issues.
