核心用法
costhq 是一款面向 AI Agent 工作流的会话成本追踪工具，通过本地 SQLite 数据库存储数据，提供完整的成本透明化方案。核心工作流遵循三步：
1. 启动会话：cs start "任务描述" --json --close-stale 创建追踪会话
2. 记录 AI 调用：每次 API 调用后执行 cs log-ai -p <provider> -m <model> --prompt-tokens <n> --completion-tokens <n> --json，支持 Anthropic、OpenAI、Google 等 17+ 内置模型自动计价
3. 结束会话：cs end -n "完成备注" --json 自动生成 Git 变更统计与成本汇总
工具提供 Web 仪表盘（cs dashboard），涵盖 KPI 概览、模型成本分析、文件热点图、多 Agent 成本归因等高级功能。支持 --agent 标签实现多 Agent 系统成本拆分，适合复杂 AI 流水线。
显著优点
- Agent 原生设计：所有命令支持
--json结构化输出，专为程序化 Agent 交互优化 - 零外部依赖：数据本地存储（
~/.CostHQ/sessions.db），无需云服务 - 精细成本追踪：内置 17+ 模型定价表，支持自动计算与自定义覆盖
- Git 深度集成：自动检测会话期间的文件变更与提交记录
- 预算管控：支持日/总会话/单会话三级预算阈值与告警
- 多 Agent 支持：
--agent标签实现成本归因，便于 A/B 测试与团队分摊
潜在局限
- 构建依赖：需 Node.js 18+ 及 C/C++ 工具链编译 SQLite 原生模块，Windows 环境配置较复杂
- 仅支持 Git 项目：会话作用域绑定 Git 根目录，非 Git 目录无法正常使用
- 本地单用户：无多用户协作或云端同步能力
- 仪表盘端口固定：默认 3737，冲突时需手动指定
- Pro 功能描述模糊："unlocked Pro architecture" 具体能力边界未明确
适合人群
- 高频使用 AI API（Claude、GPT-4o 等）的开发者与团队
- 需要精细化成本归因的多 Agent AI 系统架构师
- 追求数据主权、拒绝云服务的隐私敏感用户
- 需向客户/管理层汇报 AI 支出的咨询公司或企业技术负责人
常规风险
- 数据丢失风险：本地 SQLite 无自动备份，误删
~/.CostHQ/即丢失历史 - 会话泄露：
--close-stale参数使用不当可能导致异常会话残留 - 定价漂移：内置模型价格非实时同步，供应商调价后需手动更新
- JSON 模式陷阱：
--json模式下进程立即退出，开发者易误以为会话未创建 - 版本兼容性：
schemaVersion字段提示存在破坏性变更可能，需关注升级