核心用法
codesession-cli 是一款专为 AI 编码代理设计的开源会话成本追踪工具，支持 Claude Code、Codex、Cursor、Windsurf、Cline 等主流 AI 代理。通过 cs 命令行工具，开发者可在任务开始时创建会话，每次 AI API 调用后记录 Token 消耗与成本，任务结束时自动生成完整报告。
工作流程：
1. cs start "任务描述" --json --close-stale — 启动追踪会话
2. cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json — 记录每次 AI 调用
3. cs status --json — 实时检查当前消耗
4. cs end -n "完成备注" --json — 结束会话并生成摘要
5. cs dashboard — 浏览器打开可视化仪表盘分析历史数据
特色功能：
- 自动定价：内置 21+ 模型价格表（含最新 Codex 系列），支持自定义覆盖
- 预算管控：可设置日/总会话/单会话成本阈值，超限触发声音+浏览器通知
- 多代理追踪：
--agent参数标记不同代理，便于 A/B 测试与成本归因 - Git 集成：自动扫描会话期间文件变更与提交记录
- 本地优先：SQLite 数据库存储于
~/.codesession/，无需云服务
显著优点
| 维度 | 优势 |
|------|------|
| **生态兼容** | 支持 OpenAI、Anthropic、Google、Mistral、DeepSeek 等主流提供商 |
| **代理友好** | 所有命令支持 `--json` 结构化输出，专为自动化工作流设计 |
| **零侵入** | 不修改现有工具链，纯旁路追踪 |
| **可视化** | 本地 Web 仪表盘提供 KPI、趋势预测、文件热点等多维分析 |
| **可恢复性** | `--resume` 与 `cs recover` 应对崩溃场景，避免数据丢失 |
潜在局限
- Node.js 依赖：需 Node 18+ 及 C/C++ 构建工具（Windows 需 Visual Studio Build Tools）
- SQLite 编译：首次安装需编译原生模块，Alpine 等精简系统需额外依赖
- 手动集成：非自动钩子，需在代码中显式调用
cs log-ai记录每次 API 调用 - 本地单用户：当前版本未内置多用户/团队共享功能
- 模型定价滞后：新增模型需手动更新定价表或指定成本
适合人群
- AI 编码代理开发者：需精确追踪多步骤任务成本的团队
- 个人开发者：使用 Claude Code、Cursor 等工具，希望管控月度 AI 支出
- 多代理系统架构师：通过
--agent标签实现成本归因与效率分析 - 预算敏感团队：需要硬预算限制与告警机制的企业用户
常规风险
| 风险类别 | 说明 | 缓解措施 |
|----------|------|----------|
| **数据隐私** | 会话数据本地存储，但含文件路径、Git 提交信息等元数据 | 避免在共享环境记录敏感项目路径；定期清理 `~/.codesession/` |
| **预算误判** | 定价表延迟更新或手动成本输入错误导致预算计算偏差 | 定期执行 `cs pricing list` 核对；关键操作前人工复核 `aiCost` |
| **会话泄露** | 崩溃后未关闭的会话可能混淆后续任务成本归属 | 始终使用 `--close-stale`；配置 `cs recover --max-age` 自动清理 |
| **供应链** | npm 包依赖大量 Node 原生模块，存在供应链攻击面 | 锁定版本安装；审查 `package.json` 依赖变更 |
---
项目活跃维护（v2.4.0），GitHub 开源，适合纳入 CI/CD 成本管控体系。