Skip to main content
Glama

mcp-context-monitor

Context window usage estimation for AI coding agents via MCP.

Parses your session transcript to estimate how close you are to context compaction, so agents can proactively save important state before it's lost. Supports Claude Code and Codex CLI backends with auto-detection.

Why

AI coding agents accumulate context through conversation, tool calls, and file reads. When the context window fills up, compaction discards older content. Agents that know compaction is coming can write key insights to persistent storage first — memory queues, documents, knowledge graphs — instead of losing them silently.

Related MCP server: Total Recall

Features

  • Live estimation — Single MCP tool returns usage percentage, distance to compaction, and status level

  • Multi-backend — Supports Claude Code (JSONL transcripts) and Codex CLI (native token counts) with auto-detection

  • Incremental scanning — Sidecar cache tracks scan position; subsequent calls only process new bytes

  • Compaction-aware — Finds the last compaction boundary and measures only post-compaction content

  • Configurable — TOML config for thresholds, token ratios, and backend-specific settings

  • Zero infrastructure — Reads the transcript file directly, no daemon or network calls

Quick Start

Requires Python 3.11+ and uv.

git clone https://github.com/sophia-labs/mcp-context-monitor.git
cd mcp-context-monitor
uv sync

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "context-monitor": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-context-monitor", "python", "server.py"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.context-monitor]
command = "uv"
args = ["run", "--directory", "/path/to/mcp-context-monitor", "python", "server.py"]

The backend is auto-detected based on which CLI has the most recent transcript.

Usage

Call context_status() from your agent:

{
  "status": "HIGH",
  "usage_percent": 73.9,
  "compaction_percent": 88.5,
  "estimated_tokens_used": 147780,
  "estimated_tokens_remaining": 19220
}

Status Levels

Status

Compaction %

Recommended Action

OK

< 50%

Normal operation

MODERATE

50–75%

Be aware, no action needed

HIGH

75–90%

Start saving important state to persistent storage

CRITICAL

90%+

Save everything immediately — compaction is imminent

How Agents Should Use This

  • Call context_status() periodically during long sessions

  • At HIGH: write key insights to memory queue, sing if at a phase transition

  • At CRITICAL: write everything important to persistent storage immediately

  • The compaction_percent measures distance to the compaction trigger, not the total window

Configuration

Create ~/.config/context-monitor/config.toml:

# Backend selection: "auto", "claude-code", or "codex-cli"
[backend]
type = "auto"

# Claude Code settings
[claude-code]
context_window = 200000
autocompact_buffer = 33000
static_overhead = 43500
bytes_per_token = 3.2
# transcript_dir = "~/.claude/projects"

# Codex CLI settings
[codex-cli]
context_window = 400000
max_output_tokens = 128000
autocompact_ratio = 0.95
static_overhead = 30000
bytes_per_token = 3.2
# transcript_dir = "~/.codex/sessions"

Environment Variables

Variable

Description

CONTEXT_MONITOR_BACKEND

Force backend: claude-code or codex-cli

CONTEXT_MONITOR_WINDOW

Context window size (tokens)

CONTEXT_MONITOR_BUFFER

Autocompact buffer (tokens)

CONTEXT_MONITOR_OVERHEAD

Static overhead estimate (tokens)

CONTEXT_MONITOR_BPT

Bytes-per-token ratio

CONTEXT_MONITOR_TRANSCRIPT

Explicit transcript file path

CONTEXT_MONITOR_PROJECT_DIR

Transcript directory

How It Works

  1. Startup: Auto-detects backend (Claude Code or Codex CLI) and finds the active session transcript

  2. Compaction detection: Scans for compaction markers to find the boundary of current context

  3. Content estimation: Parses post-compaction content, categorizing by type (text, tool calls, tool results, thinking, system)

  4. Token estimation:

    • Claude Code: Estimates tokens from byte counts using a calibrated bytes-per-token ratio

    • Codex CLI: Uses native token counts from turn_complete events when available

  5. Caching: Stores scan position in a sidecar file so subsequent calls only process new bytes

What's Counted

  • User messages, assistant messages, system prompts

  • Tool use (function calls) and tool results

  • Compaction summaries (from prior compactions)

What's Excluded

  • Thinking/reasoning blocks (not retained in context after generation)

  • JSON wrapper overhead (only content bytes are counted)

License

MIT — see LICENSE.

Available Tools

1 tool
context_statusA

Estimate current context window usage and distance to compaction. Returns phase (open/midstream/narrowing/threshold), token estimates, and profile range (coding/balanced/reading). Use this to self-manage: open (<50%), midstream (50-80%), narrowing (80-92%, start choosing what to carry), threshold (>92%, write what matters now). Optionally pass transcript_path to target a specific session file.

Inputs: transcript_path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only a single tool, there is no ambiguity or overlap in the set. The tool's purpose is clearly defined and distinct.

    Naming Consistency5/5

    The tool name 'context_status' is descriptive and follows a consistent style. Since there is only one tool, naming consistency is perfect.

    Tool Count2/5

    The server has exactly one tool, which is considered too few for a functional toolset. It provides a single point of functionality but lacks supporting tools.

    Completeness4/5

    The tool covers the core need of monitoring context usage with clear thresholds, but it lacks additional features like history tracking or configuration, leaving minor gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers