Skip to main content
Glama

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: agent-work-mcp

MCP tools

Tool

Purpose

window_plan

Convert current capacity into a bounded segment admission.

checkpoint_save

Store a concise handoff: completed, pending, risks, next safe action.

resume_contract

Reconstruct the first safe action and stop conditions before resuming.

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.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 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/index.js

Manual 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 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 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 tools
checkpoint_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

    B3.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      16
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistently 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