agent-trace is a post-session analysis tool for AI coding agents, provided as a command-line interface (CLI). Its core goal is to answer a common but hard-to-quantify question: what did your AI coding agent actually do during long runs, how much did it cost, which tools repeatedly failed, and why did it retry multiple times.
Purpose
When an AI coding agent runs continuously for hours, it calls tools, consumes tokens, and retries failed operations. But users often do not know the actual cost, which tools failed, why retries happened, whether the model is slow or the tool is broken, or how long each conversation took. agent-trace quickly generates these insights locally with a single command, with no API key and no cloud service.
Main capabilities
- Cost tracking: calculates session costs based on standard API pricing.
- Token tracking: extracts token usage from message history.
- Tool health analysis: counts the success and failure rates of tool calls.
- Conversation records: parses message history and extracts roles, tokens, and timestamps.
- Anomaly detection: identifies anomalies such as high retries, high failures, and high costs.
- Multi-session summary view: displays summary information for multiple sessions.
- Single-session detail view: drills into the details of a specific session.
- Auto-detection: scans all known paths by default and automatically identifies the agent in use.
- Force-specify agent: manually specify the agent to analyze.
- Output formats: supports terminal output or JSON output for easy CI integration.
Supported agents
According to official materials, agent-trace supports Kimi Code, Claude Code, Codex, and OpenCode. The official text also mentions "CLI for monitoring Claude, Cursor, Kimi Code sessions," but does not clearly list complete support details for Cursor; this is presented here only as in the original text.
Usage
Run directly via npx, with no installation required:
npx @liangzhengtao/agent-trace
By default, agent-trace scans all known paths and automatically detects the agent type. Users can also force a specific agent for analysis. The tool reads local session files and does not make network requests or API calls; parses message history and extracts roles, tokens, and timestamps; analyzes tool calls and tracks success/failure rates; calculates costs based on standard API pricing; detects anomalies (high retries, failures, costs); and generates reports, output to the terminal or JSON.
Use cases
- Developers want to understand the actual operating cost of AI coding agents.
- Need to troubleshoot which tools frequently fail or retry.
- Evaluate model response speed and tool health status.
- Integrate session analysis into CI workflows and output JSON reports.
- Summarize and compare multiple sessions.
Limitations and privacy
- 100% local operation; data never leaves the machine.
- Read-only mode; never modifies session files.
- No API key required and no dependence on external services.
- No tracking, no analytics, no telemetry.
- Cost calculations are based on standard API pricing; actual costs may differ due to pricing changes.
- Official materials do not provide specific installation requirements, system compatibility, version numbers, or detailed configuration parameters; this information is not currently available.
Contributing and license
Contributions to the project are welcome. The process is: Fork the repository, create a feature branch, commit changes, push the branch, and open a Pull Request. See CONTRIBUTING.md for the complete guide. The project uses the MIT License, with copyright owned by Serennity007.
