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.
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.
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: Codex Claude Code MCP
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. |
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.
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.
Node.js 22.13+
npm
npm install
npm run checkWORK_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 demoBuild 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.
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.
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 actionNo 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.
See docs/ROADMAP.md.
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.
MIT. See LICENSE.
Save a bounded, redacted handoff state for deterministic resume.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | ||
| pending | Yes | ||
| lastTest | No | ||
| completed | Yes | ||
| gitStatus | No | ||
| objective | Yes | ||
| riskNotes | No | ||
| workspaceRoot | Yes | ||
| nextSafeAction | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose that the saved state is 'bounded' and 'redacted', signaling that not all workspace data is persisted. However, it does not mention overwrite behavior, storage semantics, failure behavior, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loading the action and the key characteristics of the state being saved. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nine parameters, six required fields, no annotations, and no output schema, one sentence is not enough. Missing are return values, overwrite semantics, how the state relates to resume_contract, and guidance on what 'bounded' and 'redacted' impose on callers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description names none of the nine parameters. 'Handoff state' is generic and does not clarify the roles of required fields such as jobId, completed, pending, and nextSafeAction. The description fails to compensate for the schema's lack of parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Save') and a clearly defined resource ('bounded, redacted handoff state'). The phrase 'for deterministic resume' distinguishes it from sibling tools like resume_contract, which presumably consumes such a state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose phrase 'for deterministic resume' implies this tool is used when persisting a checkpoint before a resume or handoff. However, there are no explicit when-to-use or when-not-to-use instructions, nor alternatives compared against window_plan or resume_contract.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prepare a resume contract from the last checkpoint and current capacity.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | ||
| workspaceRoot | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It says only that a contract is 'prepared' and gives no information about side effects, persistence, required permissions, or whether the operation is read-only or mutating. This is a significant gap for a tool whose name suggests it may alter a workflow state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words, so it is concise. However, it is so sparse that it omits information essential for correct invocation, making it under-specified rather than efficiently complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 0% schema coverage, the description is incomplete. It gives a hint about the source data ('last checkpoint', 'current capacity') but says nothing about return values, side effects, or prerequisites, leaving an agent unable to confidently call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not map 'workspaceRoot' or 'jobId' to the mentioned 'last checkpoint' or 'current capacity'. The description adds only a vague contextual hint and fails to explain what each parameter actually means or how to populate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Prepare' with a resource ('resume contract') and names two inputs ('last checkpoint', 'current capacity'), so it is not a tautology. However, 'resume contract' is never defined, and no distinction is drawn between this tool and its siblings, leaving its exact purpose somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case ('from the last checkpoint and current capacity') but gives no explicit when-to-use guidance and no mention of alternatives like window_plan or checkpoint_save. An agent must infer when this tool is appropriate rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn current quota into a bounded work segment with reserve and checkpoint rules.
| Name | Required | Description | Default |
|---|---|---|---|
| jobClass | No | medium | |
| workspaceRoot | Yes | ||
| requestedMinutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Turn current quota into a bounded work segment' hints at a transformation or planning operation, but it does not disclose whether this mutates state, creates files, requires permissions, or is reversible. The mention of 'reserve and checkpoint rules' adds context but not enough detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It is front-loaded with the core action and outcome. However, its brevity comes at the cost of key details, so it is efficient but not fully substantive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, no output schema, and no annotations, so the description alone must provide complete context. It does not explain what 'bounded work segment' means, how reserve rules work, what checkpoint rules entail, or how jobClass and requestedMinutes affect the plan. This is insufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the parameters (workspaceRoot, jobClass, requestedMinutes). The terms 'quota' and 'reserve' indirectly relate to requestedMinutes and reserve rules, but no parameter meanings or usage details are provided. The description fails to compensate for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Turn') and resource ('current quota') to convey that this tool creates a bounded work segment with reserve and checkpoint rules. It is distinct enough from siblings like checkpoint_save and resume_contract, though it does not explicitly name them for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied through phrases like 'current quota' and 'bounded work segment', suggesting it is used when planning a work window. However, there is no explicit guidance about when to prefer this tool over checkpoint_save or resume_contract, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0checkpoint_saveresume_contractwindow_planScored 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.
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.