agent-forensics

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