{"id":51022750,"url":"https://github.com/fullstop000/token-efficiency","last_synced_at":"2026-06-21T17:01:22.882Z","repository":{"id":358317993,"uuid":"1240820812","full_name":"Fullstop000/token-efficiency","owner":"Fullstop000","description":"Token efficiency metrics and dashboard for AI coding agents (Claude Code and friends).","archived":false,"fork":false,"pushed_at":"2026-05-16T18:29:23.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T20:36:36.128Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","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/Fullstop000.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-05-16T15:59:33.000Z","updated_at":"2026-05-16T18:29:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Fullstop000/token-efficiency","commit_stats":null,"previous_names":["fullstop000/token-efficiency"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Fullstop000/token-efficiency","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fullstop000%2Ftoken-efficiency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fullstop000%2Ftoken-efficiency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fullstop000%2Ftoken-efficiency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fullstop000%2Ftoken-efficiency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fullstop000","download_url":"https://codeload.github.com/Fullstop000/token-efficiency/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fullstop000%2Ftoken-efficiency/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34618484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-21T17:01:18.385Z","updated_at":"2026-06-21T17:01:22.877Z","avatar_url":"https://github.com/Fullstop000.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# token-efficiency\n\nToken efficiency metrics, dashboard, and notes for AI coding agents.\n\nThis repo started as a tool to analyze [Claude Code](https://docs.claude.com/claude-code) session logs (`~/.claude/projects/*.jsonl`) and answer *where are my tokens going?* — but the broader question, **how do you measure token efficiency for an agentic system fairly**, has surprisingly little practical tooling. This is a place to put the tools and the thinking.\n\n## What's here\n\n- **CLI** — `token-efficiency parse | serve | report`\n- **Dashboard** — single-file HTML page with overview, daily breakdown, per-session drill-down\n- **Methodology** — [docs/METHODOLOGY.md](docs/METHODOLOGY.md): the metrics framework, what's directly computable vs. heuristic, what makes agent-vs-agent comparisons unfair\n\n## Install\n\n```bash\npipx install git+https://github.com/Fullstop000/token-efficiency\n# or\npip install git+https://github.com/Fullstop000/token-efficiency\n```\n\n## Usage\n\n```bash\n# parse session logs into data.json\ntoken-efficiency parse\n\n# get prioritized recommendations with $-saving estimates\ntoken-efficiency advise\n\n# per-session waste observations (repeat reads, dup tool calls, etc.)\ntoken-efficiency issues --top 20\ntoken-efficiency issues --type repeat_file_read --severity high\n\n# inspect rule definitions (YAML)\ntoken-efficiency rules                       # list all\ntoken-efficiency rules show repeat_file_read # full YAML for one rule\ntoken-efficiency rules path                  # bundled vs. user-override path\n\n# serve the dashboard (defaults to http://127.0.0.1:8765/)\ntoken-efficiency serve --open\n\n# parse + serve, AND enable the in-browser refresh button\ntoken-efficiency serve --projects-dir ~/.claude/projects --open\n\n# text summary, no browser\ntoken-efficiency report\n```\n\n## Recommendations (`advise`)\n\nThe tool turns the metrics into a prioritized action list with **estimated monthly savings**, **confidence**, and **risk**. Each card shows the math behind the number — no hidden estimates. Categories shipped in v0.2:\n\n- **Unused MCP servers** — disable a whole namespace if it has near-zero call coverage\n- **Buggy / high-error tools** — surface tools with \u003e20% error rate; retries are real money\n- **Hot-file → CLAUDE.md candidates** — files Read 10+ times without edit\n- **Session hygiene** — long-running sessions, cache-thrashing patterns\n\nThe dashboard's **Actions** tab shows the same list with per-card *Mark done* / *Dismiss* buttons (state persists in localStorage). The tool advises; you decide.\n\nMode: advise-only. The tool never edits your settings — it gives you the exact command to run.\n\n## Issue rules (YAML, user-overridable)\n\nEach issue type is defined by a YAML rule shipped with the package. Override any field by placing a YAML at `~/.token-efficiency/rules/\u003crule_id\u003e.yaml` — the user file is shallow-merged onto the bundled default, so you only declare the fields you want to change. Bundled rules:\n\n| Rule id | Detects |\n|---|---|\n| `repeat_file_read` | Same file Read 2+ times in one session |\n| `dup_tool_call` | Same tool + identical input called consecutively |\n| `large_unedited_read` | One Read of a \u003e10k-token file never edited |\n\nExample: drop your `repeat_file_read.yaml` threshold by writing only the override:\n\n```yaml\n# ~/.token-efficiency/rules/repeat_file_read.yaml\nid: repeat_file_read\nthresholds:\n  high_threshold: 3   # become 'high' at 3+ reads instead of 5\n```\n\nThe dashboard's **Rules** tab is a read-only control panel: shows each rule's full YAML, source (bundled vs. user-override), enabled state, and live trigger counts against your dataset. No in-browser editing in v1 — edits go through files only.\n\nOverride the source directory or output path:\n\n```bash\ntoken-efficiency parse --projects-dir /path/to/projects --out my-data.json\ntoken-efficiency serve --data my-data.json --port 9000\n```\n\n## What the dashboard shows\n\n**Overview** — KPI cards (total cost, sessions, p50 / p90 cost per session, CHR p50, tool error rate, flagged count), cost-per-session histogram, CHR histogram, cost-by-model donut, daily cost trend, and a flagged-sessions list sorted by severity.\n\n**Daily** — one row per day: sessions, total cost, p50 / p90 cost per session, total tokens, median CHR, median tool-error rate, flagged count. Click a row to drill into that day's sessions.\n\n**Sessions** — full session list, filterable and sortable. Click a session to open a modal with: token decomposition, per-turn cost timeline, quality breakdown (tool errors, duplicate-input calls, read-waste, useful-tool ratio, output composition).\n\n## Metrics\n\n### Tier 1 — direct from log fields\n\n| Metric | Formula |\n|---|---|\n| Cost ($) | Anthropic pay-per-token math: cache_read × 0.1, cache_write_5m × 1.25, cache_write_1h × 2, plus base input/output rates |\n| CHR (cache hit ratio) | `cache_read / (cache_read + input_new + cache_write)` |\n| Tool error rate | `tool_result.is_error == true` / total tool_use blocks |\n| Turn count | Unique `requestId`s |\n| Duration | `max(ts) − min(ts)` across records |\n| Output composition | Char-share of `thinking` / `text` / `tool_use` blocks |\n| Model mix | Cost share per model |\n\n### Tier 2 — heuristic\n\n| Metric | Heuristic |\n|---|---|\n| Read-waste | Count of files Read but never Edited/Written in this session |\n| Duplicate-input calls | Tool calls with same name + serialized input as the previous call |\n| Flags | Cache thrashing, tool retry storm, read-waste, high cost, very long session |\n\n### Tier 3 — NOT computed\n\n`pass@1`, task success, cost-per-resolved-issue (CPRI) — these require user-supplied labels for what counts as a successful session. Open issue if you want to design the labeling flow.\n\n## The dollar figure\n\nCost is computed at **theoretical pay-per-token API rates** at the prices defined in [`token_efficiency/pricing.py`](token_efficiency/pricing.py). If you're on a Claude Code subscription plan, your actual bill is the subscription — the dollar figure here is useful for relative efficiency comparisons and spotting outliers, **not as an invoice**.\n\nEdit `pricing.py` if your assumed rates differ.\n\n## Status \u0026 roadmap\n\nThis is v0.1. Working: Claude Code JSONL parser + dashboard. Not yet:\n\n- Parsers for other agent scaffolds (Codex CLI, Aider, Cursor)\n- Tier 3 success labeling\n- Cross-run distribution comparisons (this week vs. last week)\n- Composite Agentic Value Score on a leaderboard\n\nContributions and issue reports welcome.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstop000%2Ftoken-efficiency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullstop000%2Ftoken-efficiency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstop000%2Ftoken-efficiency/lists"}