English | δΈζ | ζ₯ζ¬θͺ | FranΓ§ais | EspaΓ±ol | Ψ§ΩΨΉΨ±Ψ¨ΩΨ© | νκ΅μ΄ | PortuguΓͺs | Π ΡΡΡΠΊΠΈΠΉ | Deutsch
π What is your AI agent actually doing? Track costs, tokens, tool health, and every conversation β locally, in seconds.
npx @liangzhengtao/agent-trace Β· No API keys Β· No cloud services Β· 100% local
π Table of Contents
Your AI coding agent runs for hours. It calls tools, burns tokens, retries failed operations. But you have no idea:
- πΈ How much it actually cost
- π§ Which tools keep failing
- π Why it retried 15 times
- π Whether the model was slow or the tools were broken
- β±οΈ How long each conversation took
npx @liangzhengtao/agent-traceOne command. No API keys. No cloud services. Everything runs locally.
# Install
npm install -g agent-trace
# Auto-detect and analyze all sessions
agent-trace
# Analyze Kimi Code sessions
agent-trace -a kimi-code
# Analyze Claude Code sessions
agent-trace -a claude-code
# Show top 10 most expensive sessions
agent-trace -n 10
# Output as JSON
agent-trace --json π Summary
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
Sessions: 64
Total Cost: $4681.95
Total Tokens: 2,323,222,286
Total Messages: 3256
Total Tools: 11570
Total Time: 1593h 49m
π° Top 5 Most Expensive Sessions
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
Rank Session ID Cost Tokens Messages
ββββ ββββββββββββββββββββββββββ ββββββββ ββββββββ ββββββββ
1 session_37ce506c-ecbd-4ac9- $1517.15 757,285,306 1177
2 session_bd1b6c0e-a4cc-402c- $1210.12 596,458,795 508
3 session_daecc013-3b5b-44a8- $1080.48 538,333,781 489
π Agent Trace Report
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
π Session Overview
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
Duration: 45m 23s
Messages: 127 (User: 32, AI: 64, Tool: 31)
Tool Calls: 89 (12 unique tools)
Errors: 3
Retries: 2
π° Cost Analysis
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
Input Tokens: 245,891 ($0.0738)
Output Tokens: 89,234 ($0.1339)
Total Tokens: 335,125
Estimated Cost: $0.2076
π§ Tool Health
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Read ββββββββββββββββββββ 100% (45 calls, avg 120ms)
β Write ββββββββββββββββββββ 100% (23 calls, avg 85ms)
β Bash ββββββββββββββββββββ 75% (12 calls, avg 2s)
β Browser ββββββββββββββββββββ 44% (9 calls, avg 5s)
β οΈ Anomalies
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β High tool failure rate: 18/89
β High estimated cost: $5.23
β±οΈ Active Periods
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
09:15:23 β 09:47:56 (32m 33s, 45 messages)
10:02:11 β 10:31:44 (29m 33s, 52 messages)
π¬ Conversation
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
[YOU] Fix the authentication bug... 10:31:12
[AI ] I'll check the auth middleware... 10:31:14 (+2s)
[YOU] What about the token validation? 10:31:30 (+16s)
[AI ] Fixed. The issue was... 10:31:44 (+14s)
agent-trace [options] [directory]
Options:
-s, --session <id> Analyze specific session
-j, --json Output as JSON
-v, --verbose Show detailed timeline
-a, --agent <name> Agent type (opencode, kimi-code, claude-code, codex)
-n, --top <n> Show top N sessions by cost (default: 5)
--all Show all sessions (including empty)
--list-agents List supported agents
-h, --help Display help
-V, --version Display version
| Agent | Status | Config Path |
|---|---|---|
| OpenCode | β Supported | ~/.opencode/sessions/ |
| Claude Code | β Supported | ~/.claude/projects/ |
| Kimi Code | β Supported | ~/.kimi-code/sessions/ |
| Codex | β Supported | ~/.codex/sessions/ |
| Cursor | π Coming soon | β |
| Windsurf | π Coming soon | β |
| Cline | π Coming soon | β |
| Continue | π Coming soon | β |
By default, agent-trace scans all known paths and auto-detects which agent you're using:
agent-trace # Auto-detect and analyze all sessionsagent-trace -a claude-code # Only analyze Claude Code
agent-trace -a kimi-code # Only analyze Kimi Code
agent-trace -a opencode # Only analyze OpenCode
agent-trace -a codex # Only analyze Codex# GitHub Actions - check agent costs
- name: Check agent costsrun: | npx @liangzhengtao/agent-trace --json > trace.json COST=$(jq '.costBreakdown.total.cost' trace.json) if (( $(echo "$COST > 10" | bc -l) )); then echo "Agent cost too high: $COST" exit 1 fi- Reads local session files β No network requests, no API calls
- Parses message history β Extracts roles, tokens, timestamps
- Analyzes tool calls β Tracks success/failure rates
- Calculates costs β Based on standard API pricing
- Detects anomalies β High retries, failures, costs
- Generates report β Terminal output or JSON
- β 100% local β no data leaves your machine
- β Read-only β never modifies session files
- β No API keys β no external services
- β No tracking β no analytics, no telemetry
Contributions are welcome! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-thing - Commit your changes:
git commit -m 'feat: add amazing thing' - Push to the branch:
git push origin feature/amazing-thing - Open a Pull Request
See CONTRIBUTING.md for full guidelines.
MIT Β© Serennity007
Other tools by Serennity007:
| Repository | Description |
|---|---|
| agent-trace | π Observe your AI agents β costs, tokens, tool health |
Have a project to list here? Open a PR!
β Star this repo if Agent Trace helped you observe your AI agents!