上下文监控工具

mcp上下文监视器

AI编码代理的上下文窗口使用率估计 主控程序.

解析您的会话记录，以估计您离上下文压缩有多近，这样代理就可以在重要状态丢失之前主动保存它。支持Claude Code和Codex CLI后端自动检测。

为什么

AI编码代理通过对话、工具调用和文件读取来积累上下文。当上下文窗口填满时，压缩会丢弃旧内容。知道压缩即将到来的代理可以首先将关键见解写入持久存储——内存队列、文档、知识图——而不是默默地丢失它们。

特性

• 实时估算 --单个MCP工具返回使用百分比、压缩距离和状态级别
• 多后端 --支持Claude Code（JSONL转录本）和Codex CLI（本地令牌计数），具有自动检测功能
• 增量扫描 --侧车缓存轨迹扫描位置；后续调用仅处理新字节
• 压实意识 --查找最后一个压实边界，仅测量压实后的含量
• 可配置的 --用于阈值、令牌比率和后端特定设置的TOML配置
• 零基础设施 --直接读取转录文件，无需守护进程或网络调用

快速开始

需要Python 3.11+和 紫外线.

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

克劳德代码

增添 ~/.claude.json:

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

Codex CLI

增添 ~/.codex/config.toml:

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

根据哪个CLI具有最新的转录，自动检测后端。

用法

呼叫 context_status() 来自您的代理人：

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

状态级别

代理商应该如何使用它

• 呼叫 context_status() 在长时间会议期间定期
• 在 高：将关键见解写入内存队列，在阶段转换时唱歌
• 在 关键的：立即将所有重要内容写入持久存储
• 这 compaction_percent 测量到压缩触发器的距离，而不是总窗口

配置

创建 ~/.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"

环境变量

运作原理

1. 初创公司：自动检测后端（Claude Code或Codex CLI）并查找活动会话记录
2. 压实检测：扫描压缩标记以找到当前上下文的边界
3. 内容估算：分析压缩后的内容，按类型分类（文本、工具调用、工具结果、思维、系统）
4. 代币估算:
   • 克劳德代码：使用校准的字节/令牌比率从字节计数估计令牌
   • Codex CLI：使用来自的本地令牌计数 turn_complete 事件可用时
5. 缓存：将扫描位置存储在sidecar文件中，以便后续调用只处理新字节

算什么

• 用户消息、助手消息、系统提示
• 工具使用（函数调用）和工具结果
• 压实总结（来自之前的压实）

排除的内容

• 思维/推理块（生成后不保留在上下文中）
• JSON包装器开销（仅计算内容字节）

许可证

麻省理工学院——见 许可证.