Codex Work Window MCP

Turn quota limits into governed work windows.

Codex Work Window MCP treats the Codex 5-hour allowance as a capacity-planning constraint rather than an interruption. The server plans bounded work segments, keeps a reserve, requires checkpoints at the right time, and creates a precise resume contract for long-running jobs.

This project does not bypass, increase, spoof or manipulate Codex quota. It only plans work around capacity reported by an approved quota provider.

Product idea

Quota capacity
     │
     ▼
Work Window
     │
     ├── Segment A ── checkpoint
     ├── Segment B ── checkpoint
     └── PARK
           │
         reset
           │
           ▼
      Resume Contract
           │
           ▼
       Segment C

The useful abstraction is not “how much quota is left?” It is:

What is the largest safe piece of work that should start now, what reserve must remain, and exactly where should the job resume if capacity runs out?

Related MCP server: Codex Claude Code MCP

v0.1 tools

Why this is different

Codex Work Window is designed around five operating concepts:

1. Reserve — never plan to consume the final percentage of capacity.

2. Segments — large jobs are admitted in bounded slices, not as one mega-run.

3. Job class — long/high-risk jobs receive shorter admitted segments.

4. Checkpoint quality — every checkpoint must name the next safe action.

5. Provider isolation — Codex quota-reading logic is isolated from the planner, reducing breakage if the host interface changes.

Status

v0.1.0 is a foundation release, not a production quota reader.

The policy engine, local state and MCP contract are implemented. The included quota provider is intentionally manual/environment-based so the orchestration can be tested without touching Codex credentials or depending on unstable host internals.

The next integration milestone is a read-only codex app-server provider, implemented behind the QuotaProvider interface and validated on macOS first.

Requirements

• Node.js 22.13+

• npm

Install for development

npm install
npm run check

Run a safe local demo

WORK_WINDOW_QUOTA_PERCENT=58 npm run demo

Optional reset time:

WORK_WINDOW_QUOTA_PERCENT=18 \
WORK_WINDOW_RESET_AT="2026-09-06T13:00:00+08:00" \
npm run demo

Run as an MCP server

Build first:

npm run build

Then point your MCP client to:

node /absolute/path/to/codex-work-window-mcp/dist/src/index.js

For v0.1 the process must receive WORK_WINDOW_QUOTA_PERCENT in its environment. Do not present manual-provider values as real Codex readings.

Default policy

hard stop      8%
reserve       12%
caution       22%
cold segment  15 min
max segment   45 min
plan horizon  90 min
snapshot TTL  90 sec

These are conservative development defaults, not claims about OpenAI's own quota policy. They are user-side planning controls and can be made configurable later.

Example: long ONZKO-style implementation job

Objective: refactor a WordPress integration module
Requested: 60 min
Quota: 58%
Job class: long

Work Window returns:
- OPEN
- admitted segment: bounded by forecast/policy
- reserve: 12%
- checkpoint required: yes
- validUntil: short-lived admission deadline

Before the segment ends:
- commit or leave a clean reversible state
- run the relevant tests
- call checkpoint_save
- state the exact next safe action

Safety principles

• No credential collection.

• No authentication-file reading in v0.1.

• No daemon or background service.

• No automatic purchases or quota-reset purchases.

• No destructive resume action without separate authorisation.

• Local state is stored per workspace under .work-window/ with restrictive file modes where supported.

See docs/SECURITY.md.

Roadmap

See docs/ROADMAP.md.

Attribution

This project is inspired by the problem and workflow explored by valentine-89/codex-quota-guard-mcp, an MIT-licensed project by Val89. See NOTICE.md.

Licence

MIT. See LICENSE.