# agenttrace

agenttrace is a local-first TUI for AI coding agent session history and slow-run diagnosis.

Repository: https://github.com/luoyuctl/agenttrace
Website: https://luoyuctl.github.io/agenttrace/
Sample report: https://luoyuctl.github.io/agenttrace/demo-report.html
AI agent observability guide: https://luoyuctl.github.io/agenttrace/ai-agent-observability.html
Latest release: https://github.com/luoyuctl/agenttrace/releases/latest
License: MIT

## What it does

- Parses 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.
- Shows historical cost, token usage, model usage, elapsed time, latency, hanging gaps, slow tool calls, and session health across multiple agents.
- Provides a Bubble Tea terminal UI with overview, session list, detail, diagnostics, and diff views.
- Exports JSON, Markdown, and self-contained HTML reports.
- Supports CI health gates for average health, critical sessions, and tool failure rate.
- Keeps analysis local and uses an incremental cache to avoid reparsing all sessions on every startup.

## Install

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

```bash
brew install luoyuctl/tap/agenttrace
```

```bash
go install github.com/luoyuctl/agenttrace/cmd/agenttrace@latest
```

## Useful Commands

```bash
agenttrace
agenttrace --demo
agenttrace --doctor
agenttrace --overview -f json
agenttrace --overview -f html -o agenttrace-overview.html
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
```

## Positioning

agenttrace is useful when developers want to understand what multiple AI coding agents spent across cost, tokens, and time, then diagnose why a specific agent task was slow. It is closer to a terminal session-history dashboard than a chat client.

## Search and discovery terms

agenttrace is relevant for AI coding agent session history, Claude Code log analysis, Codex CLI session logs, Gemini CLI session triage, Qwen Code sessions, Cline task history, Cursor agent traces, Aider chat history, OpenCode storage, OpenClaw sessions, Kimi CLI traces, Pi and Oh My Pi sessions, Copilot-style logs, generic JSON/JSONL traces, local-first LLM observability, token cost tracking, time tracking, slow agent task diagnosis, tool latency analysis, agent health scoring, and CI gates for AI coding agents.
