TokenTrace

TokenTrace CLI

面向开发者和编码 Agent 的本地优先 AI CLI 使用情况分析工具。

TokenTrace 会在你开始下一次高成本 AI CLI 运行前，回答一个实际问题： 本地使用情况证据是否已准备就绪，值得信赖？它会扫描本地 Claude Code、Codex、 结构化使用情况日志和符合使用情况数据结构的本地数据库，然后将令牌和 成本数据标记为精确、估算、未知、缓存或非缓存。仪表板默认打开今日 页面，并可直接前往 Sessions、Evidence 和 Fix Data。

TokenTrace 首先面向本地开发机器设计，默认设置针对 macOS。它无需云账户，也不会向任何地方发送遥测数据或日志。

网站 · 源代码

TokenTrace 可以帮你做什么

• 使用 tokentrace preflight --json 或 MCP get_preflight，在下一次编码 Agent 运行前检查准备情况。
• 在首屏查看今日本地成本、令牌数、会话数、置信度、异常和修复信号。
• 将每个重要数值追溯到本地文件、解析器状态、会话、模型费率和置信度标签。
• 通过引导式修复队列补全缺失的成本数据，无需上传提示词或消息正文。

几秒钟即可开始

无需安装即可运行：

npx tokentrace

或全局安装：

npm install -g tokentrace
tokentrace

该命令会启动本地仪表板，选择从 3030 开始的可用 localhost 端口，打开默认浏览器，并持续运行服务，直到你按下 Ctrl+C。

CLI 命令：

tokentrace              # Start local dashboard
tokentrace serve        # Start local dashboard
tokentrace serve --port 3210 --no-open
                        # Start on a fixed port without opening a browser
tokentrace agent --json # Print machine-readable agent discovery manifest
tokentrace capabilities --json
                        # Alias for agent discovery manifest
tokentrace roadmap --json
                        # Print release status handoff
tokentrace mcp          # Start the local stdio MCP server
tokentrace scan         # Scan local AI CLI usage logs
tokentrace doctor --json
                        # Inspect scan health and repair recommendations
tokentrace preflight --json
                        # Check readiness before another coding-agent run
tokentrace evidence --json
                        # Print metric evidence trails as JSON
tokentrace repair --json
                        # Print unknown-cost repair groups as JSON
tokentrace digest --json
                        # Print current-month local usage digest
tokentrace digest --since yesterday
                        # Print a scoped local usage digest
tokentrace report --markdown
                        # Print a deterministic Markdown report
tokentrace review --json
                        # Print post-session scan and review movement
tokentrace insights --json
                        # Print local recommendations as JSON
tokentrace status --json
                        # Print local usage status as JSON
tokentrace statusline claude
                        # Render a Claude Code status line from stdin
tokentrace statusline claude --compact
                        # Render a shorter Claude Code status line
tokentrace statusline setup claude
                        # Print Claude Code statusLine setup JSON
tokentrace watch --session
                        # Watch local usage status in a terminal split
tokentrace watch --session --compact
                        # Watch a compact live status line
tokentrace pricing refresh
                        # Refresh public model prices
tokentrace run <cmd>    # Optional wrapper mode for command runtime diagnostics
tokentrace reset        # Reset imported local data
tokentrace reset --yes  # Reset without confirmation
tokentrace --help       # Print help
tokentrace --version    # Print version

面向编码 Agent

Agent 应从只读发现清单开始：

tokentrace agent --json

以下别名会返回相同的清单：

tokentrace capabilities --json

该清单介绍了 TokenTrace 的本地优先隐私模型、安全的 JSON 命令、常见工作流、Claude Code 状态栏设置、Codex sidecar 备用方案，以及相关防护措施，例如未经人工明确批准，绝不运行 tokentrace reset。发现命令不会扫描文件、初始化数据库或启动仪表板。

对于在调用命令前会检查仓库或 npm 包内容的 Agent，包中还包含以下 Agent 参考资料：

• TOKENTRACE_AGENT.md
• llms.txt
• docs/agent-adoption.md
• docs/agent-discovery.schema.json

支持 MCP 的客户端可在安装或使用 npm 包后启动本地 stdio 服务：

tokentrace mcp

注册表名称：io.github.abhiyoheswaran1/tokentrace。

Agent 的首次 MCP 调用：get_agent_guide。

无需扫描文件即可对本地 MCP 入口点进行自测：

tokentrace mcp selftest --json

MCP 服务通过工具提供相同的本地优先功能：能力、预检、状态、扫描健康度、证据、修复队列、报告，以及显式扫描工具。服务启动时不会扫描文件；扫描工具要求先设置 confirmLocalScan=true，才会读取本地使用情况文件或写入本地数据库。

开始下一次耗时较长的编码 Agent 运行前，请使用预检：

tokentrace preflight --json

在 MCP 客户端中，调用 get_preflight，即可根据本地扫描的新鲜度、置信度、防护措施、异常和修复结果，获得相同的继续、谨慎或阻止决定。预检不会扫描文件或检查原始提示词。

本地仪表板已运行时，Agent 可通过 localhost 获取同一份清单：

curl http://127.0.0.1:3030/api/agent
curl http://127.0.0.1:3030/api/capabilities

Local Sources & Trust 发布交接资料也提供机器可读格式：

tokentrace roadmap --json
curl http://127.0.0.1:3030/api/roadmap

从源代码运行

npm install
npm run db:migrate
npm run db:seed
npm run dev

打开 http://localhost:3000。

常用源代码命令：

npm run dev          # Start the Next.js dev server
npm run build        # Build the production app
npm run start        # Serve the production build
npm run scan         # Scan default and configured folders
npm run db:migrate   # Create/update local SQLite tables
npm run db:seed      # Seed editable provider/model prices
npm run screenshots:seed
                    # Seed a guarded public-safe screenshot database
npm run reset        # Clear imported data and scan history
npm test             # Run parser and cost tests
npm run verify       # Run Vitest, TypeScript, and ESLint checks
npm run package:test # Verify, build, and dry-run the npm package
npm run package:inspect
                    # Check package transparency guardrails
npm run security:ioc
                    # Scan lockfiles, workflows, and local AI-tool hooks for supply-chain IOCs
npm run smoke:packed
                    # Inspect packed tarball and smoke test packed CLI
tokentrace roadmap --json
                    # Inspect roadmap handoff, action recipes, and release status

日常循环与信任

TokenTrace 现在围绕日常循环组织产品：

1. 预检：在再次运行 Agent 前，判断本地证据是否已就绪。
2. 今日：查看成本、令牌、会话、置信度、异常和修复信号。
3. 证据：将数值追溯到源文件、解析器置信度、会话和模型费率状态。
4. 修复数据：解决未知成本、解析器审核和模型费率缺失问题。
5. 高级：需要完整诊断界面时，检查扫描健康状况、发现、解析器、原始数据、查询和模型费率。

信任功能包括：

• 原生结构化用量日志和 Cursor 风格的聊天导出导入
• 扫描健康状况中的源覆盖范围，显示原生、配置文件辅助、回退和 不支持的文件
• 以 JSON 或 Markdown 格式提供注重隐私的证据包
• 本地扫描计划：手动、打开时、每小时或每天
• 按项目／模型／工具设定的防护栏及警告阈值
• 保存匹配器前预览导入配置文件
• 已保存的报告导出，涵盖每周用量、源覆盖范围、防护栏、未知 成本、高成本会话和置信度趋势
• 导出运行元数据，不包含原始用量记录

准确性与证据

TokenTrace 会标注导入数值背后的可信度：

• 精确的提供商令牌计数
• 对可识别的 OpenAI/Codex 和 Claude 系列模型名称进行的分词器估算
• 仅有类文本内容时进行的简单估算
• 来自本地 SQLite 历史记录的源数据成本
• 缺少模型、令牌或费率证据时的未知成本修复组

仪表板会在今日、项目、会话和会话时间线页面显示数据置信度评分。扫描健康状况还包含供应链 IOC 检查，因此产品中会显示软件包可信度，而不只是在发布脚本中显示。

公开发布需要维护者批准。升级版本、打标签、创建 GitHub 发布或发布 npm 包之前，请参阅 docs/RELEASE_CHECKLIST.md。

在本地开发中，SQLite 数据库默认位于 .tokentrace/tokentrace.db。使用以下命令覆盖此设置：

TOKENTRACE_DB=/absolute/path/tokentrace.db npm run dev

数据位置

从 npm 安装后，TokenTrace 会将运行时数据存储在软件包文件夹之外：

• macOS：~/Library/Application Support/TokenTrace/
• Linux：~/.local/share/tokentrace/
• Windows：%APPDATA%/TokenTrace/

CLI 会自动设置 TOKENTRACE_DB 和 DATABASE_URL。你可以使用以下命令覆盖基础目录：

TOKENTRACE_HOME=/custom/path tokentrace

TokenTrace 的查找位置

默认情况下，发现功能会检查以下位置（如果存在）：

• ~/.claude/
• ~/.config/claude/
• ~/.codex/
• ~/.config/codex/
• ~/.openai/
• 项目级隐藏文件夹，例如运行 tokentrace 的目录中的 .claude、.codex、.openai 和 .ai
• 本地应用数据目录中的 TokenTrace 封装日志
• 设置中配置的任何自定义文件夹

使用设置添加自定义文件夹、切换原始消息存储，并触发扫描。使用扫描健康状况、发现、解析器和原始数据，检查发现的文件、解析器判定、警告、失败、提取的元数据和置信度。

设置还支持可选的本地月度用量防护栏。设置成本上限、令牌上限，或同时设置两者，今日页面便会显示根据导入的本地 CLI 用量计算的本月至今进度。

会话页面内置了适用于重复审核流程的视图，也支持本地保存的视图：未知成本、高成本会话、本月 Claude/Codex、估算令牌、防护栏审核和解析器审核。打开会话的时间线链接，可查看按顺序排列的交互、模型变更、令牌激增、缓存活动、工具调用、解析器置信度和未知成本事件。原始提示词和消息正文默认保持隐藏。

数据摄取架构

TokenTrace 的主要数据摄取架构是直接从本地文件系统摄取：

1. 查找本地 AI CLI 产物。
2. 通过适配器解析支持的格式。
3. 规范化会话、交互、令牌用量、模型、项目和工具调用。
4. 将规范化记录存储在本地 SQLite 中。
5. 在本地仪表板中可视化分析结果。

TokenTrace 不使用 MITM 代理、数据包嗅探、浏览器扩展、流量拦截或云端遥测。

每个适配器都会检测兼容性、尽可能解析部分元数据，并在遇到不支持的文件格式时安全地失败。导入的交互会附带令牌置信度元数据：

• exact
• high-confidence estimate
• low-confidence estimate
• unknown

精确值和估算值不会在不作说明的情况下混用。

可选包装器模式

文件系统数据摄取是主要产品路径。包装器模式是次要且可选的：

tokentrace run claude-code
tokentrace run codex
tokentrace run npm test

包装器模式会启动子进程、测量运行时长、统计 stdout/stderr 字节数、在可用时检测结构化 JSON 输出，并在应用数据目录下写入本地 JSONL 诊断日志。它不会拦截网络流量。

Claude Code 状态栏

Claude Code 可以在其终端 UI 底部运行本地状态栏命令。TokenTrace 直接支持此方式：

tokentrace statusline setup claude

将打印出的 statusLine 块添加到 ~/.claude/settings.json。它会将 Claude Code 指向：

tokentrace statusline claude

Claude Code 会通过 stdin 将会话 JSON 发送给该命令。TokenTrace 会读取转录路径、模型、上下文用量和会话成本，然后输出一行简洁的本地状态信息：

TokenTrace | Opus | ctx 7% | cost $0.1235 | processed 3.3K tokens | cache 2.0K | priced

不要将 Claude Code 的 statusLine.command 设置为纯 tokentrace。纯 tokentrace 会启动仪表板，而 tokentrace statusline claude 只会打印一条状态栏响应。

你也可以在 Claude Code 外部查看相同的本地状态：

tokentrace status --json
tokentrace watch --session

每日报告命令保持确定性，并仅在本地运行：

tokentrace digest --since last-scan
tokentrace digest --since 2026-05-01 --json
tokentrace report --markdown --since yesterday
tokentrace review --json

Codex CLI 状态栏集成暂缓推出，直到其状态栏和钩子约定足够稳定，可以在不依赖脆弱的终端输出解析的情况下提供支持。目前的替代方案是在终端分屏或 tmux 窗格中使用 tokentrace watch --session --compact。请参阅 docs/CODEX_INTEGRATION_SPIKE.md 了解当前决定。

截图

仪表板视图：

CLI 启动和帮助信息：

本地扫描输出：

可选包装器诊断：

隐私模型

• 所有处理都在你的计算机本地运行。
• 不包含外部遥测。CLI 会禁用 Next.js 遥测。
• 无需云端账户。
• 默认不存储完整的原始提示词和回复。
• TokenTrace 会存储简短的文本预览，用于调试和提供分析上下文。
• TokenTrace 可能会下载公开的模型定价清单，以便费用估算保持实用。发送该请求时，不会附带使用日志、提示词、文件路径或分析数据。设置 TOKENTRACE_DISABLE_PRICE_REFRESH=1 即可仅使用内置价格。
• 只有在你希望将完整的本地消息文本保存在 SQLite 中时，才在 Settings 中启用 Store raw message content。

在运行 tokentrace 的终端中按 Ctrl+C 停止服务。

软件包可信度

• TokenTrace npm 软件包没有 preinstall、install 或 postinstall 脚本。
• 发布的软件包包含可读的应用程序源代码和编译后的 CLI 运行时，不包含生成的 .next/server 路由包。
• 首次需要时，tokentrace serve 会在用户的 TokenTrace 应用数据目录中准备本地仪表板构建产物。
• 如果生成的 Next.js 构建产物出现在已发布的 tarball 中，npm run package:inspect 就会失败。
• npm run security:ioc 会扫描锁文件、工作流以及本地 Claude/VS Code Hook 文件，以查找高可信度的供应链入侵迹象。
• 公开发布到 npm 通过 GitHub Actions Trusted Publishing 配置，并使用版本标签生成来源证明。
• 除了 npm audit --audit-level=moderate，Socket GitHub 检查和 ProjScan 也作为发布防护措施。
• 如果某个门禁命令以非零状态退出，npm run release:check 就会失败。导入图应避免循环依赖；tests/import-boundaries.test.ts 可防止共享类型/辅助模块导入更高层的编排汇总模块。
• 发布说明会直接从相应的变更日志部分发布到 GitHub Releases，而不是仅提供链接的摘要。

完整的安全和隐私模型请参阅 SECURITY.md。

模型费率

模型价格会变动。TokenTrace 内置公开标价，并可从公开的 TokenTrace 模型费率清单刷新价格。在 Model Rates 中手动进行的修改会在后续刷新时保留。

内置目录包含常用的 OpenAI、Anthropic、Google Gemini、xAI、DeepSeek、Mistral 和 Cohere 模型，价格核验日期为 2026 年 5 月 8 日。

初始数据来源：

• OpenAI API 定价 和 OpenAI 模型文档
• Anthropic Claude 定价
• Gemini Developer API 定价
• xAI 模型和定价
• DeepSeek 模型和定价
• Mistral 模型文档
• Cohere 定价

在将成本估算视为财务依据之前，请先在 Model Rates 中检查并更新费率；尤其是在使用批处理、优先级/灵活模式、数据驻留、长上下文附加费用、订阅或特定于提供商的折扣时。

可通过仪表板或 CLI 刷新：

tokentrace pricing refresh

费用按每次交互计算：

inputTokens * inputPricePer1M / 1,000,000
+ outputTokens * outputPricePer1M / 1,000,000
+ cacheReadTokens * cachedInputPricePer1M / 1,000,000
+ cacheWriteTokens * cacheWritePricePer1M / 1,000,000

如果模型没有单独的缓存费率，缓存读取和缓存写入价格将回退为输入价格。Anthropic 初始数据行默认使用 5 分钟提示词缓存写入价格。根据令牌可用性和定价配置，数据行会标记为精确、估算或未知。

支持的输入

适配器位于 src/ingestion/adapters/ 下：

• claude-code.ts
• codex-cli.ts
• structured-usage-log.ts
• cursor-chat.ts
• sqlite-history.ts
• generic-jsonl.ts
• generic-json.ts
• generic-log.ts

Claude Code 和 Codex CLI 的格式可能因版本而异，因此这些适配器采用防御性处理，并尽力兼容。遇到未知文件时会安全失败，并在 Raw Data 页面显示警告。

支持矩阵

TokenTrace 保持清晰可见的支持承诺，让日常扫描更值得信赖：

范围	支持级别	说明
Claude Code 项目记录	稳定	主要的本地 CLI 导入来源。
Codex CLI 会话文件	尽力支持	在 CLI 格式不断演进时进行稳健解析。
结构化用量 JSONL/NDJSON	稳定	本地包装器和团队日志，包含会话、模型、令牌和来源成本字段。
Cursor 风格的聊天导出	尽力支持	导入本地编辑器聊天／编写器导出内容，默认不存储原始提示词文本。
用量格式的 SQLite 历史记录	尽力支持	读取包含会话、模型、令牌或类似成本列的本地数据库。
通用 JSONL、JSON 和文本日志	尽力支持	仅处理符合用量格式的保守记录。
Claude/Codex 缓存、插件、待办事项、配置和支持文件	忽略	将其标记为非用量文件，而非解析失败。
可编辑的模型定价	稳定	本地定价行用于计算成本和处理未知成本修复队列。
Claude Code 状态栏	稳定	使用 Claude Code 文档规定的 statusLine 标准输入约定。
Codex 固定状态栏	尽力提供备用方案	在分屏或 tmux 面板中使用 tokentrace watch --session --compact。
桌面应用抓取、浏览器扩展、代理转发、数据包捕获、遥测	不支持	不属于 TokenTrace 的产品边界。

扩展解析器

通用 JSONL 示例文件位于 fixtures/generic-jsonl/。

导入系统采用可插拔设计：

1. 添加一个实现 IngestionAdapter 的适配器。
2. 在 src/ingestion/adapters/index.ts 中注册该适配器。
3. 在 tests/ 下添加解析器测试。

参与贡献

欢迎贡献。有关本地设置、解析器指南、定价更新说明和发布政策，请参阅 CONTRIBUTING.md。

故障排除

安装期间出现 prebuild-install 弃用警告

npm warn deprecated [email protected]: No longer maintained...

这是 better-sqlite3 的传递依赖（TokenTrace 用于存储本地数据的原生 SQLite 驱动程序）。此警告无害——安装会正常完成，TokenTrace 也会按预期运行。待 better-sqlite3 上游迁移到其他预编译二进制加载器后，警告便会消失；TokenTrace 方面无需进行任何修复。

better-sqlite3 原生构建错误

如果无法下载预编译二进制文件（例如机器离线、代理限制严格或 Node ABI 不受支持），better-sqlite3 会尝试从源代码编译，但可能失败。可尝试以下解决办法：

• 确保使用受支持的 Node.js LTS 版本（TokenTrace 要求 >= 20.0.0；建议使用 Node 20 或 22 LTS）。
• 安装构建工具：macOS 上安装 Xcode Command Line Tools，Linux 上安装 build-essential 和 python3，Windows 上安装“使用 C++ 的桌面开发”工作负载。
• 在可访问网络的情况下重试安装，以便从 github.com 获取预编译二进制文件。

EBADENGINE 警告

本地 Node 版本低于某个传递依赖的 engines 字段要求时，就会出现此类警告。这些是警告，不是错误。升级到最新的 Node LTS 即可解决。

已知限制

• Claude Code 和 Codex CLI 日志格式是通过稳健推断得出的，可能需要根据真实样例日志进行调整。
• 对于可识别的 OpenAI/Codex 和 Claude 系列模型名称，可使用基于分词器的估算。无法识别的纯文本记录仍会采用保守的简单估算。
• SQLite 历史记录导入需要本地表符合用量数据格式；对于不包含会话、模型、令牌或类似成本字段的任意数据库，会跳过处理。
• 初始价格可编辑，应根据你的账户、地区和提供商方案手动核实。

许可证

由 Abhi Yoheswaran 开源。基于 MIT 许可证发布。请参阅 LICENSE。

后续改进

• 为更多本地 AI 工具和编辑器历史记录扩展一流的原生适配器。
• 当公开的分词器行为足够稳定、可以明确标注时，针对特定提供方改进分词器。
• 为使用自定义包装器日志的团队增强 Import Profile 预览的交互性。
• 在扫描超大型本地文件夹时，将扫描进度实时传输到 UI。