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.2

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

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