v0.2.1: Remaining percentage and clearer task identity

Compact MCP snapshots now include remaining_percent, calculated against the recorded effective window and rounded to one decimal place. The value is null whenever the remaining budget is unknown, including after compaction. It does not represent headroom to an auto-compaction threshold.

The tool description now identifies concrete current-task ID sources: nodeRepl.requestMeta.threadId when available in Codex, or CODEX_THREAD_ID through native exec_command. Shared MCP shell environments, including FastCtx run, cannot reliably identify the caller.

This is an additive response change. Existing fields, arguments, CLI output, and library results remain compatible. Validation includes 94 tests and cross-platform CI.

Restart an existing context-meter MCP server or its host after upgrading to load the new field and tool description.

v0.2.0: Compact context-planning responses

MCP now returns one minified JSON payload containing only status, used tokens, window size, remaining tokens, and log event age. This reduces repeated context overhead and prevents newer MCP SDKs from duplicating the response in structuredContent.

This changes the MCP response format: last_request.total_tokens becomes used_tokens, and remaining_estimate.tokens becomes remaining_tokens. Tool arguments, CLI output, and the Python library remain compatible. An explicitly supplied compaction threshold adds compaction_remaining_tokens; otherwise the field is omitted.

Unknown, stale, and post-compaction states remain explicit. Errors retain actionable codes and messages. Full timestamps, component counters, and other diagnostics remain available through the CLI.

Validation: 91 synthetic tests; MCP stdio checks with SDK 1.9.2 and 1.29.1; Windows, macOS, and Linux CI. Assets include a wheel and source archive.

Restart an existing context-meter MCP server or its host after upgrading so it loads the new code and tool description.

v0.1.1: Fix resumed-task context readings

Resumed Codex tasks can write new rollout segments with a UUID suffix. Version 0.1.0 missed these files and could return an old snapshot even while the task had newer usage records.

Version 0.1.1 follows validated continuation references to the final segment. It shares the scan budget across inherited history, respects recorded byte boundaries, and preserves compaction detection across files. Ambiguous or incomplete histories return explicit errors.

The CLI and MCP tool keep their existing arguments and response schema. Reads remain local and on demand, with no background recorder or network requests. Restart an existing context-meter MCP server or its host after upgrading so it loads the new code.

Validation includes 78 synthetic tests, real MCP stdio calls, and CI on Windows, macOS, and Linux with Python 3.10, 3.12, and 3.13. Release assets include a wheel and source archive.

v0.1.0

Changelog

0.1.0

• Add a standard-library CLI for explicitly selected local Codex threads.
• Add a read-only MCP stdio tool using the official Python SDK.
• Report last-request counters, recorded effective window, estimated remaining context, and event age.
• Withhold estimates after recognized compaction until a new usage record arrives.
• Bound log reads, validate session identity, and expose structured errors without conversation contents.