session-cost-forensics
Analyze local Codex, Pi, and Claude Code session logs for cost, token waste, cache misses, retries, duplicate sessions, and orchestration inefficiency. Tokens and cost come from llm-usage-metrics, which the bundled script runs through npx; the script adds compactions, retries, duplicate sessions, and subagent counts from the session files.
What it accesses
- Reads the local session stores
~/.codex(or$CODEX_HOME),~/.pi/agent/sessions,~/.omp/agent/sessions, and~/.claude/projectsand~/.claude/transcripts(or the same under each$CLAUDE_CONFIG_DIRentry), without writing to them. - Runs
npx --yes llm-usage-metrics@latest, which asks the npm registry for the latest release on every run and downloads it into the npm cache when it is not there yet. The script refuses output with an unknown JSONschemaVersion. - llm-usage-metrics downloads model prices from LiteLLM on GitHub (
raw.githubusercontent.com) when its price cache is older than a day, and caches them under~/.cache/llm-usage-metrics/. The request carries no session data.--pricing-offlineskips it and uses cached or bundled prices. - The script turns off the llm-usage-metrics event ledger and its update check, and counts only this machine, so it never syncs other machines over ssh.
Requirements
- Node.js >= 22.19 and
npx
Install
Pi
# pinned (versions are listed in the changelog linked below)
pi install npm:@ayagmar/session-cost-forensics@<version>
# unpinned
pi install npm:@ayagmar/session-cost-forensics
# remove
pi remove npm:@ayagmar/session-cost-forensics
skills CLI
npx skills add ayagmar/agents-skills --skill session-cost-forensics --agent pi
Other agent ids: claude-code, codex, cursor.
Claude Code
claude plugin marketplace add ayagmar/agents-skills
claude plugin install session-cost-forensics@ayagmar-skills
Codex
codex plugin marketplace add ayagmar/agents-skills
codex plugin add session-cost-forensics@ayagmar-skills
Usage
Prompt example: "Why did my agent sessions get so expensive this week? Break down token and cache usage." The agent runs the bundled script itself.
Run from the installed skill directory:
node scripts/session_cost_report.mjs --provider all --since 2026-09-01 --until 2026-09-28 --top 10
See SKILL.md for the full option list.