Codex Quota Guard MCP 0.6.0

Quota Guard is a local MCP server that reads the current Codex ChatGPT quota through the official codex app-server interface, admits bounded work segments, and stores redacted checkpoints for resume. It never creates a login, accepts an API key, or reads Codex authentication files.

Security and lifecycle guarantees

• Only the current stable account.type === "chatgpt" session is supported. API-key, Bedrock, signed-out, external-token and unstable identities return CHATGPT_LOGIN_REQUIRED; no quota percentage is read or cached for them.

• One authenticated 127.0.0.1 core owns SQLite and quota refresh for a Codex profile. Every Codex task gets only a small stdio connector.

• Connectors renew an in-memory lease every 20 seconds. A clean disconnect is observed immediately; a crashed connector expires after 60 seconds.

• The core exits about five seconds after the last connector disappears and no request or scheduler dispatch is active. Pending defers do not keep it alive.

• The five-minute early-recovery poll runs only when a connector is alive, a defer is waiting, and the current Codex task supplied a valid scheduler capability.

• There is no Scheduled Task, service, daemon, launchd, systemd, wscript, elevation request, Codex PID scan, browser login, or OAuth fallback.

Related MCP server: codex-mcp-swarm

Requirements

• Node.js 22.13 or newer (Node 22 and 24 are CI-tested).

• A current Codex installation signed in with ChatGPT.

• PowerShell 7 (pwsh) on Windows, used only to apply a private user DACL; elevation is not requested.

Windows 10/11 on physical hardware or in a VM is treated identically. Windows x64 uses x64 Node/Codex; Windows ARM64 uses native ARM64 binaries or Windows' own compatibility layer. The Guard never detects Parallels, VMware, UTM, or the macOS host.

Install

This package is private and is installed from its GitHub checkout, not npm:

npm ci
npm run check
node scripts/install.mjs

The installer preserves unrelated config.toml content, creates a private local bearer and runtime settings, and registers the absolute Node executable with dist/connector.js. It does not start a persistent process. Restart or reconnect Codex after installation so it opens the new connector.

On a Windows machine that also uses WSL, run the installer with Windows Node from pwsh; both Windows and WSL tasks then use the Windows-hosted core and the same Windows profile. Native Linux and native macOS each use their own local Node, Codex login and state. Do not share Windows login/state with a macOS host.

Uninstall

Remove only the MCP registration and stop an authenticated running v0.6 core:

node scripts/uninstall.mjs

Also delete the validated v0.6 private state directory:

node scripts/uninstall.mjs --purge

Both modes preserve unrelated Codex configuration and write a configuration backup. The purge refuses paths outside the recognized Guard-owned directory.

MCP use

The public contract has eight tools:

• quota_status: call near the beginning of long work.

• job_preflight: call once, with a stable jobId, before each substantial token-consuming segment.

• quota_profile, checkpoint_create, checkpoint_get, defer_until_reset, defer_automation_attach, and resume_prepare support policy and controlled resume.

Do not call the Guard before every shell command, small file read, or trivial edit. No tool accepts credentials, a force-refresh flag, or a model name.

quota_status.monitor reports runtimeMode="shared-http", requiresLiveClientConnection=true, and lifecycleMode="codex-bound".

Verification

npm run check
npm run acceptance:install
npm run acceptance:shared
npm audit
npm pack --dry-run

CI runs the full check, disposable installer acceptance, six-concurrent-connector singleton acceptance, and package dry run on Node 22/24 for Windows x64/ARM64, Ubuntu x64/ARM64, and macOS Intel/Apple Silicon.

Release acceptance is recorded by guest OS. A Windows VM is simply a Windows acceptance result; there are no hypervisor-specific branches.

See architecture, security, monitor behavior, Windows and WSL, MCP API, and troubleshooting.