Codex Context Status

Visibility into your Codex session: recorded context usage, a refreshable inspector, and prompts to help carry work into a fresh chat.

Explore the capabilities and interactive examples.

Current plugin version: 0.1.2. Install directly from GitHub using the commands below. A public OpenAI directory listing is not required for this installation route. This is an independent community project; directory submission remains pending, with local MCP eligibility awaiting OpenAI guidance. See the recorded submission status.

When to use it

Open the inspector when you want visibility into a long-running local Codex chat. It updates automatically while visible; you do not need to invoke it at the end of every session. When continuing the same task in a fresh chat, use its optional handoff prompts to prepare, review, and transfer a summary. If the task is finished or you are returning to the same chat, no handoff is required.

The plugin does not automatically open in every chat, detect when you leave, or transfer history. It estimates recorded usage; it does not diagnose declining model quality or guarantee that starting a fresh chat improves results.

What it shows

• Estimated context usage and remaining capacity from the latest recorded request.
• Cached and noncached input, output, and expandable token accounting.
• Current recorded model, reasoning effort, compaction activity, and measurement timestamps.
• Latest-usage model attribution, a waiting state after model changes, and the ten most recent recorded switches.
• Expandable telemetry checks for verified session identity, model metadata, usage, context limit, and cache counters, including when usage is unavailable.
• Session-recorded producer version and evidence for known usage formats; unreadable newer measurements withhold capacity advice until recovery.
• A teal Refresh button and Auto-refresh enabled by default, every 15 seconds while visible.
• Task-aware session advice with explicit 80% and 90% advisory checkpoints.
• Expandable handoff checklist with preparation and resume prompts, plus manual-copy fallback.

Refresh updates the existing inspector without sending a chat message or invoking a model. Auto-refresh pauses when hidden, can be switched off, and stops after three consecutive failures. Usage numbers and recommendations stay inside the view so chat text does not become stale.

Requirements

• A Codex desktop build with local MCP server and MCP Apps support.
• Local session logs with the supported telemetry fields. Remote or ephemeral chats may be unavailable.
• Node.js 20+ and Python 3.10+ with IANA timezone data.

This project was verified on macOS with Codex desktop 26.1007.21159. Its local log format is an implementation detail and can change between Codex releases. Browser and reader tests also run on Linux; this is not a claim of full desktop compatibility across platforms.

See the compatibility matrix for live release evidence, synthetic format coverage, and how to verify another release. Currently only one desktop build has documented live verification.

Install

Codex plugin (GitHub distribution)

The plugin bundles the skill, local MCP server, and inspector. With Node 20+, Python 3.10+, and a Codex CLI supporting plugin add (tested on 0.160.0):

Plugin telemetry currently requires the default ~/.codex data directory. For a custom CODEX_HOME, use the standalone installation below; the tested Codex host does not forward that setting to plugin MCP servers.

codex plugin marketplace add ArielSmoliar/codex-context-status --ref main
codex plugin add context-status@codex-context-status

Restart Codex if needed, select the Context Status skill, or ask:

Show the context-status inspector for this chat.

The installed skill may appear as context-status:context-status. Auto-refresh starts on and checks every 15 seconds while the inspector is visible. No npm setup or manual MCP registration is needed; JavaScript dependencies are bundled, while Node.js and Python must already be installed and available to Codex.

The commands above track main. For the supervised 0.1.2 pilot, use the participant instructions instead: they pin the reviewed product commit and explain how to verify it.

To update an existing GitHub plugin installation:

codex plugin marketplace upgrade codex-context-status
codex plugin add context-status@codex-context-status

Restart Codex and reopen the inspector after updating. Refresh reads telemetry; it does not load new UI code. A marketplace pinned to a commit stays pinned.

See plugin installation, upgrades, rollback, and removal. Existing standalone users should follow its migration steps before enabling the plugin to avoid duplicate skills and server registrations. The plugin does not modify those separate installations automatically.

Standalone skill (alternative)

Clone a trusted revision of this repository and run these commands from its root:

python3 scripts/install.py
python3 scripts/install.py --apply

The first command previews changes without writing. Apply creates a managed copy in ${CODEX_HOME:-$HOME/.codex}/skills/context-status. Then run the dependency and MCP setup commands printed by the helper. Inspect any existing MCP registration before replacing it; the helper leaves Codex configuration untouched. File installation alone does not verify runtime readiness or desktop support.

For upgrades, run the same commands from the desired revision. Local edits stop an upgrade; extra files are preserved, and the previous installation is kept as a backup. Older copies require an explicit --adopt comparison; symlink installations are left untouched. See installation and recovery for migration, conflicts, backups, and component-specific reload steps.

If $context-status or the new MCP tool is unavailable, start a new turn or restart Codex. Then invoke:

$context-status

The skill resolves the current chat ID and opens the inspector. New inspectors start with Auto-refresh on. Existing open views retain older UI code until reopened; Refresh updates telemetry only. Keep the installed copy in place while the skill and MCP server reference it. A developer using a symlink must also retain its source checkout.

To unregister the server, run codex mcp remove context-status. Removing the skill link is a separate action.

How to interpret it

Capacity is an estimate, not exact live occupancy. It uses the last recorded request footprint and runtime-reported context limit. It excludes unreported work. Cumulative totals measure consumption across requests, not unique context size. Cached input still occupies context.

The 80% and 90% checkpoints are advisory, not Codex's compaction trigger. Choose your Next step to distinguish continuing the task, planning a large step, or starting unrelated work. The inspector cannot predict the size of that step. Missing telemetry and compaction counts alone do not mean you should restart.

Expand Handoff checklist & prompts for a checklist and prompt to paste into the current chat. The prompt asks for established goals, decisions, files, verification, blockers, and the next action. Copying does not generate a summary, send a message, or open a chat. Review the resulting handoff before pasting it into a new session. If clipboard access is unavailable, the text is selected for manual copying.

Choose 1. Current chat to prepare the handoff or 2. New chat for the resume prompt. Add your reviewed handoff to the resume prompt before sending it. The resume prompt asks the next chat to reconcile the summary with current workspace state before continuing. In 0.1.2, it also asks the final response to distinguish previously completed work, actions performed now, remaining work, and verification limits—including merged source versus installed or deployed state when relevant. Your intent, prompt selection, and expanded details persist through refreshes within the current view. See handoff and resume guidance.

Model changes are detected when the new model appears in recorded turn metadata, typically after the next message. The previous context limit is cleared, and capacity is withheld until fresh usage and a new limit exist. Older cache measurements retain their model label. The inspector records a switch count and the latest ten transitions; these reflect the available log, not model-picker clicks. Cache-miss causes remain unavailable.

Telemetry checks distinguish observed data, fields not observed yet, and checks that could not run because the log was inaccessible or unverified. Missing evidence does not establish that a Codex version is unsupported. Usage records with explicit turn IDs are accepted for the current turn only; legacy records without turn IDs rely on log order for model attribution.

Privacy and scope

The MCP server runs locally over stdio. It reads the exact selected session, verifies its identity, and returns allowlisted telemetry. The UI has no external network dependencies. The backend does not modify session logs or return conversation content. Display data omits account quotas and source paths.

No separate API key or hosted telemetry service is needed. GitHub is contacted to download or update the package. The initial tool result is available to Codex like other tool results; local processing does not change Codex's own data handling. See the privacy notice.

This is a personal local tool, not a multi-user service. Do not expose it through a public tunnel or network endpoint. It relies on the local account's filesystem access, not remote-user authentication.

Try the validation kit

The validation guide includes pinned-candidate install instructions for plugin candidate 0.1.2, a synthetic walkthrough, six handoff scenarios, and a three-person pilot protocol. Record the product pin separately from the kit-source revision; generating the kit does not install the plugin. Generate an offline kit into a new directory:

python3 scripts/prepare_validation.py --output /tmp/context-status-trial

Open the generated demo.html and protocol.md. Generation makes no model calls and reads no chats. It does not establish handoff quality. The initial agent-reviewed CLI smoke run passed six synthetic cases. A later 0.1.1 dry run passed five of six and found a merged-versus-installed reporting gap. One focused rerun with the revised 0.1.2 resume prompt passed that scenario's four criteria; this was not a new six-case pass or a human trial. Real-task effectiveness and outside-user adoption remain unverified. Use the results template to keep baseline, assisted, and synthetic observations separate.

The three-person pilot packet has participant setup instructions, a proposed trial order, an invitation draft, and private scorecard templates. We are preparing a three-person pilot for daily Codex desktop users: roughly 30–45 minutes, possibly split across task boundaries, plus a seven-day reuse check-in. Its P01–P03 slots are placeholders, not enrolled users. Compare your usual transition method with the assisted workflow; setup problems and non-use are useful feedback too. To express interest, open a GitHub issue with a brief description of how you use Codex, or use the private contact in the privacy notice. Do not post chat logs or personal telemetry.

The new-user landing page source provides a capability tour, interactive synthetic examples, and pinned installation commands. The SEO plan covers search intent, technical setup, Search Console verification, and the first month of measurement.

Development

npm ci --ignore-scripts
npm ci --prefix mcp --ignore-scripts
npx playwright install chromium
npm run build
npm test
npm run test:plugin # requires Codex CLI 0.160.0; uses an isolated synthetic home

Use CHROME_EXECUTABLE_PATH to test with an existing Chromium/Chrome binary instead of Playwright's downloaded browser. Run commands from the repository root.

Tests use temporary, synthetic session logs. They never need your Codex account or personal chats. Coverage includes identity validation, partial log records, model changes, compaction, redaction, real stdio tool calls, same-view refresh, default-on polling, pause/resume, failure recovery, and narrow/light/dark presentation.

Run npm run benchmark to measure reader and one-shot CLI latency using temporary synthetic logs. See refresh performance for paired comparisons, measured results, and scope. The reader still scans a fresh size-bounded snapshot on each refresh.

The generated mcp/inspector.html and plugins/context-status/ are committed for direct installation. After editing runtime files, rebuild with npm run build and commit generated changes. CI checks source parity. Edit manifests under packaging/; do not edit generated plugin files. The plugin build uses an explicit file allowlist and preserves bundled dependencies' license notices.

test:plugin runs actual Codex install, upgrade, rollback, and removal commands against a temporary Git marketplace. It verifies host discovery, offline stdio reads, in-place refresh data, cache cleanup, and preservation of synthetic logs and unrelated configuration. It makes no model calls or changes to your installed skill. This is CLI/app-server integration coverage, not a claim that every desktop release renders MCP Apps correctly.

See telemetry details, MCP implementation, and the development roadmap.