AgentTrace CLI
Reads local logs of Claude Code, Codex, Cursor and other agents and shows token spend, time and failures in a TUI
- 155 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The program reads agent session logs that may hold prompts, code and secrets
- Reports are written to disk and contain excerpts from those logs
Install
- Works in
Manual install
brew install luoyuctl/tap/agenttraceAlternatives: `npm install -g @zack78/agenttrace`, `cargo install --git https://github.com/luoyuctl/agenttrace agenttrace` and the install script from the README.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The program reads agent session logs that may hold prompts, code and secrets
- Reports are written to disk and contain excerpts from those logs
This is third-party code. Review the repository files before installing.
What it does
AgentTrace is a local TUI and report generator for AI agent session history, written in Rust. It reads logs from Claude Code, Codex CLI, Qwen Code, Cline, Aider, Cursor exports, Hermes Agent, OpenCode, OpenClaw, Pi, Oh My Pi, Kimi CLI, Copilot-style logs and plain JSON or JSONL, then does two jobs: show what different agents spent (cost, tokens, time) and find why a task ran slowly. Expensive and slow sessions come first. The program catches long gaps, hangs, retry loops, slow tool calls, large parameters and context pressure, compares a run with a local baseline to find regressions and shows an incident timeline. Sessions sort by cost, duration, turns, health, failures, model, source or text search. One `agenttrace` binary opens the TUI with no arguments, and with the flags `--sessions`, `--overview`, `--audit`, `--recommend`, `--mcp-governance`, `--context-trends` and `--delivery-evidence` it prints reports, including JSON for CI. `--lang en|zh` switches report language. An `agenttrace-session-audit` skill for agents is included. Everything runs locally and prompts and code never leave the machine.
Who it is for. Developers and team leads who pay for several coding agents and want costs, slow sessions and tool failures in one window.
Good fit when
- The token bill jumped and you need to see which sessions and models caused it
- A task ran too long and you want to find the gaps, retries and slow tool calls
- CI needs gates on cost and session health with a JSON report
- You want to compare Claude Code, Codex and Cursor on one scale of cost and time
Not a fit when
- You need cloud dashboards with team analytics: the program runs locally and sends nothing
- You need access control or blocking of agent actions: the tool reads logs and blocks nothing
- The agent has no logs on disk: the program reads already recorded history
Example request
Run agenttrace --overview for the last 30 days and show which sessions cost the most and why they are slowLimitations
Cost estimates use a price table and can differ from the provider bill: custom prices go in a file via the `AGENTTRACE_PRICING_FILE` variable. Log formats of different agents change, so parsing completeness depends on the agent version, and the `--overview` report shows parse and pricing confidence.
The program reads logs that may contain prompts, code and secrets and writes reports to disk, so treat reports as sensitive data. Installation options include a `curl | sh` script, Homebrew, npm and cargo, and you should read the script before running it. `docs/PRIVACY.md` describes data handling.
How to disable. Remove the `agenttrace` binary the way you installed it: `brew uninstall agenttrace`, `npm uninstall -g @zack78/agenttrace` or `cargo uninstall agenttrace`. Reports stay in the folders you chose.
FAQ
How do I install AgentTrace?
With Homebrew: `brew install luoyuctl/tap/agenttrace`. There is also `npm install -g @zack78/agenttrace`, `cargo install --git https://github.com/luoyuctl/agenttrace agenttrace` and an install script.
Which agents are supported?
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 or JSONL.
Does the program send data anywhere?
No, everything runs locally: logs are read from disk and prompts and code never leave the machine.
How do I get a report for CI?
Run `agenttrace --audit --range 30d -f json`. Other reports such as `--recommend` and `--delivery-evidence` also print JSON.
How do I set my own token prices?
Pass an overrides file via `AGENTTRACE_PRICING_FILE`, for example `AGENTTRACE_PRICING_FILE=pricing-overrides.json agenttrace --audit -f json`.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI records coding agent sessions locally, replays what happened and shows what the trace could not prove.
agentplay turns local Claude Code, Codex and Cursor sessions into a file map and a replayable step timeline.
Session monitor for Claude Code, Cursor, Codex and six more agents in a terminal, window or HTTP API, with chat cleanup and search
agentburn reads local logs of Claude Code, Codex and other agents and shows which windows and tasks consume tokens and money.
Streams Claude Code hidden thinking, tool calls and subagents to a separate terminal with a live session tree
Codex Trace reads local Codex CLI logs and shows turns, tool calls and token usage in a desktop window or in the browser.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| AgentTrace (this card) | no | 155 | |
| usage | no | 347 | shows spend for one agent, with no summary across a dozen with slow-run diagnosis |
| Codex Usage Tracker | no | 196 | tracks Codex spend only |
README in short
The repository describes a local tool to audit the spend and slow runs of AI agents. It includes a TUI, console and JSON reports, privacy docs and a roadmap, a Codex plugin manifest and a skill for agents. Interface messages are available in English and Chinese.
README badge
Original SKILL.md
--- name: agenttrace-session-audit description: Audit local AI coding-agent sessions with agenttrace. Use when the user asks to inspect Claude Code, Codex CLI, Qwen Code, Cline, Aider, Cursor exports, Hermes Agent, OpenCode, OpenClaw, Pi, Oh My Pi, Kimi CLI, Copilot-style logs, or generic JSON/JSONL traces for cost, tokens, tool failures, latency, anomalies, health, diffs, or CI gates. license: MIT metadata: short-description: Audit AI agent session health --- # agenttrace Session Audit Use this skill when session logs need an operational read: spend, token burn, cache use, tool failures, retry loops, latency, health, anomalies, and CI gate readiness. ## Workflow 1. Prefer the installed `agenttrace` binary when it is available on `PATH`. 2. If the binary is not available and the current directory is the `luoyuctl/agenttrace` repository, use `cargo run -q -p agenttrace --`. 3. Start with discovery unless the user gave a specific file or directory: ```bash agenttrace --doctor agenttrace --overview ``` 4. For a fast human report, use Markdown: ```bash agenttrace --overview -f markdown -o agenttrace-overview.md ``` 5. For automation or CI, use JSON or health gates: ```bash agenttrace --overview -f json -o agenttrace-overview.json agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15 ``` 6. For a single recent session: ```bash agenttrace --latest agenttrace --latest -f json ``` 7. For a specific export or session directory: