Claude Tap là gì? Phân tích repo liaohch3/claude-tap và hướng dẫn sử dụng

Claude Tap là gì? Phân tích repo liaohch3/claude-tap và hướng dẫn sử dụng dễ hiểu

Ảnh trích xuất từ repo chính thức liaohch3/claude-tap, file docs/viewer-light.png. Ảnh là PNG, không phải SVG.¹

Tóm tắt nhanh

claude-tap là một công cụ local proxy và trace viewer cho các AI coding agent. Repo chính thức mô tả nó là công cụ cho phép chạy CLI agent thông qua proxy, sau đó xem lại traffic API thật: system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage và request diffs.²

Nói dễ hiểu: khi bạn dùng Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi, Pi hoặc Hermes, bạn thường chỉ thấy câu trả lời cuối cùng của agent. Bạn không thấy chính xác agent đã gửi prompt gì lên model, tool schema ra sao, tool call nào được gọi, token usage bao nhiêu, hoặc request thứ hai khác request thứ nhất ở điểm nào. claude-tap giúp bạn nhìn thấy toàn bộ “hộp đen” đó trên máy local.

Repo README nhấn mạnh rằng trace được giữ trên máy người dùng, không cần hosted dashboard, và các auth headers phổ biến được redacted trước khi ghi lại.³ Tuy vậy, trace vẫn có thể chứa prompt, file path, tool schema, response body và ngữ cảnh riêng tư, nên cần xử lý cẩn thận.⁴

Claude Tap dùng để làm gì?

Claude Tap hữu ích nhất khi bạn muốn hiểu vì sao AI coding agent hành xử như vậy.

Các câu hỏi nó giúp trả lời:

• Agent đã gửi system prompt nào lên model?
• Conversation history đang phình ra ở bước nào?
• Tool schemas có quá dài không?
• Tool call nào được model chọn?
• Tool result nào làm model đổi hướng?
• Token usage của mỗi request là bao nhiêu?
• Cache read / cache creation có hoạt động không?
• Request trước và request sau khác gì?
• Vì sao agent bỗng dưng quên instruction?
• Vì sao agent gọi tool sai hoặc không gọi tool?
• Provider/API endpoint thực tế là gì?

Đây là công cụ thuộc nhóm agent observability và agent debugging: nó không thay thế agent, mà giúp bạn quan sát agent đang nói gì với model.

Claude Tap không phải là gì?

Điểm cần nhớ: Claude Tap không làm model thông minh hơn. Nó giúp bạn nhìn rõ model và agent đang trao đổi gì.

Repo liaohch3/claude-tap có gì đáng chú ý?

Trang GitHub mô tả repo là công cụ intercept và inspect API traffic của Coding Agent từ Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi, Pi và Hermes trong local trace viewer.⁵ Repo dùng MIT license, yêu cầu Python 3.11+, và package script chính là claude-tap.⁶

Các điểm chính trong README:

• Live browser viewer bật mặc định.
• Hỗ trợ export self-contained HTML viewer.
• Hỗ trợ trace nhiều client.
• Có structured diff giữa các request.
• Có token usage breakdown.
• Có tool inspector.
• Có search toàn văn trong messages/tools/prompts/responses.
• Có reverse proxy và forward proxy.
• Có forward proxy + local CA cho client không hỗ trợ base URL override.
• Trace được lưu local trong thư mục .traces mặc định.⁷

Hỗ trợ client nào?

README liệt kê các client chính:⁸

Support matrix chính thức cũng ghi rõ mode mặc định theo client: Claude, Codex, Kimi và CodeBuddy thường dùng reverse mode; Gemini, OpenCode, Pi, Hermes, Cursor, Qoder và Antigravity thường dùng forward mode.⁹

Reverse proxy và forward proxy là gì?

Claude Tap có hai cách bắt traffic:

Cách hiểu đơn giản:

Reverse proxy:
Client → localhost proxy → API provider

Forward proxy:
Client → HTTPS_PROXY local → nhiều API provider

Support matrix ghi rõ từng client chọn mode mặc định dựa trên khả năng của client và số endpoint mà client gọi.⁹

Cài đặt Claude Tap

Yêu cầu:

• Python 3.11+
• Client bạn muốn trace, ví dụ Claude Code, Codex CLI, Gemini CLI, Cursor CLI hoặc Hermes Agent

Cài bằng uv:

uv tool install claude-tap

Hoặc pip:

pip install claude-tap

Nâng cấp:

claude-tap update
uv tool upgrade claude-tap
pip install --upgrade claude-tap

README nêu uv tool install claude-tap là cách khuyến nghị.¹⁰

Kiểm tra:

claude-tap --help

Quickstart với Claude Code

Chạy mặc định:

claude-tap

Lệnh này chạy Claude Code thông qua Claude Tap và live browser viewer được bật mặc định.¹¹

Truyền flag cho Claude Code sau dấu --:

claude-tap -- --model claude-opus-4-6

Tiếp tục conversation gần nhất:

claude-tap -c

Bỏ permission prompt của Claude Code:

claude-tap -- --dangerously-skip-permissions

Lưu ý: --dangerously-skip-permissions là flag của Claude Code, không phải tính năng an toàn của claude-tap. Chỉ dùng trong môi trường bạn chấp nhận rủi ro agent tự gọi tool.

Dùng với Codex CLI

Chạy Codex CLI qua Claude Tap:

claude-tap --tap-client codex

Nếu dùng OAuth sau codex login, README nói claude-tap có thể auto-detect target https://chatgpt.com/backend-api/codex khi đọc được auth state.¹²

Nếu cần chỉ định target:

claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex

Nếu dùng API key mode:

export OPENAI_API_KEY="..."
claude-tap --tap-client codex

Truyền flag sang Codex:

claude-tap --tap-client codex -- --model codex-mini-latest

Full auto:

claude-tap --tap-client codex -- --full-auto

Dùng với Gemini CLI

Gemini CLI mặc định dùng forward proxy mode vì Google OAuth / Code Assist traffic đi qua nhiều Google endpoints.¹³

claude-tap --tap-client gemini -- -p "hello"

Nếu flow của bạn tương thích API key hoặc Vertex và có base URL, có thể thử reverse mode:

claude-tap --tap-client gemini --tap-proxy-mode reverse -- -p "hello"

Dùng với Cursor CLI

Cursor CLI dùng forward proxy mode mặc định. README khuyến nghị dùng --model auto với free plans và bỏ --mode ask nếu muốn có tool calls.¹⁴

claude-tap --tap-client cursor -- -p --trust --model auto "hello"

Tiếp tục:

claude-tap --tap-client cursor -- -p --trust --model auto --continue "continue"

Dùng với OpenCode

OpenCode là multi-provider terminal AI assistant, nên Claude Tap mặc định dùng forward proxy mode để bắt traffic tới bất kỳ provider nào.¹⁵

claude-tap --tap-client opencode

Nếu chỉ dùng Anthropic provider và muốn reverse mode:

claude-tap --tap-client opencode --tap-proxy-mode reverse

Dùng với Hermes Agent

Hermes Agent là multi-provider Python AI agent. README nói httpx và requests đều honor HTTPS_PROXY, vì vậy claude-tap dùng forward proxy mode mặc định cho Hermes.¹⁶

TUI/local trace:

claude-tap --tap-client hermes

Gateway mode:

claude-tap --tap-client hermes -- gateway start

Claude Tap tự rewrite gateway start thành gateway run để gateway chạy foreground và kế thừa proxy env; nếu gateway chạy daemon qua systemd/launchd thì traffic có thể không đi qua proxy.⁹

Lưu ý: gateway mode chỉ có trace khi một nền tảng messaging như Slack hoặc Telegram thật sự gửi message tới bot.¹⁶

Live viewer, dashboard và export

Live viewer chạy mặc định:

claude-tap

Tắt live viewer:

claude-tap --tap-no-live

Mở dashboard xem trace đã lưu:

claude-tap dashboard

Export JSONL trace thành HTML:

claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html

Export compact bundle:

claude-tap export <session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html

README nói viewer HTML là self-contained và có thể dùng để review hoặc archive.¹⁷

Viewer có gì hay?

Ảnh trích xuất từ repo chính thức liaohch3/claude-tap, file docs/diff-modal.png. Ảnh là PNG, không phải SVG.¹⁸

README liệt kê các khả năng của viewer:¹⁹

Đây là phần làm Claude Tap khác với việc chỉ log raw JSON. Nó giúp người dùng đọc trace nhanh hơn.

Kiến trúc hoạt động

Ảnh trích xuất từ repo chính thức liaohch3/claude-tap, file docs/architecture.png. Ảnh là PNG, không phải SVG.²⁰

README mô tả luồng hoạt động như sau:²¹

1. claude-tap khởi động reverse hoặc forward proxy và spawn client được chọn.
2. Client có base URL sẽ được trỏ vào reverse proxy; client không có base URL sẽ dùng proxy/CA environment variables.
3. SSE và WebSocket streams được forward theo chunks/messages khi nhận được.
4. Mỗi request-response pair hoặc WebSocket session được ghi vào local trace storage.
5. Khi client exit, claude-tap tạo self-contained HTML viewer.
6. Live mode mặc định broadcast update tới browser qua SSE.

Có thể hình dung:

AI coding agent CLI
        ↓
claude-tap proxy
        ↓
LLM provider / gateway / OAuth backend
        ↓
trace storage local
        ↓
live viewer / dashboard / exported HTML

Thư mục trace và quản lý dung lượng

Mặc định, trace nằm trong:

./.traces/

Đổi thư mục:

claude-tap --tap-output-dir ./my-traces

Giới hạn số session giữ lại:

claude-tap --tap-max-traces 10

Không giới hạn:

claude-tap --tap-max-traces 0

Dùng proxy-only mode:

claude-tap --tap-no-launch --tap-port 8080

Khi chạy proxy-only, bạn tự mở client ở terminal khác và cấu hình base URL/proxy trỏ về Claude Tap.²²

Các option quan trọng

README nói tất cả flags không phải --tap-* sẽ được forward sang client được chọn.²³

Khi nào nên dùng Claude Tap?

Nên dùng khi:

• bạn đang debug AI coding agent;
• agent gọi tool sai;
• agent quên context hoặc tự thay đổi hướng;
• bạn cần so sánh prompt giữa nhiều lượt;
• bạn muốn biết tool schema có quá dài không;
• bạn muốn đo token usage/cache usage;
• bạn đang đánh giá nhiều coding agent;
• bạn muốn chia sẻ trace self-contained HTML cho team review;
• bạn muốn kiểm chứng endpoint/gateway/provider thật sự được gọi.

Không nên dùng nếu:

• bạn không muốn lưu prompt/context local;
• dự án chứa dữ liệu cực kỳ nhạy cảm nhưng chưa có quy trình redaction;
• bạn đang chạy trên máy dùng chung;
• bạn chưa hiểu forward proxy/local CA hoạt động thế nào;
• client đang dùng chính sách doanh nghiệp cấm MITM/proxy capture;
• bạn cần log production có compliance nghiêm ngặt.

Triển khai cho cá nhân

Quy trình khuyến nghị:

# 1. Cài
uv tool install claude-tap

# 2. Chạy với client thường dùng
claude-tap
# hoặc
claude-tap --tap-client codex
# hoặc
claude-tap --tap-client cursor -- -p --trust --model auto "hello"

# 3. Mở live viewer trong browser

# 4. Sau khi chạy xong, mở dashboard
claude-tap dashboard

# 5. Export khi cần chia sẻ
claude-tap export <session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html

Nên thêm .traces/ vào .gitignore nếu bạn chạy trong project Git.

Triển khai cho team

Giai đoạn 1: dùng cá nhân

• Mỗi developer cài claude-tap.
• Chạy với agent họ đang dùng.
• Dùng trace để hiểu context, tools, token usage.
• Không chia sẻ raw trace nếu chưa redacted.

Giai đoạn 2: quy tắc chia sẻ trace

Tạo policy:

- Không gửi .traces/*.jsonl thô ra ngoài team.
- Không gửi HTML trace nếu chưa review nội dung.
- Redact API keys, file paths, customer data, prompt nội bộ.
- Dùng compact export khi cần review nhẹ.
- Xóa trace cũ định kỳ.

Giai đoạn 3: dùng trong review agent workflow

Dùng Claude Tap để review:

• prompt quá dài;
• tool schema quá rộng;
• context không cần thiết;
• token/cost bất thường;
• agent bị tool result gây nhiễu;
• prompt injection xuất hiện trong tool output;
• provider/gateway routing sai.

Giai đoạn 4: tích hợp với observability nội bộ

Không nên tự động upload trace lên server chung nếu chưa có privacy review. Nếu team cần hệ thống trace chung, hãy:

• encrypt artifact;
• phân quyền người xem;
• xóa trace theo retention policy;
• tách trace chứa customer data;
• log metadata thay vì full body khi không cần;
• có quy trình security review.

Lưu ý bảo mật

SECURITY.md nhấn mạnh: không đính kèm raw .traces/*.jsonl, HTML viewer, screenshot hoặc recording trừ khi đã review và redacted.⁴ Trace files có thể chứa prompts, tool schemas, file paths, response bodies và private context ngay cả khi API keys được redacted.⁴

Checklist bảo mật:

• Thêm .traces/ vào .gitignore.
• Không commit trace.html hoặc .ctap.json.
• Không gửi trace qua chat công khai.
• Review prompt/system prompt trước khi chia sẻ.
• Kiểm tra file paths và repo names.
• Kiểm tra tool outputs có secret hay customer data không.
• Không bind --tap-host 0.0.0.0 trừ khi hiểu rủi ro.
• Với forward proxy, hiểu local CA/cert được trust ở đâu.
• Không chạy trên máy dùng chung nếu trace chứa dữ liệu nhạy cảm.
• Xóa trace cũ định kỳ.
• Khi report security bug, dùng private vulnerability reporting hoặc liên hệ maintainer riêng.⁴

So sánh Claude Tap với Headroom và RTK

Claude Tap không tối ưu token trực tiếp. Nó giúp bạn nhìn thấy token đang đi đâu để ra quyết định tối ưu sau.

FAQ

Claude Tap là gì?

Claude Tap là local proxy và trace viewer cho AI coding agents. Nó ghi lại API traffic thật như system prompts, messages, tools, tool calls, streaming responses, token usage và request diffs để bạn debug agent.²

Claude Tap có phải chỉ dùng cho Claude Code không?

Không. README liệt kê hỗ trợ Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI và CodeBuddy CLI.⁸

Trace có được gửi lên server ngoài không?

README nói trace được giữ trên máy người dùng và không cần hosted dashboard.³ Tuy vậy, nếu bạn tự export/chia sẻ trace, bạn phải tự redaction dữ liệu nhạy cảm.

Claude Tap có xóa API key không?

README nói common auth headers được redacted trước khi ghi lại.³ Nhưng SECURITY.md cảnh báo trace vẫn có thể chứa prompt, file path, response body và private context.⁴

Reverse proxy khác forward proxy thế nào?

Reverse proxy phù hợp khi client có base URL override rõ. Forward proxy phù hợp với client multi-provider hoặc client gọi nhiều endpoint và cần HTTPS_PROXY + local CA.⁹

Có nên dùng Claude Tap trong CI không?

Có thể dùng để debug, nhưng không nên tự động lưu/share trace nếu chưa có policy. Trace có thể chứa nội dung riêng tư. Nếu dùng CI, hãy giới hạn retention, mask secrets và không upload artifact công khai.

Kết luận

liaohch3/claude-tap là một repo rất hữu ích nếu bạn dùng AI coding agent nghiêm túc. Nó giúp biến một quá trình vốn khó quan sát thành dữ liệu có thể kiểm tra: prompt, messages, tool schemas, tool calls, responses, token usage và diff giữa request. Nhờ đó, bạn có thể hiểu vì sao agent hành xử sai, vì sao token tăng nhanh, hoặc vì sao provider/gateway routing không như mong đợi.

Cách bắt đầu đơn giản nhất là uv tool install claude-tap, sau đó chạy claude-tap với Claude Code hoặc claude-tap --tap-client codex/cursor/gemini. Với team, giá trị lớn nhất là dùng trace để review workflow agent, nhưng cần quy trình bảo mật rõ ràng vì trace có thể chứa dữ liệu riêng tư.

Nguồn tham khảo

Footnotes

1. GitHub raw asset. liaohch3/claude-tap/docs/viewer-light.png. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/viewer-light.png ↩

2. claude-tap README, project overview. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩²

3. claude-tap README, “Why use it”. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩² ↩³

4. claude-tap SECURITY.md. https://raw.githubusercontent.com/liaohch3/claude-tap/main/SECURITY.md ↩ ↩² ↩³ ↩⁴ ↩⁵

5. GitHub. liaohch3/claude-tap. https://github.com/liaohch3/claude-tap ↩

6. claude-tap pyproject.toml. https://raw.githubusercontent.com/liaohch3/claude-tap/main/pyproject.toml ↩

7. claude-tap README, viewer and trace overview. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

8. claude-tap README, supported clients. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩²

9. claude-tap support matrix. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/support-matrix.md ↩ ↩² ↩³ ↩⁴

10. claude-tap README, install section. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

11. claude-tap README, quick start examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

12. claude-tap README, Codex CLI auth modes and examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

13. claude-tap README, Gemini CLI examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

14. claude-tap README, Cursor CLI examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

15. claude-tap README, OpenCode examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

16. claude-tap README, Hermes Agent examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩²

17. claude-tap README, export and advanced options. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

18. GitHub raw asset. liaohch3/claude-tap/docs/diff-modal.png. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/diff-modal.png ↩

19. claude-tap README, viewer features. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

20. GitHub raw asset. liaohch3/claude-tap/docs/architecture.png. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/architecture.png ↩

21. claude-tap README, architecture section. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

22. claude-tap README, viewer/export/advanced options. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

23. claude-tap README, CLI options. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩