判断先说：claude-tap 是给"天天用编码 agent、但不知道它到底发了什么请求"的人准备的一把放大镜。它把本地代理和 trace 查看器拼在一起，让你看清 agent 的真实 API 流量——system prompt、对话历史、工具定义、流式响应、token 用量，全都能翻出来对比。项目用 Python 写，MIT 协议，目前 3300 多星。
解决什么问题
编码 agent 的黑盒在于：你下了个指令，它自己决定调什么工具、发什么请求、拼什么上下文，中间过程你看不见。出了错，你只知道结果不对，不知道是 prompt 不对、检索不对还是工具调用不对。claude-tap 的做法是让你的 CLI 经过它跑，或者监听本地 App 的 transcript，把每一轮请求-响应对都记成本地 trace，再导出一个零依赖的自包含 HTML 给你翻。它覆盖的客户端很广：Claude Code、Codex CLI 和 App、Gemini CLI、Grok、DeepSeek Harness、Kimi、OpenCode、Pi、Cursor、CodeBuddy 等十几个。
安装与上手
要求 Python 3.11+，推荐用 uv 装：
uv tool install claude-tap
然后让它接管你的 agent。默认接管 Claude Code，--tap-client 切换别的客户端，-- 后面的参数原样传给客户端：
claude-tap # Claude Code，实时 viewer 默认开启
claude-tap --tap-client codex # Codex CLI
claude-tap --tap-client gemini -- -p "hello" # Gemini CLI，带参数
claude-tap --tap-client cursor # Cursor：监听 transcript，不做 MITM
claude-tap -- --model claude-opus-4-6 # 给 Claude Code 传模型参数
每次运行结束后生成一份 trace，可以用 claude-tap export 导出成可移植的 compact 包或自包含 HTML：
claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html
关键设计
三件事值得拆开看。
一是代理模式分三种。支持改 base URL 的客户端（Claude Code、Codex、Kimi 等）走 reverse proxy，把流量转发到上游的同时记录下来；多 provider 的客户端（Gemini、OpenCode、Pi 等）走 forward proxy，靠 CA 证书做 MITM；Cursor 这种没有标准 API 入口的，只监听它落在 ~/.cursor 下的 agent transcript，不做代理。
二是trace viewer 是个自包含 HTML。它不做服务端，打开就是一个能全文搜索、按模型分组、按 token 用量拆解、做结构化 diff 的页面。对比相邻请求，能直接看出哪条 message、哪个 tool 参数变了，字符级高亮。8 种语言、深色模式、键盘导航都有。
三是隐私边界默认收紧。常见的 auth 头在落盘前就自动脱敏，trace 留本机，不托管 dashboard。这个设计对把 trace 当审计证据的人很关键——你拿它去查问题，不该顺手把 key 也存一遍。
可复用点
就算不用 claude-tap 本身，它那套"trace 加 diff"的排查思路也值得抄：给 agent 的每次请求留一份结构化快照，出问题时对比相邻请求，通常比看日志快得多。具体到日常，它最实用的是那行结构化 diff——你改了个 prompt 或工具参数，重跑一次对比，就知道是不是这个改动把 agent 带偏了。它派生出来的 Phistory 项目也证明了这条路——用 capture-only 的模式归档各 agent CLI 的 system prompt 快照做版本对比。
局限
proxy 模式天然要处理加密和签名：AWS 原生 Bedrock 走 SigV4 签名，改 base URL 会破坏签名，得退回 forward 模式；本地 CA 要信任进 keychain，本身又是一层攻击面。Cursor 那条 transcript-only 的路径能看的内容比 MITM 少。此外它是个观测工具，只负责"看"，不负责"拦"——真要做请求级别的准入控制，得另外接一层。最后提醒一句：它靠监听本地流量工作，意味着你本机已经是信任边界，装到共享机器上等于给别人一把看流量的话筒。