AgentTrace

Local-first TUI and reports for AI coding-agent session history, cost, tokens, time, and slow-run diagnosis.

English | 简体中文

---

agenttrace is a local-first terminal TUI and report generator for AI coding-agent session history. It reads 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, 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.

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.
• Did a run regress? Compare against a local baseline when supplied, then inspect incident timelines and conservative tool authority categories in reports.
• 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.5.0

Signal	What agenttrace found
Analyzed sessions	1,761
Total tokens	9.13B
Estimated cost	$5,037.26
Tool failure rate	1.1%
Critical sessions	16
Average health	91%

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

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

# Save a local baseline, then compare a later run
agenttrace --overview -f json -o agenttrace-baseline.json
agenttrace --overview -f json \
  --baseline agenttrace-baseline.json \
  -o agenttrace-overview.json

# 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, Pi, 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
Regression evidence	Local baseline comparison when supplied, incident timelines, and conservative tool authority categories in reports
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
• Awesome Claude Code and Skills
• awesome-x-ops
• Awesome DevOps AI
• agentic-ai-knowledge-base
• awesome-harness-engineering
• awesome-ai-tools
• awesome-claude-code-toolkit
• awesome-ai-plugins
• awesome-agent-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