Codex Context Meter

Read the latest recorded context-window usage of a local Codex thread through a CLI or a read-only MCP tool.

中文说明

The meter reads Codex rollout JSONL files. It reports the last request's token counters, the recorded effective window, a remaining-window estimate, and the age of the log event. It never selects a conversation by recency or working directory.

Install

Python 3.10 or newer is required. The CLI uses only the standard library. MCP support uses the official Python SDK, pinned to its v1 compatibility line.

git clone https://github.com/ShallowDream724/codex-context-meter.git
cd codex-context-meter
python -m venv .venv
# Activate .venv with the command appropriate for your shell.
python -m pip install ".[mcp]"

For a pinned installation directly from GitHub:

python -m pip install "codex-context-meter[mcp] @ git+https://github.com/ShallowDream724/codex-context-meter.git@v0.2.1"

Related MCP server: agent-activity

CLI

codex-context-meter --thread-id YOUR-CODEX-THREAD-UUID --pretty

When a Codex native executor supplies CODEX_THREAD_ID, the CLI can omit --thread-id. Other terminals and MCP-based shell tools may not inherit that variable. In those environments, pass the actual thread UUID explicitly.

python -m codex_context_meter --pretty

CODEX_HOME defaults to ~/.codex. Override it with --codex-home. For nonstandard storage, --session-file selects an exact uncompressed JSONL file; its session_meta ID must match the requested UUID.

Optional flags:

Successful reads exit with code 0, including explicitly stale or post-compaction snapshots. A read or validation error returns JSON with status: "unavailable" and exits with code 2. Consumers must inspect status and freshness fields before using an estimate.

Codex MCP Configuration

Add this section to your Codex config.toml, using the absolute path to the Python executable in the environment where you installed the package:

[mcp_servers.context_meter]
command = "/absolute/path/to/.venv/bin/python"
args = ["-m", "codex_context_meter.server"]
startup_timeout_sec = 10
tool_timeout_sec = 10
enabled_tools = ["get_context_usage"]

On Windows, use a path such as C:/path/to/.venv/Scripts/python.exe. A server-level --codex-home argument can select another fixed data directory. Reload the MCP configuration or start a new Codex task after adding the server.

After upgrading the package, restart the context-meter MCP server or its host so an already-running Python process loads the updated code.

The server exposes one read-only tool:

get_context_usage(
    thread_id="00000000-0000-0000-0000-000000000001",
    stale_after_seconds=120,
    auto_compact_token_limit=null
)

The UUID above is synthetic. Supply the requested task's exact UUID. For the current task in Codex, use nodeRepl.requestMeta.threadId when exposed by node_repl; otherwise read CODEX_THREAD_ID through the native exec_command tool. MCP-based shells such as FastCtx run may expose their shared server's environment instead of the caller's. The meter requires an explicit UUID and never infers identity from a working directory or the latest modified file.

Interpret the Result

Since 0.2.0, MCP returns one compact JSON text block. Example with synthetic counters:

{"status":"ok","used_tokens":201000,"window_tokens":353400,"remaining_tokens":152400,"remaining_percent":43.1,"event_age_seconds":4}

Cached input and reasoning counters are not added again. Even an ok result excludes unreported work; a fresh log event can repeat older counters. Event age does not establish measurement freshness.

• stale: the log event exceeds stale_after_seconds; counts are historical.

• event_time_unknown: the timestamp is absent, invalid, or in the future. More restrictive compaction/window statuses take precedence; the age is still null.

• awaiting_usage_after_compaction: used_tokens, remaining_tokens, and remaining_percent are null until changed counters appear. A repeated count with a newer timestamp does not restore them. Without a pre-compaction baseline in the bounded tail, another distinct usage record is required.

• window_unknown: window_tokens, remaining_tokens, and remaining_percent are null.

• unavailable: the response contains status and an error object with a safe code and actionable message.

Only when the caller supplies auto_compact_token_limit, the response adds compaction_remaining_tokens. It is null while awaiting new usage after compaction. The supplied threshold must count total context; model capacity and thresholds that count only growth after a compacted prefix cannot substitute for it. remaining_percent always uses the recorded window, not the compaction threshold.

This replaces the MCP 0.1.x response format. Tool arguments are unchanged. The CLI and Python library retain their detailed version-1 schema, including timestamps, component counters, and diagnostics. For MCP consumers, last_request.total_tokens becomes used_tokens, and remaining_estimate.tokens becomes remaining_tokens. The MCP result omits repeated explanations and identity fields, and is not duplicated in structuredContent.

Check at meaningful task boundaries, before large reads or delegations, and when planning room for results and verification. Avoid polling after every small tool call: the check itself adds conversation tokens and snapshots may not have changed.

Storage and Privacy

The resolver searches only filenames matching the supplied UUID beneath CODEX_HOME/sessions and CODEX_HOME/archived_sessions. It supports original rollout-...-THREAD_UUID.jsonl files and resumed rollout-...-THREAD_UUID_SEGMENT_UUID.jsonl files. Every segment's session_meta ID must match the requested thread. The history_base.thread_id references must form one connected chain; the final segment is selected by those references, never by modification time. Duplicate segment IDs, branches, cycles, missing predecessors, and invalid history references produce explicit errors. Discovery is limited to 128 segments. Files resolving outside CODEX_HOME are rejected by the normal resolver.

The reader inspects each segment's first metadata line and shares one tail budget across the chain, starting from the final segment. Inherited history ends at the recorded history_base.end_byte_offset; later records in a predecessor are excluded. This preserves compaction detection across segment boundaries. An empty continuation can inherit the prior snapshot, including its original event time. --session-file still reads only the exact selected file. The reader ignores malformed JSON and unfinished trailing records. It performs no network requests and does not modify Codex files. MCP returns budget counters, event age, and status or diagnostic codes; the CLI also includes timestamps and the supplied thread UUID. Neither returns prompts, tool outputs, credentials, or local file paths.

This is a local convenience tool, not an authorization boundary between mutually untrusted clients. A client that can call it can request metadata for other known UUIDs within the configured data directory. Keep each server attached to the intended local account.

Uncompressed rollout JSONL is supported. Cloud-only sessions, compressed storage formats, and future schema changes may return unavailable results. Automatic compaction is not disabled, delayed, or triggered by this tool.

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m build

Tests use synthetic temporary rollouts. The MCP integration test starts a real stdio server and calls the tool through the official client SDK. No real conversations belong in fixtures or release artifacts.

References

• Codex App Server documents thread/tokenUsage/updated. This package currently reads the local rollout log rather than attaching to an app-server transport.

• Codex configuration reference documents MCP launch settings and compaction threshold configuration.

• MCP Python SDK provides the optional stdio transport.

MIT licensed. See LICENSE.