用途
sidegrade 解决的是编码智能体使用成本不透明的问题。它读取你本机已有的 Claude Code、Codex、Hermes 和 OpenCode 会话日志，分析你的实际 token 使用结构，然后告诉你：在保持同等智能水平的前提下，哪个模型更便宜；以及哪个更便宜的档位值得小幅降级使用。
主要能力
- 读取本地编码智能体会话日志，提取 token 计数。
- 基于 Artificial Analysis Intelligence Index 为每个候选模型评分（取整到最接近的整数）。
- 按你实际的 token 组合（输出、新输入、缓存读取等）对每个模型重新计价。
- 输出报告，按智能水平和价格排序，不偏向任何提供商——某一行胜出仅因为该模型在该来源最便宜。
- 支持通过
npx sidegrade --json输出 JSON，便于在编码智能体会话中让智能体自行推理结果。
使用方式
无需安装、无需账号、无需配置。直接运行：
npx sidegrade
也可以在你的编码智能体（Claude Code、Codex、Cursor 等）中直接粘贴指令，让它运行 sidegrade 并告诉你该怎么做，无需终端。
运行后会基于你的实际使用情况生成报告。官方示例中的数字仅为示意，实际报告反映你自己的机器数据。
支持的智能体
- Claude Code — 读取
~/.claude/projects - Codex — 读取
~/.codex/sessions - Hermes — 读取
~/.hermes/state.db中的session_model_usage（通过系统 sqlite3 读取；已用真实数据验证并有 fixture 测试覆盖；若 sqlite3 不可用则跳过） - OpenCode — 读取
~/.local/share/opencode（读取storage/session/message；匹配 v1.18.x 消息 schema，并有 fixture 测试覆盖）
添加其他智能体只需在 src/parse.js 中写一个小的只读解析器，欢迎提交 PR。
数据来源
- 智能评分：Artificial Analysis Intelligence Index（https://artificialanalysis.ai），取整后存放在
data/models.json。 - 价格：每个提供商一个文件，位于
data/providers/，每个文件标注其公开定价页面的链接。部分最便宜的报价来自 QuickSilver Pro，一个 OpenAI 兼容网关。
隐私与限制
- 100% 本地运行，仅从智能体自身日志文件读取 token 计数。
- 运行时无网络调用；价格和智能评分已打包在包内。唯一的网络访问是 npm / npx 获取 sidegrade 本身。
- 无遥测、无账号、运行无需 API 密钥。
- 只读：你的提示词、代码、文件路径和补全内容永远不会离开你的机器。
- 零运行时依赖，整个工具只有几个小文件，几分钟即可读完。
适用场景
适合使用 Claude Code、Codex、Hermes 或 OpenCode 的开发者，希望在不牺牲智能水平的前提下降低模型调用成本，或评估是否值得切换到更便宜的模型档位。也适合在编码智能体会话中直接调用，让智能体基于 JSON 结果给出建议。
提供商参与
如果你运行推理服务，可以在约 2 分钟内添加价格：新增一个文件 data/providers/<you>.json，列出你的模型和公开价格，然后提交 PR。CI 会自动验证。模板见 CONTRIBUTING.md，或通过“Add / update a provider”表单提交 issue。
