核心用法
agent-usage-stats 是一款专注于本地AI Agent用量监控的轻量级工具。用户通过交互式菜单选择目标Agent（支持Hermes、Claude Code、CodeX、OpenClaw、Reasonix、DeepSeek TUI），即可即时查看Token消耗统计。支持命令行快速调用（如 token-stats -a hermes 跳过菜单）、实时监控模式（--watch）以及已安装Agent列表查询（--list-backends）。
工具采用纯Python标准库开发，安装后通过 python3 token-stats.py setup 完成配置，默认部署至 ~/.token-stats/ 目录。特别地，Hermes用户可在SKILL.md中配置 run: token-stats -a hermes，实现任务结束自动输出消耗报告的无缝集成。
显著优点
极致轻量与兼容性：零第三方依赖，仅依赖Python 3.11+标准库，彻底规避供应链攻击风险。支持跨平台运行（Windows原生/WSL2混合环境），通过智能检测自动适配不同Agent的数据存储路径。
隐私优先设计：所有数据处理严格本地化，无网络外发行为。直接读取各Agent的SQLite数据库（~/.hermes/state.db）或JSONL日志文件（~/.claude/projects/**/*.jsonl），用户完全掌控数据主权。
开发者友好：MIT开源协议，代码结构清晰（2,461行/19文件），支持Git与ClawHub双渠道更新。实时监控模式满足开发调试场景，导出功能便于后续分析与审计。
潜在缺点与局限性
生态覆盖有限：当前仅支持6款特定Agent，对Cursor、GitHub Copilot等主流工具暂无支持，多Agent并行用户需配合其他工具使用。
WSL环境依赖子进程：Windows环境下查询WSL内数据需调用 wsl.exe 子进程，虽参数经过转义验证，但存在潜在执行开销与兼容性边界情况。
PATH修改操作：安装/更新/卸载流程会修改用户PATH环境变量（Windows注册表或Shell配置文件），需用户理解并信任此行为。
来源验证待完善：GitHub仓库当前不可访问（404），虽通过ClawHub可信渠道分发，但缺乏公开仓库的社区审计与版本追溯机制。
适合的目标群体
- 多Agent重度用户：同时使用Hermes、Claude Code等多款工具，需统一监控Token消耗的开发者
- 成本敏感型团队：需精细化追踪AI调用成本、优化预算分配的技术管理者
- 隐私优先用户：拒绝云端同步、坚持数据本地化的安全意识较强群体
- 开源工具爱好者：倾向于轻量、透明、可审计的纯标准库解决方案
使用风险说明
性能风险：WSL环境下子进程调用可能引入毫秒级延迟，高频监控场景（--watch 短间隔轮询）建议直接使用原生Linux环境。
数据依赖风险：工具有效性取决于各Agent本地数据格式的稳定性。若目标Agent更新后变更存储结构，可能导致统计异常，需关注作者版本适配。
更新渠道风险：GitHub不可访问状态下，建议绑定ClawHub官方源（clawhub.ai/zhy/agent-usage-stats）并校验版本签名，避免从未知来源获取更新包。
权限风险：首次运行需读取 ~/.hermes、~/.claude 等敏感目录，建议审查代码确认无越界访问，并在隔离环境预演后再投入生产使用。