Codex Work Window MCP
Integrates with OpenAI's Codex quota system to read remaining capacity and plan bounded work segments, maintain a reserve, save checkpoints, and create resume contracts for long-running jobs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex Work Window MCP Plan a 60-minute refactor in safe segments with checkpoints and a resume contract."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 CThe 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: agent-work-mcp
MCP tools
Tool | Purpose |
| Convert current capacity into a bounded segment admission. |
| Store a concise handoff: completed, pending, risks, next safe action. |
| Reconstruct the first safe action and stop conditions before resuming. |
Why this is different
Codex Work Window is designed around five operating concepts:
Reserve — never plan to consume the final percentage of capacity.
Segments — large jobs are admitted in bounded slices, not as one mega-run.
Job class — long/high-risk jobs receive shorter admitted segments.
Checkpoint quality — every checkpoint must name the next safe action.
Provider isolation — Codex quota-reading logic is isolated from the planner, reducing breakage if the host interface changes.
Status
v0.2.0 includes the foundation policy engine plus a read-only live Codex app-server quota provider.
The policy engine, local state, MCP contract and live quota provider are implemented. The manual provider remains available for CI, tests and controlled simulation without requiring Codex.
The read-only codex app-server provider is implemented behind the QuotaProvider interface and has been validated on macOS.
Requirements
Node.js 22.13+
npm
Install for development
npm install
npm run checkRun a safe local demo
WORK_WINDOW_QUOTA_PERCENT=58 npm run demoOptional reset time:
WORK_WINDOW_QUOTA_PERCENT=18 \
WORK_WINDOW_RESET_AT="2026-09-06T13:00:00+08:00" \
npm run demoRun as an MCP server
Build first:
npm run buildThen point your MCP client to:
node /absolute/path/to/codex-work-window-mcp/dist/index.jsManual mode uses WORK_WINDOW_QUOTA_PERCENT; live mode uses the read-only Codex app-server provider.
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 secThese 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 actionSafety principles
No credential collection.
No direct Codex authentication-file reading.
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.
Available Tools
3 toolscheckpoint_saveB
Save a bounded, redacted handoff state for deterministic resume.
Inputs: jobId (required), pending (required), completed (required), objective (required), +5 more.
resume_contractC
Prepare a resume contract from the last checkpoint and current capacity.
Inputs: jobId (required), workspaceRoot (required).
window_planC
Turn current quota into a bounded work segment with reserve and checkpoint rules.
Inputs: workspaceRoot (required), jobClass, requestedMinutes.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct phase of the work-window lifecycle: planning rules, saving state, and preparing a resume contract. There is no functional overlap or ambiguity about which tool to call.
All names use a two-word underscore convention and clearly describe their action, but the pattern is mixed: window_plan and checkpoint_save are noun-verb while resume_contract is verb-noun. This is a minor deviation from a strictly consistent verb_noun scheme.
Three tools is well-scoped for a focused workflow around planning, saving, and resuming work windows. Each tool earns a clear place; nothing feels redundant or missing at the surface level.
The set covers the core lifecycle of a work window: planning, checkpointing, and resuming. Minor gaps exist such as an explicit finalize/cancel action, but agents can work around those by planning a new window or not resuming.
Maintenance
Related MCP Connectors
Execution control plane for agents: capabilities, durable jobs, budgets, receipts, and BYOK.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Related MCP Servers
- AlicenseAqualityBmaintenanceCoordinates concurrent Codex tasks around a shared ChatGPT quota snapshot, deferring expensive work near exhaustion and storing resumable checkpoints.57MIT
- AlicenseAqualityCmaintenanceEnables coding agents to run persistent, budgeted work sessions with dependency graphs, human decision queues, required validation, and clean handoffs for autonomous or human-in-the-loop execution.16MIT
- AlicenseNot gradedqualityBmaintenanceEnables host agents to launch and supervise durable, long-horizon AI jobs—starting, running, resuming, checking budgets, and inspecting assembled context—so tasks can survive restarts and outlive the conversation with verified completion.MIT
- AlicenseNot gradedqualityCmaintenancePersistently connects Codex to Reasonix Studio so Codex can plan and verify while Reasonix executes, delegating tasks across shared multi-client sessions. Keeps tasks, sessions, approvals, results, and artifact fingerprints durable, with idempotent submission, workspace queuing, session reuse and recovery, manual adjudication of unknown outcomes, explicit retries, cancellation, and bounded shutdown.GPL 3.0