# 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

```text
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?**

## 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

```bash
npm install
npm run check
```

## Run a safe local demo

```bash
WORK_WINDOW_QUOTA_PERCENT=58 npm run demo
```

Optional reset time:

```bash
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:

```bash
npm run build
```

Then point your MCP client to:

```text
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

```text
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

```text
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`](docs/SECURITY.md).

## Roadmap

See [`docs/ROADMAP.md`](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`](NOTICE.md).

## Licence

MIT. See [`LICENSE`](LICENSE).