Skip to content
Back to search

agenttrace

Local-first Rust TUI/CLI for auditing AI coding-agent sessions: cost, tokens, latency, failures, and health|本地优先 Rust TUI/CLI,审计 AI 编程 Agent 会话的成本、Token、延迟、失败与健康度

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/luoyuctl/agenttrace with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/luoyuctl/agenttrace'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/luoyuctl--agenttrace/badge.svg)](/listings/luoyuctl--agenttrace)

HTML

<a href="/listings/luoyuctl--agenttrace"><img src="/api/listings/luoyuctl--agenttrace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.ps1 | iex

The install scripts download the release binary for your platform, verify its SHA-256 against the published checksum, and add the install directory to your PATH (`~/.local/bin`, or `%LOCALAPPDATA%\agenttrace` on Windows). Set `AGENTTRACE_VERSION=v0.9.1` (or `-Version v0.9.1` in PowerShell) to pin a release.

Package managers:

# macOS and Linux
brew install luoyuctl/tap/agenttrace

# macOS, Linux, and Windows (requires Node.js 18+)
npm install -g @zack78/agenttrace

# From source
cargo install --git https://github.com/luoyuctl/agenttrace agenttrace

Check the installed version with `agenttrace --version`.

Update

| Installed with | Update command | | --- | --- | | Install script | `agenttrace update` (`--check` to only look) | | Homebrew | `brew upgrade luoyuctl/tap/agenttrace` | | npm | `npm install -g @zack78/agenttrace@latest` | | cargo | `cargo install --git https://github.com/luoyuctl/agenttrace agenttrace --force` |

`agenttrace update` verifies the release checksum before replacing the binary, and points package-manager installs back to their manager.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo-icon.png" alt="agenttrace logo" width="256" height="256">
  3. </p>
  4. <h1 align="center">AgentTrace</h1>
  5. <p align="center">
  6. Local-first TUI and reports for AI coding-agent session history, cost, tokens, time, and slow-run diagnosis.
  7. </p>
  8. <p align="center">
  9. English | <a href="README.zh-CN.md">简体中文</a>
  10. </p>
  11. <p align="center">
  12. <a href="https://github.com/luoyuctl/agenttrace/actions/workflows/ci.yml"><img src="https://github.com/luoyuctl/agenttrace/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  13. <a href="https://codecov.io/gh/luoyuctl/agenttrace"><img src="https://codecov.io/gh/luoyuctl/agenttrace/graph/badge.svg" alt="Coverage"></a>
  14. <a href="https://scorecard.dev/viewer/?uri=github.com/luoyuctl/agenttrace"><img src="https://api.scorecard.dev/projects/github.com/luoyuctl/agenttrace/badge" alt="OpenSSF Scorecard"></a>
  15. <a href="https://github.com/luoyuctl/agenttrace/releases/latest"><img src="https://img.shields.io/github/v/release/luoyuctl/agenttrace?color=00ADD8" alt="Release"></a>
  16. <img src="https://img.shields.io/badge/Rust-stable-f74c00.svg" alt="Rust">
  17. <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
  18. <a href="https://github.com/luoyuctl/homebrew-tap"><img src="https://img.shields.io/badge/Homebrew-tap-2bbc8a.svg" alt="Homebrew tap"></a>
  19. <a href="https://www.npmjs.com/package/@zack78/agenttrace"><img src="https://img.shields.io/npm/v/@zack78/agenttrace?label=npm" alt="npm"></a>
  20. </p>
  21. <p align="center">
  22. <img src="assets/readme-real-run.gif" alt="agenttrace running locally against real AI coding agent session logs" width="100%">
  23. </p>
  24. ---
  25. **agenttrace** is a local-first terminal TUI and report generator for AI coding-agent session history. It reads Claude Code, Codex CLI, Qwen Code, Cline, Aider, Cursor exports, Hermes Agent, OpenCode, OpenClaw, Pi, Oh My Pi, Kimi CLI, Copilot-style logs, and generic JSON/JSONL traces, then helps with two daily jobs: see what multiple agents spent across cost, tokens, and time; and diagnose why a task ran slowly.
  26. One `agenttrace` binary provides both interfaces: run it without a report action to open the TUI, or pass flags such as `--sessions` and `--overview` for CLI output.
  27. ## Why agenttrace?
  28. AI coding agents now behave like small build systems: they call tools, retry, stall, and spend tokens while you only see the final answer.
  29. **agenttrace** reads the logs your agents already write and puts cost-heavy or slow sessions first.
  30. It helps you answer:
  31. - **What did my agents spend?** Compare historical sessions by agent source, model, input/output/cache tokens, estimated cost, and wall-clock time.
  32. - **Why was this task slow?** Catch long gaps, hanging sessions, retry loops, slow tool calls, large parameters, and context pressure.
  33. - **Did a run regress?** Compare against a local baseline when supplied, then inspect incident timelines and conservative tool authority categories in reports.
  34. - **What should I inspect first?** Rank sessions by cost, duration, turns, health, failures, anomalies, model, source, or text search.
  35. - **Can I inspect this privately?** Everything runs locally; prompts, code, and logs do not need to leave your machine.
  36. ## Real local run
  37. ```bash
  38. agenttrace
  39. ```
  40. | Overview | Critical sessions |
  41. |---|---|
  42. | <img src="assets/readme-real-overview.png" alt="agenttrace overview showing real local AI coding agent sessions, token cost, errors, and health" width="100%"> | <img src="assets/readme-real-critical.png" alt="agenttrace critical session list from real local AI coding agent logs" width="100%"> |
  43. | Session detail | Diagnostics |
  44. |---|---|
  45. | <img src="assets/readme-real-detail.png" alt="agenttrace detail view showing health, cost, tool failures, and next action from a real local session" width="100%"> | <img src="assets/readme-real-diagnostics.png" alt="agenttrace diagnostics view showing latency, context window, and large parameter calls from real local logs" width="100%"> |
  46. ## Install
  47. macOS and Linux:
  48. ```bash
  49. curl -fsSL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh | sh
  50. ```
  51. Windows PowerShell:
  52. ```powershell
  53. irm https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.ps1 | iex
  54. ```
  55. The install scripts download the release binary for your platform, verify its
  56. SHA-256 against the published checksum, and add the install directory to your
  57. PATH (`~/.local/bin`, or `%LOCALAPPDATA%\agenttrace` on Windows). To pin a
  58. release, set `AGENTTRACE_VERSION`:
  59. ```bash
  60. curl -fsSL https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.sh | AGENTTRACE_VERSION=v0.9.1 sh
  61. ```
  62. ```powershell
  63. $env:AGENTTRACE_VERSION = "v0.9.1"; irm https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.ps1 | iex
  64. ```
  65. Package managers:
  66. ```bash
  67. # macOS and Linux
  68. brew install luoyuctl/tap/agenttrace
  69. # macOS, Linux, and Windows (requires Node.js 18+)
  70. npm install -g @zack78/agenttrace
  71. # From source
  72. cargo install --git https://github.com/luoyuctl/agenttrace agenttrace
  73. ```
  74. Check the installed version with `agenttrace --version`.
  75. ### Update
  76. | Installed with | Update command |
  77. | --- | --- |
  78. | Install script | `agenttrace update` (`--check` to only look) |
  79. | Homebrew | `brew upgrade luoyuctl/tap/agenttrace` |
  80. | npm | `npm install -g @zack78/agenttrace@latest` |
  81. | cargo | `cargo install --git https://github.com/luoyuctl/agenttrace agenttrace --force` |
  82. `agenttrace update` verifies the release checksum before replacing the binary,
  83. and points package-manager installs back to their manager.
  84. ## Quickstart
  85. ```bash
  86. agenttrace
  87. ```
  88. Reports, help, and errors follow `--lang en|zh` (default `en`; the TUI also
  89. remembers the language you toggle with `L`). Machine-readable fields such as
  90. JSON keys, codes, and the `--sessions` TSV header always stay English.
  91. ```bash
  92. agenttrace --overview --lang zh
  93. ```
  94. ### Governance reports
  95. ```bash
  96. # Audit raw token components, normalized pricing, and fallback confidence.
  97. agenttrace --audit --range 30d -f json
  98. # Optional local model aliases and per-million-token price overrides.
  99. AGENTTRACE_PRICING_FILE=pricing-overrides.json agenttrace --audit -f json
  100. # Rank evidence-backed actions by severity and estimated impact.
  101. agenttrace --recommend --range 30d -f json
  102. # Inspect observed MCP invocations. Loaded-server coverage is intentionally
  103. # reported as unavailable unless the source log actually records it.
  104. agenttrace --mcp-governance --range 30d -f json
  105. # Review cross-session context, cache, repeat-read, and read/write trends.
  106. agenttrace --context-trends --range 30d -f json
  107. # Correlate local Git commit timestamps with sessions (heuristic, read-only).
  108. agenttrace --delivery-evidence --range 30d -f json
  109. ```
  110. `pricing-overrides.json` accepts `aliases` plus per-million-token `prices`:
  111. ```json
  112. {"aliases":{"provider/raw-model":"my-model"},"prices":{"my-model":{"input":1,"output":2,"cw":0,"cr":0}}}
  113. ```
  114. `--overview` now includes scope, parse and pricing confidence, cost audit,
  115. prioritized recommendations, MCP governance, context trends, and delivery
  116. signals in JSON, Markdown, and HTML output. All cost and delivery fields are
  117. explicitly estimates or heuristics; they are not provider billing or proof that
  118. a commit reached `main`.
  119. ## What you get
  120. | Need | agenttrace gives you |
  121. | --- | --- |
  122. | Historical spend review | Sessions grouped across projects, agents, and models with Today/7d/30d/All ranges |
  123. | Data confidence | Report scope, per-source coverage, parse skips, cache hits, unknown sources/models, pricing fallbacks, and latest observed session |
  124. | Cost audit and action plan | Token component rates, pricing source/status, estimated cost confidence, and prioritized, evidence-backed remediation suggestions |
  125. | Governance trends | Canonical project grouping, observed MCP invocation governance, cross-session context/cache/read-write trends, and read-only Git delivery correlation |
  126. | Honest capability levels | `Detailed`, `Aggregate`, or `Limited` per session so missing event-level evidence is never presented as a complete trace |
  127. | Privacy-safe steps | Tool-step metadata and duration when the source provides call IDs and timestamps; no prompt, response, result, or tool-argument body is stored in steps |
  128. | Slow-task diagnosis | Latency stats, long gaps, hanging sessions, retry loops, slow tools, large params, and context pressure |
  129. | Regression evidence | Local baseline comparison when supplied, incident timelines, and conservative tool authority categories in reports |
  130. | First-session triage | Sort and filter by cost, duration, health, failures, anomalies, model, source, or text search |
  131. | Shareable evidence | JSON, Markdown, and self-contained HTML reports |
  132. | Local-first inspection | No hosted backend required |
  133. ## Docs
  134. - Documentation index: [docs/README.md](docs/README.md)
  135. - CI setup: [docs/guides/ci-integration.md](docs/guides/ci-integration.md)
  136. - Governance reports: [docs/guides/governance-reports.md](docs/guides/governance-reports.md)
  137. - Usage over time (daily/weekly/monthly, 5-hour blocks): [docs/guides/usage-over-time.md](docs/guides/usage-over-time.md)
  138. - Cursor import: [docs/guides/cursor-import.md](docs/guides/cursor-import.md)
  139. - Parser guide: [docs/guides/parser-guide.md](docs/guides/parser-guide.md)
  140. - Maintainer distribution guide: [docs/maintainers/distribution.md](docs/maintainers/distribution.md)
  141. Listed in these open source projects:
  142. - [awesome-mac](https://github.com/jaywcjlove/awesome-mac)
  143. - [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
  144. - [awesome-claude-skills](https://github.com/BehiSecc/awesome-claude-skills)
  145. ## Contributing
  146. Parser PRs are welcome. A good parser contribution usually includes:
  147. - a tiny redacted fixture or synthetic sample
  148. - format detection in `crates/agenttrace-core/src/parser.rs`
  149. - role, timestamp, model, token usage, tool call, and tool error extraction
  150. - tests for successful parsing and malformed input
  151. Run before sending a PR:
  152. ```bash
  153. cargo test
  154. cargo build --release -p agenttrace
  155. target/release/agenttrace --doctor
  156. ```
  157. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the full contribution flow.
  158. ## License
  159. [MIT](LICENSE) © 2026 agenttrace contributors

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.