context-tracker

v0.5.0

Published

4 days ago

Local request viewer for Claude Code, Codex and OpenCode.

0High
0Medium
0Low

ai-coding-agent agent-observability claude-code codex opencode anthropic openai local-proxy llm llm-observability prompt-debugging prompt-inspection tool-calling

context-tracker

语言: English · 简体中文

将 AI 编码工具(OpenCode / Claude Code / Codex)发送给模型的 HTTP 请求镜像到本地查看器，用于查看完整的请求上下文(headers、system prompt、tools 定义、messages)以及(可选)模型响应。

架构

Claude Code ──ANTHROPIC_BASE_URL──▶ ┐
Codex CLI  ──config.toml base_url─▶ ├─▶ proxy ──HTTPS──▶ AI API
OpenCode   ──opencode.json baseURL▶ ┘      │
                                            └──POST──▶ viewer (:39877)

proxy 向 viewer 发送镜像数据，不影响主链路的正常通信。支持单端口按路径路由到多个上游，viewer 按来源(source)与协议(api)分类展示。

安装

要求 Node.js >= 18，零运行时依赖。

全局安装(推荐)：

npm install -g context-tracker
# 或从源码:git clone https://github.com/conrad621/context-tracker.git && cd context-tracker && npm link

安装后提供单入口命令 context-tracker:

context-tracker start           # 同时启动 viewer + proxy(同一进程)
context-tracker help            # 查看用法

未安装也可直接用脚本:node src/start.js。viewer 与 proxy 仍位于 src/viewer.js / src/proxy.js 供高级用法直接运行,但 CLI 只暴露 start。

使用

快速开始——viewer + proxy 一个进程同时启动：

context-tracker start           # 全局安装
npm start                       # 从仓库(本地)

viewer(Web + 终端)与转发 proxy 作为同一进程一起起,一次 Ctrl+C 同时停。

启动默认静默,只打印监听 URL。想连提示型日志(发现来源、路由表、mirror 地址、抓取状态、终端输出说明)一起看,在命令里加 --verbose/-v:context-tracker start --verbose(仓库内 npm start -- --verbose)。

当 Claude Code 和 Codex 同时配置时,start 会两个都抓(一个端口把 /v1/messages 路由到 Claude 上游、/v1/responses 路由到 Codex 上游)。只想抓其中一个,加 --agent <claude|codex>:发现逻辑只读该客户端的配置,proxy 也只转发该 agent 的路径前缀——其他流量会得到 no route 404,而不是被错误转发到别的目标:

context-tracker start --agent codex      # 只抓 Codex
context-tracker start --agent claude     # 只抓 Claude Code

1. 上游如何选择

start 把 viewer(Web 界面 http://localhost:39877,实时终端输出)与转发 proxy 放在同一进程里跑。proxy 按以下顺序选取上游:

环境变量(自由度最高) — TARGET_URL / ROUTES 始终优先于自动发现;想要特定上游、自定义端口、或完全不用配置文件时用它:

# 单上游
TARGET_URL=https://api.deepseek.com context-tracker start

# 多上游路由(一个端口同时抓 Claude + Codex)
ROUTES='[
  {"prefix":"/v1/messages","target":"https://api.anthropic.com","source":"claude-code"},
  {"prefix":"/v1/responses","target":"https://api.openai.com","source":"codex"}
]' context-tracker start

自动发现(默认,免配置) — 如果你用 Claude Code 和/或 Codex CLI,proxy 能从客户端自己的配置文件里推导上游,完全不用维护 profiles.json 也不用设 TARGET_URL:
```
context-tracker start               # 不带 env:自动发现上游
```

发现逻辑遵循各客户端官方的读取姿势与合并顺序:

Claude Code — 依次读 ~/.claude/settings.local.json、~/.claude/settings.json(local 覆盖 user)→ env.ANTHROPIC_BASE_URL;兜底读 ANTHROPIC_BASE_URL 环境变量。Claude 流量固定落在 /v1/messages。
Codex CLI — 读 ~/.codex/config.toml → 活跃 [model_providers.*] 的 base_url + wire_api;兜底读 OPENAI_BASE_URL(wire 取 CODEX_WIRE_API || "chat")。Codex 流量落在 /responses(chat wire 则 /chat/completions)。

两者都找到时,一个端口按前缀同时路由到两个上游(--verbose 会显示发现来源)。要指向非默认路径(或在 CI/测试里覆盖):CT_CLAUDE_SETTINGS、CT_CLAUDE_SETTINGS_LOCAL、CT_CODEX_CONFIG。设 AUTO_DISCOVER=0 可关闭。

发现到的上游如果指回 proxy 自身(loopback host + proxy/mirror 端口)会被忽略——所以过时的捕获设置 ANTHROPIC_BASE_URL=http://localhost:39876 不会造成环。其他端口上的合法本地上游(如 Ollama :11434)正常放行。若所有候选都被过滤,启动报错会逐条列出是哪个来源指回了 proxy,方便定位。自动发现只覆盖 Claude Code 和 Codex 的配置;其余工具(OpenCode、DeepSeek 等)仍需 env。

profiles.json(schema:target,或带 prefix/target/source 的 routes;另有 port/mirrorPort/captureResponse/maxResponseBytes/redactAuth)仍保留给程序化使用者,通过 src/config.js 的 loadProfiles() / resolveConfig() 读取(PROFILES 可覆盖其路径);CLI 不使用它。

3. 配置各工具指向 proxy

Claude Code(调用 POST /v1/messages)：

export ANTHROPIC_BASE_URL=http://localhost:39876
export ANTHROPIC_API_KEY=sk-ant-...        # 或 ANTHROPIC_AUTH_TOKEN
claude

Codex CLI(调用 POST /v1/responses)——编辑 ~/.codex/config.toml：

model_provider = "capture"

[model_providers.capture]
name = "Capture Proxy"
base_url = "http://localhost:39876/v1"      # 客户端会发 /v1/responses
env_key = "OPENAI_API_KEY"
wire_api = "responses"

export OPENAI_API_KEY=sk-...
codex

Codex 默认走 ChatGPT 订阅登录，抓包需改用 API key 鉴权(上面的 env_key)。

OpenCode——在 opencode.json 中配置对应 provider 的 baseURL 为 http://localhost:39876。

⚠️ /v1 路径前缀：Claude Code 与 Codex 会自己发送带 /v1 的完整路径，因此 TARGET_URL / route target 必须是主机根(如 https://api.anthropic.com，不带 /v1)，否则会出现 /v1/v1/... 双前缀。OpenCode 若只发 /messages，则 TARGET_URL 需要带 /v1。

4. 开始对话

请求上下文会实时显示在 viewer 的终端和 Web 界面中。每条请求提供 structured / raw / headers /(可选)response 视图。

Web 界面特性：

搜索:顶部搜索框按 path / model / 内容实时过滤并高亮(快捷键 / 聚焦,Esc 清除)
过滤:source / api chip 点选,多选叠加
实时指标:请求总数、当前显示数、每分钟请求数
暂停 / 跟随 / 清空:pause 暂停实时更新,follow 自动滚动到最新,clear 清空视图
文本框选取:hover 任意正文框弹出 select all / copy,双击整块选中
增量同步:客户端只拉取新增/更新条目(/__history?since=),poll 开销与历史规模无关
虚拟滚动:只渲染视口内条目,上千条请求也只有数十个 DOM 节点,不卡顿
展开稳定:点击展开的条目在实时刷新时保持展开、保留当前 tab
响应用量:开启响应抓取后,响应面板会把 SSE 流解析成 token 用量 / stop reason / tool call 摘要
请求 diff:"diff" 视图把每个请求与同来源的上一个请求对比:system prompt 变化、tool 增删改、消息轮次增删
token 计量与构成:每条请求显示 token 数(抓到响应用真实用量,否则估算),并用堆叠条拆分为 system / tools / history / current,附各 tool 开销
成本统计:Stats 面板按 model 和 source 聚合(请求数、token、预估美元成本);价格可在 config/pricing.json 配置
浪费检测:标记超大 system prompt、过大/重复的 tool schema、过长历史、重复消息,并给出建议列表
会话过滤:带 session 标识的请求(来自 header 或 body)可被单独筛出,把一个 agent 任务的多轮请求作为时间线查看
导出:把当前视图、单条请求或整个会话导出为 JSON / Markdown / HAR(通过导出链接或 /__export 接口)

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | PROFILES | ./config/profiles.json | profile 配置文件路径 | | AUTO_DISCOVER | 1 | 为 1(默认)时 proxy 不带 profile/env 会从 Claude Code / Codex 配置文件自动发现上游;设 0 关闭 | | CT_CLAUDE_SETTINGS | ~/.claude/settings.json | 自动发现:Claude Code settings 文件路径 | | CT_CLAUDE_SETTINGS_LOCAL | ~/.claude/settings.local.json | 自动发现:Claude Code 本地 settings 路径(覆盖 user settings) | | CT_CODEX_CONFIG | ~/.codex/config.toml | 自动发现:Codex CLI 配置文件路径 | | PROXY_PORT | 39876 | proxy 监听端口 | | MIRROR_PORT | 39877 | viewer 监听端口 | | TARGET_URL | - | 单上游 base URL；配合或作为 ROUTES 的回落 | | ROUTES | - | JSON 数组，按 prefix 路由到不同 target，可带 source 标签 | | SOURCE | - | 单上游模式下手动指定来源标签 | | CAPTURE_RESPONSE | - | 设为 1 时 tee 并聚合 SSE 响应，关联到对应请求 | | MAX_RESPONSE_BYTES | 2097152 | 响应聚合上限(超出截断) | | MAX_HISTORY | 2000 | viewer 保留的最大请求条数 | | REDACT_AUTH | - | 设为 1 时脱敏 API key(viewer 渲染时生效) |

测试

npm test        # 即 node --test

包含 protocols 抽取单测(Anthropic Messages / OpenAI Chat / OpenAI Responses)、config/profile 加载与自动发现单测,与端到端测试(mock SSE 上游 + proxy + viewer,验证路由、流式透传、镜像分类、脱敏、响应聚合、profile 启动,以及从注入的客户端配置文件自动发现)。

支持的协议

| API | 路径 | 来源工具 | |-----|------|----------| | Anthropic Messages | /v1/messages | Claude Code | | OpenAI Responses | /v1/responses | Codex | | OpenAI Chat Completions | /v1/chat/completions | OpenCode / DeepSeek 等 |

限制

仅适用于 header 鉴权的 provider(Anthropic、OpenAI、DeepSeek、OpenRouter 等)；AWS Bedrock(SigV4)/ Google Vertex 等签名鉴权不适用。
Codex 订阅登录(ChatGPT)不可抓，需切换到 API key 鉴权。
响应抓取有内存成本，受 MAX_RESPONSE_BYTES 上限约束，超长响应仅保留截断副本。

路线图

项目未来方向见 ROADMAP.md。

许可

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

context-tracker

架构

安装

使用

1. 上游如何选择

3. 配置各工具指向 proxy

4. 开始对话

环境变量

测试

支持的协议

限制

路线图

许可