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
}状态级别
| 状态 | 压实度% | 建议措施 |
|---|---|---|
| 正常 | \<50% | 正常运行 |
| 中等 | 50-75% | 请注意，无需采取任何行动 |
| HIGH | 75–90% | 开始将重要状态保存到持久存储 |
| 关键 | 90%+ | 立即保存所有内容——压缩迫在眉睫 |
代理商应该如何使用它
- 呼叫
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"环境变量
| 变量 | 描述 |
|---|---|
CONTEXT_MONITOR_BACKEND | 强制后端： claude-code 或 codex-cli |
CONTEXT_MONITOR_WINDOW | 上下文窗口大小（标记） |
CONTEXT_MONITOR_BUFFER | 自动压缩缓冲区（令牌） |
CONTEXT_MONITOR_OVERHEAD | 静态开销估计（令牌） |
CONTEXT_MONITOR_BPT | 每个令牌的字节数比率 |
CONTEXT_MONITOR_TRANSCRIPT | 显式转录文件路径 |
CONTEXT_MONITOR_PROJECT_DIR | 成绩单目录 |
运作原理
- 初创公司：自动检测后端（Claude Code或Codex CLI）并查找活动会话记录
- 压实检测：扫描压缩标记以找到当前上下文的边界
- 内容估算：分析压缩后的内容，按类型分类（文本、工具调用、工具结果、思维、系统）
- 代币估算:
- *克劳德代码*：使用校准的字节/令牌比率从字节计数估计令牌 - *Codex CLI*：使用来自的本地令牌计数 turn_complete 事件可用时
- 缓存：将扫描位置存储在sidecar文件中，以便后续调用只处理新字节
算什么
- 用户消息、助手消息、系统提示
- 工具使用（函数调用）和工具结果
- 压实总结（来自之前的压实）
排除的内容
- 思维/推理块（生成后不保留在上下文中）
- JSON包装器开销（仅计算内容字节）
许可证
麻省理工学院——见 许可证.