CodeLedger: Open-source Claude Code plugin tracks token usage and background agents

What CodeLedger does

CodeLedger is an open-source Claude Code plugin (MCP server) that automatically tracks token usage, project costs, and background agent activity. It was created after analyzing 77 Claude Code sessions across 8 projects on the Max 20x plan, revealing significant token consumption by background agents.

The problem it solves

The built-in /cost command in Claude Code only shows current session data. There's no native way to see:

• Per-project history
• Per-agent breakdown
• What background agents are consuming
• Which model is being used for which task

When you close the terminal, that context disappears forever.

Key findings from the analysis

• $2,061 equivalent API cost across 77 sessions, 8 projects
• Most expensive project: $955 in tokens for a side project
• 233 background agents consumed 23% of agent token spend
• 57% of compute was Opus, including for tasks like file search that Sonnet handles fine
• One session spawned 100+ background agents, consuming $80+ in token value

Background agent patterns discovered

• acompact-* agents run automatically to compress context when conversations get long, using whatever model your session uses (including Opus)
• aprompt_suggestion-* agents generate prompt suggestions and spawn frequently in long sessions
• There's no native way to distinguish "agents I asked for" from "system background agents" without parsing the JSONL agentId prefixes

CodeLedger features

• Per-project cost tracking across all sessions
• Per-agent breakdown showing which agents consumed the most tokens
• Overhead detection separating your coding agents from background acompact-* and aprompt_suggestion-* agents
• Model optimization recommendations
• Conversational querying — ask "what did I spend this week on project X?"

How it works

• Hooks into SessionEnd events and parses local JSONL files
• Background scanner catches sessions where hooks weren't active
• Stores everything in a local SQLite database (~/.codeledger/codeledger.db) — zero cloud, zero telemetry
• Exposes MCP tools: usage_summary, project_usage, agent_usage, model_stats, cost_optimize

Installation

npm install -g codeledger

The tool is still waiting on Anthropic Marketplace approval, but the npm install works directly.