# usage-planner

usage-planner is a Claude Code MCP server that plans OpenAI Codex weekly quota and forecasts quota resets. It builds a two-week timeline across five usage strategies.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: ItsOdeLeo
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ItsOdeLeo/usage-planner
- Updated: 2026-10-29
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/usage-planner

## What it does

usage-planner tracks remaining OpenAI Codex quotas directly from a signed-in local Codex session. The server generates a day-by-day timeline spanning two weeks, marking daily usage, scheduled resets, and remaining capacity.

It projects unscheduled reset probability for the next 48 hours using historical reset data, factoring them in only when the likelihood reaches at least 60%. Five planning strategies help allocate tokens across weekdays or hold reserves for service outages.

Running the MCP server requires Node.js 20+ and a logged-in Codex CLI on the host machine. The server reads balance locally and never triggers resets or spends quota on its own.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add usage-planner -- npx -y usage-planner
```

### Codex

**Platform CLI**
```bash
codex mcp add usage-planner -- npx -y usage-planner
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "usage-planner": {
            "command": "npx",
            "args": [
                "-y",
                "usage-planner"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "usage-planner": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "usage-planner"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add usage-planner npx -y usage-planner
```

## When to use it
- forecast OpenAI Codex quota run-out dates based on current pace
- estimate the likelihood of an extra quota reset within 48 hours
- schedule banked reset redemptions across a two-week window
- distribute quota across weekdays or weekend-focused schedules

## Example prompts
- Show the two-week quota forecast for Codex
- Check when my Codex weekly limit runs out at the current pace
- Plan my quota using the weekdays-only strategy

## Similar
- [event-planner](https://affpapa.org/en/nevibecode/skills/event-planner.md) — skill · 253 installs
- [sales-quota-setting](https://affpapa.org/en/nevibecode/skills/sales-quota-setting.md) — skill · 33600 installs
- [recipe-find-large-files](https://affpapa.org/en/nevibecode/skills/recipe-find-large-files.md) — skill · 31300 installs
- [codex-quota-title](https://affpapa.org/en/nevibecode/plugins/codex-quota-title.md) — plugin · ★ 1596 repo stars
- [foundation-meeting-synthesize](https://affpapa.org/en/nevibecode/skills/foundation-meeting-synthesize.md) — skill · 778 installs
- [claude-usage-analyst](https://affpapa.org/en/nevibecode/skills/claude-usage-analyst.md) — skill · 471 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
