agenttrace logo

AgentTrace

本地优先的 TUI 和报告工具，用来分析 AI 编程 Agent 会话历史、成本、Token、耗时和慢任务原因。

English | 简体中文

CI Site Release Rust License Homebrew tap

agenttrace running locally against real AI coding agent session logs

--- **agenttrace** 是一个本地优先的终端 TUI 和报告生成工具，用来分析 AI 编程 Agent 的会话历史。它会读取 Claude Code、Codex CLI、Gemini CLI、Qwen Code、Cline、Aider、Cursor exports、Hermes Agent、OpenCode、OpenClaw、Pi、Oh My Pi、Kimi CLI、Copilot-style logs 和通用 JSON/JSONL traces，主要帮你做两件事：汇总多个 Agent 历史会话的成本、Token 和耗时；定位某次任务为什么跑得慢。 CLI 和 TUI 来自同一个 `agenttrace` 二进制：不带报告动作时进入 TUI，传入 `--sessions`、`--overview` 等参数时输出 CLI 报告。 ## 为什么需要 agenttrace？ AI 编程 Agent 越来越像一套小型构建系统：会调用工具、重试、卡住、花 token，但你最后往往只看到一段总结。 **agenttrace** 读取这些 Agent 已经写在本机的日志，把最贵、最慢、最值得看的会话排到前面。 它能帮你回答： - **Agent 花了多少？** 按来源、模型、input/output/cache token、估算成本和真实耗时对比历史会话。 - **任务为什么慢？** 发现长时间空档、挂起会话、重试循环、慢工具调用、大参数和上下文压力。 - **这次有没有退化？** 在提供本地 baseline 时对比回归，再从报告里查看 incident timeline 和保守的 tool authority 分类。 - **先看哪一次？** 按成本、耗时、轮次、健康分、失败、异常、模型、来源或文本搜索排序。 - **能不能本地看？** 所有分析都在本机完成，不需要上传 prompt、代码和日志。 ## 真实本机运行 以下截图和数字来自为 v0.6.0 源码树采集的最新 500 条真实本机会话脱敏样本，不是当前遥测数据，也不是测试 fixture。 ```bash agenttrace ``` | 概览 | Critical 会话 | |---|---| | agenttrace overview showing real local AI coding agent sessions, token cost, errors, and health | agenttrace critical session list from real local AI coding agent logs | | 会话详情 | 诊断 | |---|---| | agenttrace detail view showing health, cost, tool failures, and next action from a real local session | agenttrace diagnostics view showing latency, context window, and large parameter calls from real local logs | ## 安装 以下命令安装当前公开渠道版本；在 v0.6.0 Release 资产和 Homebrew Formula 发布前，它们可能落后于 v0.6.0 源码树。可用 `agenttrace --version` 检查实际版本； 如需体验当前源码树，请使用下面的 Git Cargo 安装命令。 ```bash curl -sL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh | sh ``` 其它安装方式： ```bash brew install luoyuctl/tap/agenttrace cargo install --git https://github.com/luoyuctl/agenttrace agenttrace ``` Windows： ```powershell iwr -useb https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.ps1 | iex ``` ## Quickstart ```bash agenttrace ``` ## 你会得到什么 | 需求 | agenttrace 提供 | |---|---| | 历史消耗总览 | 跨 Agent 会话聚合，展示 token 总量、模型价格、估算成本和真实耗时 | | 数据可信度 | 展示解析跳过、缓存命中、未知来源/模型、价格回退和字段覆盖率 | | 能力降级 | 每个会话标记为 `Detailed`、`Aggregate` 或 `Limited`，不把缺失的事件证据包装成完整 Trace | | 脱敏步骤 | 来源提供调用 ID 和时间戳时展示 Tool Step 元数据和耗时，不在 Step 中保存 prompt、回复、结果或工具参数正文 | | 慢任务诊断 | 延迟统计、长间隔、挂起会话、重试循环、慢工具、大参数和上下文压力 | | 回归证据 | 在提供本地 baseline 时进行对比，并在报告中展示 incident timeline 和保守的 tool authority 分类 | | 优先级排序 | 按成本、耗时、轮次、健康分、失败、异常、模型、来源或文本搜索筛选 | | 可分享证据 | JSON、Markdown 和独立 HTML 报告 | ## 文档 - 官网：https://luoyuctl.github.io/agenttrace/ - AI Agent 可观测性指南：https://luoyuctl.github.io/agenttrace/ai-agent-observability.html - 示例 HTML 报告：https://luoyuctl.github.io/agenttrace/demo-report.html - CI 集成：[docs/ci-integration.md](docs/ci-integration.md) - Cursor 导入：[docs/cursor-import.md](docs/cursor-import.md) - Parser 指南：[docs/parser-guide.md](docs/parser-guide.md) - 发布说明草案：[docs/launch-kit.md](docs/launch-kit.md) agenttrace 已被这些项目收录： - [awesome-mac](https://github.com/jaywcjlove/awesome-mac) - [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) - [awesome-claude-skills](https://github.com/BehiSecc/awesome-claude-skills) ## 贡献 欢迎提交 Parser PR。一个好的 parser 贡献通常包含： - 一个很小的脱敏 fixture 或合成样本 - `crates/agenttrace-core/src/parser.rs` 中的格式识别 - role、timestamp、model、token usage、tool call、tool error 提取 - 成功解析和坏输入的测试 生成式 fixture 使用确定性脚本维护： ```bash python3 scripts/generate-testdata.py python3 scripts/generate-testdata.py --check ``` 提交 PR 前请运行： ```bash cargo test python3 scripts/generate-testdata.py --check cargo build --release -p agenttrace target/release/agenttrace --doctor ``` 完整贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE) © 2026 agenttrace contributors