{"id":50084236,"url":"https://github.com/CodeShuX/tokenwise","last_synced_at":"2026-05-29T09:00:28.425Z","repository":{"id":357159144,"uuid":"1235672782","full_name":"CodeShuX/tokenwise","owner":"CodeShuX","description":"Cut Claude Code spend without sacrificing quality — and prove it. Haiku/Sonnet/Opus router with real $-saved numbers, not vibes.","archived":false,"fork":false,"pushed_at":"2026-05-11T16:07:35.000Z","size":324,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T16:39:05.986Z","etag":null,"topics":["ai-cost-optimization","anthropic","claude","claude-code","claude-skill","cost-reduction","developer-tools","haiku","llm-router","model-routing","opus","productivity","sonnet","subagents","token-optimization"],"latest_commit_sha":null,"homepage":"","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/CodeShuX.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-11T14:44:49.000Z","updated_at":"2026-05-11T16:22:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CodeShuX/tokenwise","commit_stats":null,"previous_names":["codeshux/tokenwise"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/CodeShuX/tokenwise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShuX%2Ftokenwise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShuX%2Ftokenwise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShuX%2Ftokenwise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShuX%2Ftokenwise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeShuX","download_url":"https://codeload.github.com/CodeShuX/tokenwise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeShuX%2Ftokenwise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33644313,"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-05-29T02:00:06.066Z","response_time":107,"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":["ai-cost-optimization","anthropic","claude","claude-code","claude-skill","cost-reduction","developer-tools","haiku","llm-router","model-routing","opus","productivity","sonnet","subagents","token-optimization"],"created_at":"2026-05-22T18:00:36.857Z","updated_at":"2026-05-29T09:00:28.390Z","avatar_url":"https://github.com/CodeShuX.png","language":"HTML","funding_links":[],"categories":["Skills","Agent Infrastructure"],"sub_categories":["Community Skills","Usage Analytics \u0026 Cost Tracking"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/social-preview.png\" alt=\"TokenWise — Cut your Claude Code spend by 80%. Measured on your real work, not a marketing claim.\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n# TokenWise\n\n\u003e **Cut your Claude Code token spend without sacrificing quality — and prove it.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](./LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/CodeShuX/tokenwise?style=social)](https://github.com/CodeShuX/tokenwise/stargazers)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-d97757)](https://claude.com/claude-code)\n[![Anthropic](https://img.shields.io/badge/Anthropic-Haiku%20%2B%20Sonnet%20%2B%20Opus-7c5cff)](https://www.anthropic.com)\n\nA Claude Code skill that routes work to the cheapest model that can handle it, **measures actual savings on your real workload**, and shows you the proof. Opus orchestrates, Haiku and Sonnet handle the grunt work, and you get a session report with verified $-saved numbers — not marketing claims.\n\n---\n\n## Table of Contents\n\n- [Why this exists](#why-this-exists)\n- [How it works](#how-it-works)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Sample output](#sample-output)\n- [How TokenWise compares](#how-tokenwise-compares)\n- [FAQ](#faq)\n- [What TokenWise is NOT](#what-tokenwise-is-not)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why this exists\n\nAnthropic's own [Issue #27665](https://github.com/anthropics/claude-code/issues/27665) reports that **93.8% of Max-subscriber tokens flow to Opus** — even when Haiku could have handled the task in a tenth the cost. Users have been asking for auto-routing for a year ([Issue #44976](https://github.com/anthropics/claude-code/issues/44976)). Anthropic hasn't shipped it.\n\nThe community has built workarounds. They fall into two camps:\n\n1. **Static catalogs** ([wshobson/agents](https://github.com/wshobson/agents), [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents)) — every subagent has a pinned `model:` field. Works, but you trust the catalog author's intuition.\n2. **Heuristic routers** ([0xrdan/claude-router](https://github.com/0xrdan/claude-router)) — auto-route by task complexity. Claims big savings. **Zero measurement.** You install the config and you're hoping.\n\nTokenWise is the third option: **route + measure + prove**.\n\nEvery routed task is logged to `.tokenwise/log.ndjson` with real token counts and cost numbers. `/tokenwise:report` shows what you actually spent vs. what you'd have spent at all-Opus. `/tokenwise:ab \"\u003ctask\u003e\"` runs the same task on Haiku and Sonnet, diffs the outputs, and tells you whether the cheaper tier was good enough.\n\nYou don't trust the savings. You verify them.\n\n---\n\n## How it works\n\nFive phases:\n\n1. **Detect** — Scans your Claude Code config, runs probes for known routing bugs ([#36381](https://github.com/anthropics/claude-code/issues/36381), [#47488](https://github.com/anthropics/claude-code/issues/47488)). Refuses to install if routing is broken on your build.\n2. **Configure** — Guided mode shows a diff and asks before every write, with automatic backups. Manual mode prints copy-paste blocks and exits. You pick.\n3. **Measure** — Every routed subagent appends one NDJSON line to `.tokenwise/log.ndjson` with token counts, costs, escalations, durations. All local. Zero telemetry.\n4. **A/B test** — `/tokenwise:ab \"\u003ctask\u003e\"` runs the same task on multiple tiers, diffs outputs, scores quality, writes a report. Use this to validate \"is Haiku really good enough for my codebase?\" before you trust the router.\n5. **Report** — `/tokenwise:report` (this session), `/tokenwise:summary --week` (trend), `/tokenwise:undo` (restore config from backup).\n\nThe router classifies tasks into three tiers:\n\n| Tier | Model | What it gets |\n|---|---|---|\n| **Mechanical** | Haiku 4.5 | file reads, grep, format, rename, simple edits, doc lookups |\n| **Scoped reasoning** | Sonnet 4.6 | single-file refactor, test writing, scoped research, code exploration |\n| **Synthesis / planning** | Opus 4.7 | architecture decisions, multi-file synthesis, security review, ambiguous requirements |\n\nSafety caps prevent regressions:\n- Haiku never spawns further subagents (if it wants to, the task was wrong-sized)\n- Max spawn depth = 2 (parent → subagent → one more tier)\n- Trivial-task floor: tasks under 100 chars with no file context run inline (subagent overhead \u003e savings)\n- Input bump: if subagent context would exceed 30k tokens, escalate one tier\n\n---\n\n## Installation\n\n**Prerequisites:**\n- [Claude Code](https://claude.com/claude-code) installed (verified on v2.x)\n\n### Option 1 — One-line install via Claude Code marketplace (recommended)\n\nIn any Claude Code session, run:\n\n```\n/plugin marketplace add CodeShuX/tokenwise\n/plugin install tokenwise@tokenwise\n```\n\nThen in a fresh session:\n\n```\n/tokenwise:install\n```\n\nTokenWise will detect your config, show a diff of proposed changes, and ask for confirmation before writing anything.\n\n### Option 2 — Manual symlink\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/CodeShuX/tokenwise.git ~/tokenwise\n\n# 2. Symlink the skill into your Claude Code skills directory\nmkdir -p ~/.claude/skills\nln -s ~/tokenwise/skill/SKILL.md ~/.claude/skills/tokenwise.md\n```\n\nVerify either way by typing `/tokenwise` in any Claude Code session.\n\n---\n\n## Usage\n\n### First-time setup\n\n```\n/tokenwise:install\n```\n\nTokenWise will:\n1. Read your `~/.claude/CLAUDE.md`, project `CLAUDE.md`, and `~/.claude/settings.json`\n2. Run probes against your Claude Code build (catches Anthropic Issues #36381 and #47488)\n3. Show you the proposed diff for each file\n4. Back up each file before modifying (`\u003cfile\u003e.tokenwise-backup-\u003ctimestamp\u003e`)\n5. Write the routing rules + optional env vars\n\nIf you'd rather copy-paste than have TokenWise write your config:\n\n```\n/tokenwise:install --manual\n```\n\nPreview without writing anything:\n\n```\n/tokenwise:install --dry-run\n```\n\n### Daily use\n\nAfter install, **nothing changes in your workflow**. Just use Claude Code normally. The router runs in the background. Every routed task is logged.\n\nWhen you want to see savings:\n\n```\n/tokenwise:report          # this session\n/tokenwise:summary --week  # last 7 days\n/tokenwise:summary --all   # everything in the log\n```\n\nWhen you want to validate the router on a specific task:\n\n```\n/tokenwise:ab \"rename all uses of getCwd to getCurrentWorkingDirectory across the codebase\"\n```\n\nTokenWise runs the task on Haiku and Sonnet separately, diffs the outputs, scores them, and writes `tokenwise-ab-\u003ctimestamp\u003e.md` to your project root.\n\nWhen you want to undo TokenWise's config changes:\n\n```\n/tokenwise:undo\n```\n\nLists all `.tokenwise-backup-*` files and lets you restore one.\n\n---\n\n## Sample output\n\n### Session report\n\n```\nTokenWise Session Report\n========================\n\nTasks routed:        47\nDuration:            2h 14m\n\nPer model:\n  Haiku    32 tasks   1.2M input  /  84K output   →  $1.62\n  Sonnet   12 tasks   480K input  /  41K output   →  $2.06\n  Opus      3 tasks   145K input  /  28K output   →  $1.43\n\nTotal spent:         $5.11\nBaseline (all-Opus): $24.93\nSavings:             $19.82  (79.5%)\n\nQuality flags:\n  Escalations:        2 (Haiku → Sonnet, mid-task)\n  User overrides:     0\n  Regressions:        0\n```\n\n[See full example reports →](./examples/)\n\n### A/B test\n\n```markdown\n# A/B Test — rename getCwd → getCurrentWorkingDirectory\nRun: 2026-05-11 14:32:18\n\n## Tier comparison\n\n| Tier   | Tokens (in/out) | Cost   | Duration | Quality |\n|--------|-----------------|--------|----------|---------|\n| Haiku  | 12.4k / 890     | $0.017 | 4.2s     | 8/10    |\n| Sonnet | 11.8k / 1.2k    | $0.053 | 6.8s     | 9/10    |\n\n## Recommendation\n\nFor this task class, **Haiku is sufficient** (quality 8/10, 68% cheaper).\n```\n\n---\n\n## How TokenWise compares\n\n| Tool | Routes | Measures | A/B tests | Telemetry |\n|---|---|---|---|---|\n| **TokenWise** | ✅ | ✅ | ✅ | ❌ (local-only) |\n| [0xrdan/claude-router](https://github.com/0xrdan/claude-router) | ✅ | ❌ | ❌ | ❌ |\n| [wshobson/agents](https://github.com/wshobson/agents) | ✅ (static pin) | ❌ | ❌ | ❌ |\n| [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | ✅ (static pin) | ❌ | ❌ | ❌ |\n| [ccusage](https://github.com/ryoppippi/ccusage) | ❌ | ✅ | ❌ | ❌ |\n| LiteLLM / OpenRouter | ✅ (cross-vendor) | ❌ | ❌ | varies |\n\n**TokenWise is the only tool that closes the loop: route → measure → prove → adjust.** ccusage measures but doesn't route. claude-router routes but doesn't measure. Static catalogs do neither dynamically.\n\n---\n\n## FAQ\n\n### How much will it actually save me?\n\nThat depends on your workload. The router can only save what's safe to route — a session that's 90% architecture decisions won't see big savings; a session that's 90% file reads will. **The point isn't a guaranteed %. The point is that you'll know your real %, because TokenWise measures it.**\n\nCurrent Anthropic pricing (May 2026, per 1M tokens):\n\n| Model | Input | Output |\n|---|---|---|\n| Opus 4.7 | $5 | $25 |\n| Sonnet 4.6 | $3 | $15 |\n| Haiku 4.5 | $1 | $5 |\n\nOpus is 5× more expensive than Haiku for the same token. A task routed correctly to Haiku costs 20¢ on the dollar.\n\n### Does it work with my Claude Code build?\n\nTokenWise probes your build at install time. Specifically:\n- **Issue #36381** — `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` was silently ignored in some Claude Code versions. TokenWise sets-and-reads-back to verify it's honored.\n- **Issue #47488** — Subagent `model:` param was silently overridden in some versions. TokenWise spawns a probe Haiku subagent and verifies the model param took effect.\n\nIf either probe fails, TokenWise refuses to install and tells you exactly which Anthropic issue is affecting you.\n\n### Is my data sent anywhere?\n\n**No.** TokenWise has zero telemetry. All logs are append-only NDJSON in `.tokenwise/log.ndjson` in your project. Task descriptions are truncated to 80 chars and stripped of file contents before logging. There is no analytics endpoint, no error reporter, no usage tracker.\n\nYou can audit this by reading `skill/SKILL.md` and grepping for any network call. There aren't any.\n\n### Will TokenWise modify my files?\n\nOnly the ones you explicitly approve at install time:\n- `~/.claude/CLAUDE.md` (or project `./CLAUDE.md` — you pick)\n- `~/.claude/settings.json` (only if the env-var probe passes)\n\nEvery write requires `[Y/n]` confirmation. Every original is backed up to `\u003cfile\u003e.tokenwise-backup-\u003ctimestamp\u003e`. `/tokenwise:undo` restores in one command.\n\nIf you'd rather not have TokenWise touch your files at all, run `/tokenwise:install --manual` — it prints copy-paste blocks and exits without writing anything.\n\n### What about prompt caching?\n\nAnthropic's 90% cached-input discount is honored automatically. TokenWise reports raw cost (conservative) — actual savings on cached reads will be larger than reported. The **prompt-cache hint detector** flags files re-read 3+ times in a session as cache-eligible.\n\n### Does this work outside Claude Code?\n\nNo. TokenWise is Claude-Code-specific by design. If you need cross-vendor routing (Claude + GPT + Gemini), use [LiteLLM](https://github.com/BerriAI/litellm) or [OpenRouter](https://openrouter.ai). TokenWise stays in its lane — Anthropic-only, Claude-Code-only — and does that lane better than anything else.\n\n### What if Haiku gets a task wrong?\n\nTwo things:\n1. **Safety caps** — if Haiku realizes a task needs more reasoning, it returns to the parent (Opus) without escalating on its own. The parent re-classifies and retries at a higher tier. The escalation is logged so you can see how often it happens.\n2. **A/B test mode** — `/tokenwise:ab \"\u003ctask\u003e\"` runs the same task on multiple tiers and scores them. If you're nervous about Haiku for some task class, run the A/B once and see.\n\nThe most common escalation pattern is `Haiku → Sonnet` for tasks involving more than 2 file dependencies. That's worth knowing — and TokenWise tells you.\n\n### What's the license?\n\nMIT. Use it commercially, modify it, redistribute it. See [LICENSE](./LICENSE).\n\n---\n\n## What TokenWise is NOT\n\n| Tool | Use case |\n|---|---|\n| **LiteLLM / OpenRouter** | Multi-vendor routing across Anthropic / OpenAI / Google |\n| **Anthropic Batch API** | Bulk async work with a 24h SLA (50% discount) |\n| **ccusage / claude-monitor** | Token tracking without routing |\n| **wshobson / VoltAgent catalogs** | Static subagent libraries with pinned models |\n| **TokenWise** | **Measurement-driven routing for Claude Code, Anthropic-only** |\n\nTokenWise doesn't replace any of these. It fills the gap they don't cover: \"is my routing actually saving me money, and how would I know?\"\n\n---\n\n## Roadmap\n\n**v0.2** (planned)\n- Pre-task cost estimator\n- GitHub Action — run `/tokenwise:report` on PR previews, comment savings\n- Multi-month digest with trend lines\n- YAML-editable routing taxonomy (override the defaults for your codebase)\n\n**v1.0** (later)\n- Workload profiles — save \"my-Rails-app\" taxonomy as a sharable profile\n- Self-healing prompt rewrites (rewrite a task description so Haiku can handle it)\n- Cost projection across full project history\n\n---\n\n## Contributing\n\nPRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nAreas where help is most needed:\n- **Pricing updates** when Anthropic publishes new rates\n- **Routing taxonomy refinements** — backed by A/B test reports\n- **Cross-platform install testing** (Mac / Linux / Windows / WSL)\n- **Troubleshooting docs** for common Claude Code routing-bug workarounds\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\n---\n\n## Acknowledgments\n\nBuilt on the routing primitives in [Claude Code](https://claude.com/claude-code) by Anthropic. Inspired by community workarounds in [Issue #44976](https://github.com/anthropics/claude-code/issues/44976) and the \"Opus orchestrator, Haiku subagents\" pattern surfaced by [@sakeeb.rahman](https://www.threads.com/@sakeeb.rahman/post/DUQOcC2kUpb).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/social-preview.png\" alt=\"TokenWise\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/CodeShuX/tokenwise\"\u003egithub.com/CodeShuX/tokenwise\u003c/a\u003e · \u003ca href=\"./LICENSE\"\u003eMIT\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCodeShuX%2Ftokenwise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCodeShuX%2Ftokenwise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCodeShuX%2Ftokenwise/lists"}