{"id":47787730,"url":"https://github.com/bhvbhushan/codeledger","last_synced_at":"2026-04-03T15:04:17.635Z","repository":{"id":344891965,"uuid":"1183012069","full_name":"bhvbhushan/codeledger","owner":"bhvbhushan","description":"Claude Code plugin for token-level cost intelligence — per-project, per-agent, per-skill usage tracking with local dashboard","archived":false,"fork":false,"pushed_at":"2026-04-03T13:00:24.000Z","size":26975,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T13:44:29.411Z","etag":null,"topics":["ai-analytics","analytics","anthropic","claude","claude-code","claude-code-plugin","cost-tracking","developer-tools","llm","mcp","mcp-server","nodejs","sqlite","token-usage","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/bhvbhushan/codeledger#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bhvbhushan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T07:21:44.000Z","updated_at":"2026-04-03T12:59:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bhvbhushan/codeledger","commit_stats":null,"previous_names":["bhvbhushan/codeledger"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bhvbhushan/codeledger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhvbhushan%2Fcodeledger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhvbhushan%2Fcodeledger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhvbhushan%2Fcodeledger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhvbhushan%2Fcodeledger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bhvbhushan","download_url":"https://codeload.github.com/bhvbhushan/codeledger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bhvbhushan%2Fcodeledger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31359097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T14:24:47.623Z","status":"ssl_error","status_checked_at":"2026-04-03T14:24:32.380Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-analytics","analytics","anthropic","claude","claude-code","claude-code-plugin","cost-tracking","developer-tools","llm","mcp","mcp-server","nodejs","sqlite","token-usage","typescript"],"created_at":"2026-04-03T15:02:14.181Z","updated_at":"2026-04-03T15:04:11.145Z","avatar_url":"https://github.com/bhvbhushan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeLedger\n\n**Token-level cost intelligence for AI coding tools.**\n\n[![npm version](https://img.shields.io/npm/v/codeledger)](https://www.npmjs.com/package/codeledger)\n[![license](https://img.shields.io/npm/l/codeledger)](./LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/node/v/codeledger)](https://nodejs.org/)\n\nCodeLedger is a Claude Code plugin that tracks where your AI coding tokens go — per-project, per-agent, per-skill — across Claude Code, Codex CLI, Cline, and Gemini CLI. It separates your actual coding work from background plugin overhead, sets budget alerts, and detects spend anomalies. Ask questions conversationally via MCP tools, or browse the local dashboard.\n\n### Setup \u0026 MCP Tools\n![CodeLedger Setup](demo/codeledger-setup.gif)\n\n### Dashboard\n![CodeLedger Dashboard](demo/codeledger-dashboard.gif)\n\n## Why CodeLedger?\n\nRunning Claude Code agents can burn through tokens fast. A single session with 49 parallel subagents can cost $8,000-$15,000. But you have zero visibility into:\n\n- Which **project** costs the most?\n- Which **agent** burned the most tokens?\n- How much is **plugin overhead** (claude-mem observers, auto-compaction) vs your actual work?\n- Are you using **Opus for tasks that Sonnet handles just as well**?\n- Am I going to **blow my budget** this month?\n- How much am I spending across **all my AI coding tools**?\n\nNo existing tool answers these questions. CodeLedger does.\n\n## What Makes It Different\n\n| Capability | ccusage | Agentlytics | tokscale | **CodeLedger** |\n|---|---|---|---|---|\n| Per-project tracking | Yes | Yes | No | **Yes** |\n| Per-agent token breakdown | No | No | No | **Yes** |\n| Per-skill attribution | No | No | No | **Yes (~estimated)** |\n| User vs overhead cost split | No | No | No | **Yes** |\n| Session category classification | No | No | No | **Yes** |\n| Cost optimization recommendations | No | No | No | **Yes** |\n| Budget alerts \u0026 anomaly detection | No | No | No | **Yes** |\n| Multi-tool cost tracking | No | Yes (16+) | Yes (16+) | **Yes (4 tools)** |\n| Conversational querying via MCP | No | No | No | **Yes** |\n| Local web dashboard | No | Yes | No | **Yes** |\n| Runs as Claude Code plugin | No | No | No | **Yes** |\n\n## Quick Start\n\n### Install from npm\n\n```bash\nnpm install -g codeledger\n```\n\n### Run Claude Code with the plugin\n\n**macOS / Linux:**\n```bash\nclaude --plugin-dir $(npm root -g)/codeledger\n```\n\n**Windows (PowerShell):**\n```powershell\nclaude --plugin-dir \"$(npm root -g)\\codeledger\"\n```\n\n**Windows (CMD):**\n```cmd\nfor /f \"delims=\" %i in ('npm root -g') do claude --plugin-dir \"%i\\codeledger\"\n```\n\nThis loads **everything** — 9 MCP tools, 4 hooks (real-time tracking), and slash commands.\n\n\u003e **Anthropic Plugin Marketplace:** CodeLedger has been submitted to the [official Claude Code plugin directory](https://github.com/anthropics/claude-plugins-official) and is **pending approval**. Once approved, installation will be simply:\n\u003e ```\n\u003e /plugin install codeledger\n\u003e ```\n\u003e Until then, use the npm install method above.\n\n### Start the dashboard\n\n```bash\nnpx codeledger dashboard\n```\n\nOpens a local dashboard at `http://localhost:4321` with charts, tables, and drill-downs.\n\n### Install from source (development)\n\n```bash\ngit clone https://github.com/bhvbhushan/codeledger.git\ncd codeledger \u0026\u0026 npm install \u0026\u0026 npm run build\nclaude --plugin-dir .\n```\n\n## Features\n\n### 9 MCP Tools (conversational querying)\n\nAsk Claude directly — no dashboards needed:\n\n- **`usage_summary`** — \"How much have I spent today?\" (includes spend velocity + budget status)\n- **`project_usage`** — \"Which project costs the most?\"\n- **`model_stats`** — \"What's my model distribution?\"\n- **`agent_usage`** — \"Which agents burned the most tokens?\"\n- **`skill_usage`** — \"How much does brainstorming cost vs code review?\" (~estimated)\n- **`cost_optimize`** — \"How can I reduce my costs?\" (6 evidence-based rules including anomaly detection)\n- **`budget_set`** — \"Set my monthly budget to $200\"\n- **`budget_status`** — \"Am I on track for my budget?\" (utilization + projected overshoot)\n- **`cross_tool_cost`** — \"How much am I spending across all my AI tools?\"\n\n### User vs Overhead Classification\n\nCodeLedger automatically separates your actual coding work from background noise:\n\n```\nThis Week — $142.62\n  Your coding agents:     $122.76 (86%)\n  Background overhead:     $19.87 (14%)\n    Plugin observers (acompact-*)\n    System agents (aprompt_suggestion-*)\n```\n\nZero configuration. Works by detecting agent ID prefixes — a structural signal present in all Claude Code versions.\n\n### Session Categories (auto-classified)\n\nEvery session is classified by what kind of work it does, based on tool usage patterns:\n\n| Category | Signal |\n|----------|--------|\n| **generation** | Write + Edit \u003e 40% of tool calls |\n| **exploration** | Read + Grep + Glob \u003e 60% |\n| **debugging** | Bash + Edit combos |\n| **review** | Read-heavy, no Write/Edit |\n| **planning** | Agent delegation dominant |\n| **devops** | Bash-heavy, no editing |\n| **mixed** | No dominant pattern |\n\nClassification is heuristic (~70-80% accuracy). Always labeled \"auto-categorized.\"\n\n### Cost Optimization\n\nEvidence-based recommendations with dollar amounts:\n\n```\n1. Opus used for exploration-only sessions\n   12 sessions spent $45.00 using Opus just for Read/Grep/Glob\n   Recommendation: Use Sonnet — same quality at 1/5 the price\n   Potential savings: ~$36.00\n\n2. Background plugin overhead exceeds 15%\n   $19.87 spent on overhead agents (14% of total)\n   Recommendation: Review active plugin configuration\n   Potential savings: ~$9.94\n```\n\n### Budget Alerts \u0026 Anomaly Detection\n\nSet per-project or total budgets and get proactive warnings:\n\n```\n## Budget Status (monthly, Apr 1 - Apr 30)\n| Scope | Budget | Spent | %   | Projected | Status              |\n|-------|--------|-------|-----|-----------|---------------------|\n| Total | $200   | $142  | 71% | $215      | ⚠️ Projected overshoot |\n| myapp | $75    | $68   | 91% | $102      | ⚠️ Near limit        |\n```\n\nAnomaly detection flags unusual spend spikes automatically:\n\n```\n6. Daily spend anomaly detected\n   Today's $25.40 is 3.2x your 30-day average of $7.80\n   Recommendation: Check for runaway agents or model upgrades\n```\n\nBudget alerts fire via stderr when a session ends and spend exceeds 75% of budget.\n\n### Multi-Tool Cost Tracking\n\nTrack spend across Claude Code, Codex CLI, Cline, and Gemini CLI — all from local session files, zero API keys needed:\n\n```\n## Cross-Tool Cost (month)\n| Tool        | Sessions | Cost    | Tokens |\n|-------------|----------|---------|--------|\n| claude-code | 45       | $142.50 | 15.7M  |\n| codex-cli   | 12       | $23.40  | 2.9M   |\n| gemini-cli  | 8        | $15.20  | 2.4M   |\n| Total       | 65       | $181.10 | 21.0M  |\n```\n\nCollectors auto-detect installed tools and parse their local data directories. Existing Claude Code analytics stay isolated — multi-tool data only appears in `cross_tool_cost`.\n\n### Local Dashboard\n\nDark-themed web dashboard at `localhost:4321`:\n\n- **Overview** — KPI cards, daily spend chart (user vs overhead), model distribution pie chart, top projects\n- **Projects** — per-project table with drill-down to sessions and agents\n- **Agents** — filter by user/overhead, click project to see its agents\n- **Skills** — per-skill estimated token attribution\n- **Optimize** — actionable cost reduction recommendations\n\n## How It Works\n\n```\n~/.claude/projects/*/              Claude Code JSONL session files\n         │\n         ├── SessionEnd hook ──────── Parses JSONL + budget alerts\n         ├── SubagentStop hook ────── Parses agent JSONL files\n         ├── PostToolUse hook ─────── Logs skill invocations\n         └── Background scanner ───── Catches missed sessions (every 5 min)\n                    │\n~/.codex/sessions/  │  Codex CLI JSONL ──── Codex collector\n~/.gemini/tmp/      │  Gemini CLI JSON ──── Gemini collector\n~/.vscode/.../cline │  Cline task JSON ──── Cline collector\n                    │\n                    ▼\n         ~/.codeledger/codeledger.db   SQLite (WAL mode)\n                    │\n          ┌─────────┼──────────┐\n          ▼         ▼          ▼\n      MCP Tools  Dashboard  Classifier\n     (9 tools)  (:4321)   (categories)\n```\n\nAll data stays local. Zero network calls. The SQLite database at `~/.codeledger/codeledger.db` is readable, exportable, and deletable at any time.\n\n## Configuration\n\n| Environment Variable | Default | Purpose |\n|---------------------|---------|---------|\n| `CODELEDGER_DB_PATH` | `~/.codeledger/codeledger.db` | Database location |\n| `CLAUDE_DATA_DIR` | `~/.claude` | Claude Code data directory |\n\nDashboard port: `npx codeledger dashboard --port 8080`\n\n## Development\n\n```bash\ngit clone https://github.com/bhvbhushan/codeledger.git\ncd codeledger\nnpm install\nnpm run build     # tsup: src/ → dist/\nnpm test          # vitest (170 tests)\nnpm run lint      # tsc --noEmit\nnpm run dev       # tsup --watch\n```\n\n## Privacy\n\n- **100% local.** All data stays in `~/.codeledger/`. Zero network calls.\n- **Read-only parsing.** CodeLedger reads JSONL files but never modifies them.\n- **No code or prompts stored.** Only aggregated metrics: token counts, costs, model names, tool names.\n- **User-owned data.** Delete `~/.codeledger/` at any time to remove all data.\n\n## Roadmap\n\n- [x] Per-project and per-session tracking\n- [x] Per-agent token breakdown with overhead classification\n- [x] Per-skill estimated token attribution\n- [x] Session category classification\n- [x] Cost optimization recommendations\n- [x] Local web dashboard\n- [x] Budget alerts and anomaly detection\n- [x] Multi-tool support (Codex CLI, Cline, Gemini CLI)\n- [ ] Team dashboard (hosted, multi-user aggregation)\n\n## Contributing\n\nContributions are welcome! Please read the [Contributing Guidelines](./CONTRIBUTING.md) before submitting a PR.\n\n- **Bug reports** and **feature requests** — use [Issue Templates](https://github.com/bhvbhushan/codeledger/issues/new/choose)\n- **Questions** — use [GitHub Discussions](https://github.com/bhvbhushan/codeledger/discussions)\n- **Security vulnerabilities** — see [Security Policy](./SECURITY.md)\n\nAll contributors are expected to follow the [Code of Conduct](./CODE_OF_CONDUCT.md).\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhvbhushan%2Fcodeledger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbhvbhushan%2Fcodeledger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhvbhushan%2Fcodeledger/lists"}