Tokentap（原名 Sherlock）

LLM CLI 工具的 Token 追踪器

安装 • 快速入门 • 功能 • 命令 • 贡献代码

---

tokentap 通过实时终端仪表盘跟踪 LLM CLI 工具的 token 使用情况。您可以实时查看自己正在使用的确切 token 数量。

为什么选择 tokentap？

• 跟踪 token 使用：精确查看每次请求消耗的 token 数量
• 监控上下文窗口：可视化油量表显示累计使用量与上限的对比
• 调试提示：自动将每个提示以 markdown 和 JSON 格式保存，便于后续查看
• 零配置：无需证书、无需设置——只需安装即可使用

安装

pip install tokentap

或者从源码安装：

git clone https://github.com/jmuncor/tokentap.git
cd tokentap
pip install -e .

要求

• Python 3.10+

快速入门

终端 1：启动仪表盘

tokentap start

系统会提示您选择保存捕获提示的位置，随后仪表盘将显示如下内容：

┌─────────────────────────────────────────────────────────────┐
│  TOKENTAP - LLM 流量监视器                           │
├─────────────────────────────────────────────────────────────┤
│  上下文使用量  ████████████░░░░░░░░░░░░░░░░  42%           │
│                 (84,231 / 200,000 tokens)                   │
├─────────────────────────────────────────────────────────────┤
│  时间     提供商    模型                      Tokens     │
│  14:23:01 Anthropic   claude-sonnet-4-20250514   12,847     │
│  14:23:45 Anthropic   claude-sonnet-4-20250514   8,234      │
│  14:24:12 Anthropic   claude-sonnet-4-20250514   15,102     │
├─────────────────────────────────────────────────────────────┤
│  最后一条提示: "你能帮我重构这个函数吗..."   │
└─────────────────────────────────────────────────────────────┘

终端 2：运行您的 LLM 工具

# 对于 Claude Code
tokentap claude

# 对于 Gemini CLI（存在已知问题）
tokentap gemini

# 对于 OpenAI Codex
tokentap codex

# 对于基于 MiniMax 的工具
tokentap run --provider minimax python my_app.py

就是这样！在您工作时，仪表盘会实时更新。

功能

实时终端仪表盘

实时 token 跟踪，并配有彩色油量表：

• 绿色：低于 50% 的限制
• 黄色：50%-80% 的限制
• 红色：超过 80% 的限制

提示存档

所有拦截到的请求都会保存到您指定的目录中：

• Markdown：带有元数据的人类可读格式
• JSON：用于调试的原始 API 请求体

会话摘要

退出时，您将看到总使用量：

会话结束。总共 84,231 个 token，涉及 12 次请求。

命令

命令	描述
tokentap start	启动代理和仪表盘
tokentap claude	配置代理后运行 Claude Code
tokentap gemini	配置代理后运行 Gemini CLI
tokentap codex	配置代理后运行 OpenAI Codex CLI
tokentap run --provider <name> <cmd>	配置代理后运行任意命令

支持的 --provider 提供商：anthropic、openai、gemini、minimax

选项

tokentap start [OPTIONS]

选项：
  -p, --port NUM    代理端口（默认：8080）
  -l, --limit NUM   油量表的 token 限制（默认：200000）

tokentap claude [OPTIONS] [ARGS]...

选项：
  -p, --port NUM    代理端口（默认：8080）

工作原理

┌─────────────────────────────────────────────────────────────────┐
│  终端 1：tokentap start                                     │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  HTTP 代理（localhost:8080）                                ││
│  │  + 仪表盘                                                ││
│  │  + 提示存档                                           ││
│  └─────────────────────────────────────────────────────────────┘│
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTP
                                │
┌───────────────────────────────┴─────────────────────────────────┐
│  终端 2：tokentap claude                                    │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  设置 ANTHROPIC_BASE_URL=http://localhost:8080              ││
│  │  运行：claude                                               ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ HTTPS
                                ▼
                      ┌───────────────────┐
                      │ api.anthropic.com │
                      └───────────────────┘

对于兼容 OpenAI 的提供商，例如 MiniMax，tokentap 使用路径前缀路由，以便将请求转发到正确的上游 API：

tokentap run --provider minimax python my_app.py
  → 设置 OPENAI_BASE_URL=http://localhost:8080/minimax/v1
  → 请求到达 /minimax/v1/chat/completions
  → 代理移除前缀，转发至 https://api.minimax.io/v1/chat/completions

支持的提供商

提供商	命令	状态
Anthropic（Claude Code）	tokentap claude	支持
Google（Gemini CLI）	tokentap gemini	因上游问题被阻止
OpenAI（Codex）	tokentap codex	支持
MiniMax	tokentap run --provider minimax <cmd>	支持

已知问题

Gemini CLI

Gemini CLI 目前存在一个已知问题，即在使用 OAuth 认证时会忽略自定义的基础 URL。一旦 Gemini CLI 团队修复此问题，tokentap 的 Gemini 支持将自动生效。

贡献

欢迎贡献！以下是您可以提供帮助的方式：

1. Fork 仓库
2. 创建 一个特性分支（git checkout -b feature/amazing-feature）
3. 提交 您的更改（git commit -m '添加超赞功能'）
4. 推送到 该分支（git push origin feature/amazing-feature）
5. 打开 一个 Pull Request

开发环境搭建

git clone https://github.com/jmuncor/tokentap.git
cd tokentap
python -m venv venv
source venv/bin/activate
pip install -e .

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

---

查看真正发送给大语言模型的内容。跟踪、学习、优化。

tokentap.ai

Tokentap 快速上手指南

Tokentap（原名 Sherlock）是一款专为 LLM CLI 工具设计的 Token 追踪器。它通过实时终端仪表盘，帮助你监控每次请求的 Token 消耗、上下文窗口使用情况，并自动保存提示词（Prompt）以便调试。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS 或 Linux
• Python 版本：Python 3.10 或更高版本
• 前置依赖：无需配置证书或复杂的环境变量，安装即可使用。
• 支持的工具：Claude Code, OpenAI Codex, MiniMax 等（Gemini CLI 目前因上游 OAuth 问题暂时受限）。

安装步骤

你可以选择通过 PyPI 直接安装，或从源码安装。

方式一：使用 pip 安装（推荐）

pip install tokentap

国内加速建议：如果下载速度较慢，建议使用国内镜像源：

pip install tokentap -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

git clone https://github.com/jmuncor/tokentap.git
cd tokentap
pip install -e .

基本使用

Tokentap 采用双终端模式运行：一个终端启动监控仪表盘，另一个终端运行你的 LLM 工具。

第一步：启动监控仪表盘

在第一个终端窗口中运行以下命令。系统会提示你选择提示词保存目录，随后将显示实时仪表盘：

tokentap start

启动后，你将看到类似以下的界面，包含上下文使用率（燃料表）和实时 Token 流水：

┌─────────────────────────────────────────────────────────────┐
│  TOKENTAP - LLM Traffic Inspector                           │
├─────────────────────────────────────────────────────────────┤
│  Context Usage  ████████████░░░░░░░░░░░░░░░░  42%           │
│                 (84,231 / 200,000 tokens)                   │
├─────────────────────────────────────────────────────────────┤
│  Time     Provider    Model                      Tokens     │
│  14:23:01 Anthropic   claude-sonnet-4-20250514   12,847     │
│  14:23:45 Anthropic   claude-sonnet-4-20250514   8,234      │
└─────────────────────────────────────────────────────────────┘

第二步：运行 LLM 工具

打开第二个终端窗口，根据你使用的工具选择对应的命令。Tokentap 会自动配置代理并拦截流量。

运行 Claude Code:

tokentap claude

运行 OpenAI Codex:

tokentap codex

运行 MiniMax 或其他兼容 OpenAI 接口的工具:

tokentap run --provider minimax python my_app.py

现在，回到第一个终端窗口，你将看到 Token 使用情况随着你的操作实时更新。会话结束时，工具会自动输出本次会话的总 Token 消耗统计。

自定义配置（可选）

如果需要修改代理端口或设置上下文上限，可以使用以下参数：

# 设置代理端口为 9090，上下文上限为 100,000 tokens
tokentap start --port 9090 --limit 100000