AgentTrace

Review AI coding agent history across cost, tokens, and time, then find why a run was slow.

English | 简体中文

---

agenttrace is a local TUI and report generator for AI coding agent session history. It reads Claude Code, Codex CLI, Gemini CLI, Qwen Code, Cursor, Aider, OpenCode, OpenClaw, Hermes Agent, Kimi CLI, and Copilot-style logs, then helps with two daily jobs: see what multiple agents spent across cost, tokens, and time; and diagnose why a task ran slowly.

Why agenttrace?

AI coding agents now behave like small build systems: they call tools, retry, stall, and spend tokens while you only see the final answer.

agenttrace reads the logs your agents already write and puts cost-heavy or slow sessions first.

It helps you answer:

• What did my agents spend? Compare historical sessions by agent source, model, input/output/cache tokens, estimated cost, and wall-clock time.
• Why was this task slow? Catch long gaps, hanging sessions, retry loops, slow tool calls, large parameters, and context pressure.
• What should I inspect first? Rank sessions by cost, duration, turns, health, failures, anomalies, model, source, or text search.
• Can I inspect this privately? Everything runs locally; prompts, code, and logs do not need to leave your machine.

Real local run

These screenshots were captured from a local run against real session logs. They are not --demo output and not test fixtures.

agenttrace

Overview	Critical sessions

Session detail	Diagnostics

That local run found:

AGENTTRACE v0.4.2

Signal	What agenttrace found
Analyzed sessions	1,714
Total tokens	8.93B
Estimated cost	$4,896.61
Tool failure rate	1.5%
Critical sessions	35
Average health	90%

Install

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

Other install paths:

brew install luoyuctl/tap/agenttrace
go install github.com/luoyuctl/agenttrace/cmd/agenttrace@latest

Windows:

iwr -useb https://raw.githubusercontent.com/luoyuctl/agenttrace/master/install.ps1 | iex

The npm wrapper is also available as agenttrace after each release is published.

Common workflows

# Open the local TUI
agenttrace

# Check detected agent directories and cache state
agenttrace --doctor

# Generate machine-readable evidence
agenttrace --overview -f json

# Create a self-contained report for CI artifacts or issue links
agenttrace --overview -f html -o agenttrace-overview.html

# Fail CI on unhealthy agent runs
agenttrace --overview \
  --fail-under-health 80 \
  --fail-on-critical \
  --max-tool-fail-rate 15

Supported logs

agenttrace supports local sessions from:

Claude Code, Codex CLI, Gemini CLI, Qwen Code, Cline, Aider, Cursor exports, Hermes Agent, OpenCode, OpenClaw, Oh My Pi, Kimi CLI, Copilot-style logs, and generic JSON/JSONL traces.

What you get

Need	agenttrace gives you
Historical spend review	Sessions grouped across agents with token totals, model pricing, estimated cost, and elapsed time
Slow-task diagnosis	Latency stats, long gaps, hanging sessions, retry loops, slow tools, large params, and context pressure
First-session triage	Sort and filter by cost, duration, health, failures, anomalies, model, source, or text search
Shareable evidence	JSON, Markdown, and self-contained HTML reports
Local-first inspection	No hosted backend required

Docs

• Site: https://luoyuctl.github.io/agenttrace/
• Sample HTML report: https://luoyuctl.github.io/agenttrace/demo-report.html
• CI setup: docs/ci-integration.md
• Cursor import: docs/cursor-import.md
• Parser guide: docs/parser-guide.md
• Launch notes: docs/launch-kit.md

Listed in Awesome Gemini CLI, Charm in the Wild, and Awesome Claude Code and Skills.

Contributing

Parser PRs are welcome. A good parser contribution usually includes:

• a tiny redacted fixture or synthetic sample
• format detection in DetectFormat
• role, timestamp, model, token usage, tool call, and tool error extraction
• tests for successful parsing and malformed input

Run before sending a PR:

go test ./...
go build -o agenttrace ./cmd/agenttrace/
./agenttrace --doctor

See CONTRIBUTING.md for the full contribution flow.

License

MIT © 2026 agenttrace contributors