| name | token-counter |
| description | 使用 DeepSeek V3 BPE tokenizer 计算 token 数量，附带 Claude Code chars/N 粗略估算对比。
触发词："计算token"、"token数"、"token计数"、"统计token"、"token占用"、"提示词大小"、"prompt大小"。
用于计算 skill、agent、command、CLAUDE.md、hooks 等 Claude Code 配置文件占用的 token 数量。
|
| user-invocable | true |
| argument-hint | [文件或目录路径] |
Token Counter
计算 Claude Code 相关文件（skills、agents、commands、hooks、CLAUDE.md 等）的 token 占用。
Claude Code 的 Token 计算策略
Claude Code 源码中没有本地 tokenizer，采用三层回退策略：
| 优先级 | 方式 | 精度 |
|---|
| 1 | API countTokens() | 精确 |
| 2 | Haiku 发最小请求回退 | 精确（花一次 API 调用） |
| 3 | chars / 4（JSON: chars / 2） | 粗略 |
本工具使用 DeepSeek V3 BPE tokenizer 做本地计数（精度介于 1 和 3 之间），同时输出 Claude Code 风格的 chars/N 粗略估算供对比。
工具位置
claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py
前置依赖
pip3 install transformers
使用方式
1. 统计单个文件
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --file <文件路径>
2. 统计多个文件
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --files <文件1> <文件2> ...
3. 统计目录下所有文本文件
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --dir <目录路径>
4. 统计文本字符串
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --text "要计算的文本"
5. 从管道读取
echo "some text" | python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --stdin
输出字段说明
| 字段 | 含义 |
|---|
bpe | DeepSeek V3 BPE tokenizer 计算的 token 数 |
chars | 字符数 |
rough | Claude Code 风格的 chars/N 估算（括号内为与 bpe 的偏差百分比） |
ratio | bpe / chars，反映 token 密度 |
执行步骤
当用户要求计算 token 时：
-
明确统计范围 — 确定用户想统计哪些文件：
- 单个文件：
--file
- 某个 skill 目录：
--dir skills/<skill-name>
- 所有 skills：
--dir skills/
- 所有 agents：
--dir agents/
- CLAUDE.md 及其规则：
--files 列出
- 全部 Claude Code 配置：分别统计后汇总
-
执行命令 — 使用 Bash 工具运行 count_tokens.py
-
结果解读 — 向用户报告各文件 token 数、总占用、上下文窗口占比（按 200K 上下文估算）
常用统计场景
统计所有 skills
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --dir claude-code-tool/skills/
统计所有 agents
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --dir claude-code-tool/agents/
统计当前项目的 CLAUDE.md 及 rules
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --files CLAUDE.md .claude/rules/*.md
统计某个 skill 的完整内容
python3 claude-code-tool/custom-tools/deepseek_tokenizer/count_tokens.py --dir claude-code-tool/skills/<skill-name>/
精度说明
DeepSeek V3 BPE tokenizer（128K 词表）与 Claude 实际 tokenizer 有差异，但作为估算工具：
- 英文文本：误差通常在 5-10% 以内
- 中文文本：误差可能稍大，但趋势一致
- 主要用途是比较不同文件的相对大小，而非精确计量
rough 列展示 Claude Code 源码中 chars/N 估算与 BPE 计数的偏差
