agent-forensics

Agent Cost Observability for Claude Code. Analyze session logs to find token waste, calculate costs, and get actionable optimization recommendations.

Install

npx agent-forensics analyze <path>

Or install globally:

npm install -g agent-forensics

Usage

Basic analysis

npx agent-forensics analyze ~/.claude/projects/my-project/

Scans for .jsonl session logs and prints a cost breakdown with token usage, model distribution, tool usage, and hot turns.

Full analysis

npx agent-forensics analyze ~/.claude/projects/my-project/ --full

Includes everything in basic, plus:

• Waste patterns — redundant file reads, debug loops, context bloat, expensive model misuse, verbose output, sub-agent sprawl
• Recommendations — actionable changes to CLAUDE.md and .claudeignore
• Savings estimates — projected per-session and monthly savings

JSON output

npx agent-forensics analyze session.jsonl --json

Outputs raw JSON for piping into other tools or dashboards.

What it detects

| Pattern | Severity | Description | |---------|----------|-------------| | Redundant file reads | Medium | Same file read 3+ times in a session | | Debug loops | High | 5+ consecutive Bash calls (retry loops) | | Context bloat | Medium | Low cache read:create ratio | | Expensive model misuse | High | Opus used for simple single-tool operations | | Verbose output | Low | Turns with >4K output tokens | | Sub-agent sprawl | Medium | 10+ sub-agents spawned in one session |

API Access

For programmatic access, use the hosted API:

POST https://api.agentsconsultants.com/api/analyze
Content-Type: application/json

{ "content": "<jsonl-content>", "tier": "full" }

Pricing

• CLI: Free and open source (MIT)
• API Basic: $0.05/analysis
• API Full: $5.00/analysis

Privacy

All analysis is done in-memory. No session data is stored or logged, locally or via the API.

License

MIT