{"id":48954912,"url":"https://github.com/rahuldhiman93/tokenomy","last_synced_at":"2026-04-30T03:03:48.733Z","repository":{"id":352091640,"uuid":"1213815428","full_name":"RahulDhiman93/Tokenomy","owner":"RahulDhiman93","description":"Tokenomy — A surgical toolkit for Claude Code and Codex CLI.","archived":false,"fork":false,"pushed_at":"2026-04-23T01:03:10.000Z","size":1000,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-23T03:02:30.846Z","etag":null,"topics":["anthropic","claude-code","mcp","npm-package","token-reduction"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/tokenomy","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/RahulDhiman93.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":"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-04-17T19:44:08.000Z","updated_at":"2026-04-23T01:03:14.000Z","dependencies_parsed_at":"2026-04-24T04:00:44.214Z","dependency_job_id":null,"html_url":"https://github.com/RahulDhiman93/Tokenomy","commit_stats":null,"previous_names":["rahuldhiman93/tokenomy"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/RahulDhiman93/Tokenomy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RahulDhiman93%2FTokenomy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RahulDhiman93%2FTokenomy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RahulDhiman93%2FTokenomy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RahulDhiman93%2FTokenomy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RahulDhiman93","download_url":"https://codeload.github.com/RahulDhiman93/Tokenomy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RahulDhiman93%2FTokenomy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32208477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"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":["anthropic","claude-code","mcp","npm-package","token-reduction"],"created_at":"2026-04-17T23:12:30.411Z","updated_at":"2026-04-30T03:03:48.726Z","avatar_url":"https://github.com/RahulDhiman93.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg alt=\"Tokenomy\" src=\"https://raw.githubusercontent.com/RahulDhiman93/Tokenomy/main/src/assets/logo.jpg\" width=\"200\"\u003e\n\n### Stop burning tokens on tool chatter.\n\nA surgical hook + analysis toolkit for **Claude Code, Codex CLI, Cursor, Windsurf, Cline, and Gemini** that transparently trims bloated MCP responses, clamps oversized file reads, bounds verbose shell commands, dedupes repeat calls, compresses agent memory files, and benchmarks waste.\n\n[![CI](https://github.com/RahulDhiman93/Tokenomy/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RahulDhiman93/Tokenomy/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/RahulDhiman93/Tokenomy/main/.github/badges/coverage.json\u0026cacheSeconds=300)](#contribute)\n[![npm](https://img.shields.io/npm/v/tokenomy.svg?label=npm\u0026color=cb0000\u0026cacheSeconds=300)](https://www.npmjs.com/package/tokenomy)\n[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](#quickstart)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)\n[![Phase](https://img.shields.io/badge/phase%205-beta-blue)](#roadmap)\n\n\u003c/div\u003e\n\n---\n\n## 🩻 Why\n\nLong agent sessions burn 100k+ tokens on tool chatter before the agent does any real work. Compaction kicks in too late and is lossy.\n\nTokenomy plugs the holes the hook contracts let you close — zero proxy, no monkey-patching:\n\n- **Live trimming** — MCP/Bash/Read/Write hooks shrink responses the moment they fire\n- **Code-graph MCP** — focused context retrieval instead of brute-force `Read` sweeps\n- **Agent nudges** — redirect waste before it happens (OSS alternatives, prompt classifier)\n- **Golem** — terse-output mode (the one surface other features leave alone — assistant output is billed 5× input on Sonnet)\n- **Raven** — Claude/Codex cross-agent handoff + review bridge\n- **Observability** — `savings.jsonl`, `tokenomy report`, `tokenomy analyze`, statusline, doctor\n\nEach live trim appends a row to `~/.tokenomy/savings.jsonl` with measured bytes-in / bytes-out. Run `tokenomy report` for a digest, or `tokenomy analyze` to benchmark historical waste from session transcripts.\n\n---\n\n## ⚡ Quickstart\n\n```bash\nnpm install -g tokenomy\ntokenomy init --graph-path \"$PWD\"   # patches Claude/Codex/Cursor/Windsurf/Cline/Gemini configs + builds the graph\ntokenomy doctor                     # all checks passing\n# restart Claude Code — done\n```\n\nCodex CLI, Cursor, Windsurf, Cline, Gemini auto-detected and registered when each is on PATH. Force one target with `--agent \u003cname\u003e`; inspect first with `tokenomy init --list-agents`.\n\n\u003e **Pre-`1.0`.** Breaking changes may land before `1.0.0` (see [CHANGELOG](./CHANGELOG.md)). Pin: `npm install -g tokenomy@0.1.6`. Upgrade: `tokenomy update`.\n\n---\n\n## \u003cimg src=\"https://claude.ai/apple-touch-icon.png\" alt=\"Claude\" width=\"22\" style=\"vertical-align: middle;\"\u003e Zero-touch interactive install via Claude Code\n\nPaste this into Claude Code. The agent installs Tokenomy with the graph MCP first, then walks you through each opt-in feature one at a time so you can pick what fits your workflow.\n\n```\nInstall tokenomy for me, then walk me through the optional features one by one.\n\nStep 1 — Install the core:\n  1. Run: npm install -g tokenomy\n  2. Run: tokenomy init --graph-path \"$PWD\"\n     (patches Claude Code config, registers the tokenomy-graph MCP server\n      for this repo, and builds the code graph)\n  3. Run: tokenomy doctor\n\nStep 2 — Then ask me about each optional feature, one at a time.\n  For each feature: give me a 2-3 sentence explanation of what it does,\n  what it costs (tokens / latency / friction), and a yes/no question.\n  Wait for my answer before moving on. Apply the install command for\n  features I say yes to. Skip features I say no to.\n\n  Walk through these features in order:\n\n  a) Golem — terse-output mode plugin. Five modes from `lite`\n     (drop hedging) up to `recon` (zero banter, info-density only).\n     Cuts assistant output tokens 20-65 % depending on mode. Ask me\n     which mode I want, or whether to skip entirely.\n     Install: tokenomy golem enable --mode=\u003cchosen\u003e\n\n  b) Raven bridge — Claude Code + Codex CLI cross-agent handoff +\n     review packets. Useful only if I have Codex CLI on PATH and I\n     actually do code review with both agents. Skip if I only use\n     Claude.\n     Install: tokenomy raven enable\n\n  c) OSS-alternatives nudge (Write intercept) — when I'm about to\n     create a new utility-ish file \u003e 500 B, Tokenomy reminds me to\n     check `find_oss_alternatives` first. Catches reinventing-the-wheel\n     work. Default ON; ask if I want it off.\n     Disable: tokenomy config set nudge.write_intercept.enabled false\n\n  d) Prompt-classifier nudge — fires once per turn when I prompt\n     \"any existing library for X\" / \"alternative to Y\" / \"instead of\n     building Z\". Conservative since 0.1.2 (was overly broad before).\n     Default ON; ask if I want it off.\n     Disable: tokenomy config set nudge.prompt_classifier.enabled false\n\n  e) Pre-call redact — extends secret redaction to PreToolUse on\n     Bash/Write/Edit. Catches API keys, tokens, JWTs, PEM blocks\n     before they hit the assistant. Default OFF; ask if I want it on\n     (recommended if I work with credentials).\n     Enable: tokenomy config set redact.pre_tool_use true\n\n  e.5) Kratos — security shield. Continuously scans my prompts for\n     prompt-injection (\"ignore previous instructions\"), data-exfil\n     requests, secrets I accidentally pasted, hidden zero-width chars.\n     Also runs `tokenomy kratos scan` to audit installed MCP servers\n     for read-source ↔ write-sink combos that form an exfil route.\n     Default OFF. Strongly recommended if I have any third-party MCP\n     servers (Slack, Gmail, Atlassian, etc.) installed. Ask me yes/no.\n     Enable: tokenomy kratos enable\n     One-shot audit: tokenomy kratos scan\n\n  f) Budget pre-flight — advisory PreToolUse rule that warns when a\n     call would push my session past a token cap. Never blocks.\n     Default OFF; ask if I want it on with what cap.\n     Enable: tokenomy config set budget.session_cap_tokens 200000\n\n  g) Statusline — one-line live savings counter. Shows version,\n     Golem mode, graph freshness, today's trims, and a `↑` after the\n     version when an update is available. Already wired by `init`;\n     just confirm it's working and move on.\n\n  h) Live graph freshness (0.1.3+) — graph stays fresh during the\n     session. PostToolUse hook on Edit/Write/MultiEdit drops a\n     `.dirty` sentinel; the next graph query rebuilds in the\n     background. ON by default. Tell me whether to keep it ON\n     (recommended) or disable.\n     Disable: tokenomy config set graph.async_rebuild false\n\n  i) Multi-repo graph + Raven (0.1.3+) — register the graph in EACH\n     repo I want it for. Run `tokenomy init --graph-path \"$PWD\"` in\n     each project root. When working across repos in one Claude\n     session, agents should pass `path: \"$PWD\"` to the MCP tools so\n     Tokenomy resolves the right per-repo graph + Raven store.\n     No-op for single-repo workflows.\n\n  j) Auto update-check (0.1.3+) — SessionStart fires\n     `tokenomy update --check --quiet` (detached, fail-open,\n     throttled 3h) so a new release shows up in the statusline `↑`\n     marker on the next Claude restart. ON by default. No action\n     needed; just confirm.\n\n  k) Diagnose (0.1.5+) — `tokenomy diagnose` emits a JSON health\n     report covering every feature + environment. Useful for paste\n     into `tokenomy feedback` when something looks wrong. No\n     install action needed; just demo it once and move on.\n     Demo: tokenomy diagnose\n\nStep 3 — Final check:\n  1. Run: tokenomy doctor\n  2. Tell me to fully quit Claude Code (Cmd+Q) and reopen so the new\n     hooks + MCP server + SessionStart preamble load cleanly.\n```\n\n---\n\n## 🧭 Features\n\nEach feature has its own README. Main README stays small.\n\n| Area | What | Docs |\n|---|---|---|\n| Live token trimming | MCP / Bash / Read / Write / Edit hooks — multi-stage pipeline, dedup, redact, stacktrace collapse, schema profiles, shape-trim, byte-trim | [docs/features/live-trimming.md](./docs/features/live-trimming.md) |\n| Code-graph MCP | `tokenomy-graph` stdio server — `get_minimal_context`, `get_impact_radius`, `get_review_context`, `find_usages`, `find_oss_alternatives` | [docs/features/code-graph.md](./docs/features/code-graph.md) |\n| Agent nudges | OSS-alternatives Write nudge, prompt-classifier, repo-search relevance gate | [docs/features/agent-nudges.md](./docs/features/agent-nudges.md) |\n| Golem | Terse output mode — `lite` / `full` / `ultra` / `grunt` / `recon` / `auto`. Safety-gated for code, commands, warnings, numbers | [docs/features/golem.md](./docs/features/golem.md) |\n| Raven bridge | Claude-primary + Codex-reviewer handoff packets, deterministic finding compare, PR-readiness verdict | [docs/features/raven.md](./docs/features/raven.md) |\n| Kratos *(0.1.2+)* | Security shield — prompt-injection / data-exfil / secret-in-prompt detector + cross-MCP exfil-pair scanner | [docs/features/kratos.md](./docs/features/kratos.md) |\n| Feedback *(0.1.2+)* | `tokenomy feedback \"...\"` files a GitHub issue (via `gh` or browser fallback). No backend service. | [docs/features/feedback.md](./docs/features/feedback.md) |\n| Diagnose *(0.1.5+)* | `tokenomy diagnose [--json]` — single-shot health report covering every feature + environment. Designed to paste into `tokenomy feedback`. | [docs/features/diagnose.md](./docs/features/diagnose.md) |\n| Observability | `savings.jsonl`, `report`, `analyze`, `diff`, `learn`, `budget`, `bench`, `status-line`, `doctor`, `update` | [docs/features/observability.md](./docs/features/observability.md) |\n| Compress | `tokenomy compress` — agent rule file cleanup (CLAUDE.md, AGENTS.md, .cursor/rules) | [docs/features/compress.md](./docs/features/compress.md) |\n| Cross-agent install | Per-agent adapters for Claude / Codex / Cursor / Windsurf / Cline / Gemini | [docs/features/cross-agent.md](./docs/features/cross-agent.md) |\n| Configure | `~/.tokenomy/config.json` — full reference + common tweaks | [docs/features/configure.md](./docs/features/configure.md) |\n\n---\n\n## 💸 Real savings from one dogfood session\n\nTokenomy run on its own repo in a fresh Claude Code session (Bash verbose commands, Read on a large file, five graph MCP queries):\n\n```\nWindow:             2026-04-20T01:32:56Z → 2026-04-20T01:55:10Z   (~22 minutes)\nTotal events:       14\nBytes trimmed:      1,374,113 → 260,000   (−1,114,113)\nTokens saved (est): 285,000\n~USD saved:         $0.8550\n\nTop tools by tokens saved\n  Bash    11 calls   247,500 tok      (bash-bound:git-log / :find / :ls-recursive / :ps)\n  Read     3 calls    37,500 tok      (read-clamp on 89 KB package-lock.json + 2 others)\n```\n\n~20k tokens saved per event. A dev spending 4 agent-hours a day reclaims ~$10/week. Reproduce via `CONTRIBUTING.md`'s dogfood playbook.\n\n---\n\n## 🩺 `tokenomy doctor`\n\n```\n✓ Node ≥ 20\n✓ ~/.claude/settings.json parses\n✓ Hook entries present (PostToolUse + PreToolUse + UserPromptSubmit + SessionStart)\n✓ PreToolUse matcher covers Read + Bash + Write + Edit — Read|Bash|Write|Edit\n✓ Hook binary exists + executable\n✓ Smoke spawn hook (empty mcp call) — exit=0 elapsed=74ms\n✓ ~/.tokenomy/config.json parses\n✓ Log directory writable\n✓ Manifest drift — clean\n✓ No overlapping mcp__ hook — clean\n✓ Graph MCP registration — tokenomy-graph configured in ~/.claude.json\n✓ Statusline registered — tokenomy status-line\n✓ Agent detection — claude-code, codex, cursor\n✓ Graph MCP SDK available — @modelcontextprotocol/sdk import ok\n✓ Hook perf budget — p50=5ms p95=12ms max=14ms (n=30, budget 50ms)\n✓ Graph dirty sentinel age — no pending sentinel\n✓ Raven store size — 0.0 MB\n✓ Savings log size — 1.2 MB\n✓ Update cache age — 12min old\n\n19/19 checks passed\n```\n\nEvery check has an actionable remediation hint on failure. `tokenomy doctor --fix` for routine repair.\n\n---\n\n## 🛑 Uninstall\n\n```bash\ntokenomy uninstall --purge\n```\n\nRemoves both hook entries from `~/.claude/settings.json` (matched by absolute command path), deletes `~/.tokenomy/`. Original `settings.json` remains backed up at `~/.claude/settings.json.tokenomy-bak-\u003ctimestamp\u003e`.\n\n---\n\n## 🧭 Roadmap\n\n- [x] **Phase 1.** `PostToolUse` MCP trim + `PreToolUse` Read clamp + CLI + 12-check doctor + savings log (Claude Code).\n- [x] **Phase 2.** `tokenomy analyze` — walks Claude Code + Codex CLI transcripts, replays rules with a real tokenizer.\n- [x] **Phase 3.** Local code-graph MCP server: `tokenomy-graph` stdio server. Works with both Claude Code and Codex CLI.\n- [x] **Phase 3.5.** Multi-stage PostToolUse pipeline: dedup, secret redact, stacktrace collapse, schema-aware profiles.\n- [x] **Phase 4.** `PreToolUse` Bash input-bounder.\n- [x] **Phase 4.5.** OSS-alternatives-first nudge — `find_oss_alternatives` MCP tool + Write context nudge.\n- [x] **Phase 5.** Polish — Golem output mode, statusline, prompt-classifier, `compress`, `bench`, cross-agent installers.\n- [x] **Phase 5.5.** Codex hook foothold — user-scoped `SessionStart` + `UserPromptSubmit` hooks for Golem and prompt-classifier nudges.\n- [x] **Phase 6 (0.1.x).** Raven bridge, Kratos security shield, statusline update marker, Raven in report/analyze, Golem `recon` mode, `tokenomy feedback` command, live graph freshness + cross-repo isolation + auto-update-check (0.1.3), Kratos statusline badge (0.1.4), `tokenomy diagnose` + production-hardening pass + RECON v2 (0.1.5), production-scale graph defaults (0.1.6).\n- [ ] **Phase 7.** Language breadth — Python parser plugin, richer benchmark fixtures, npm publish at 1.0.\n- [ ] **Phase 8.** Agent operating layer — rule-pack generator, compaction-time memory hygiene, workflow MCP tools, session ledgers, team-ready reports. See [docs/NEXT_FEATURES.md](./docs/NEXT_FEATURES.md).\n\n---\n\n## 🤝 Contribute\n\nDependency-light (zero runtime deps in the hot hook path; `@modelcontextprotocol/sdk` loaded dynamically; `js-tiktoken` optional peer for accurate `analyze`). Test-first.\n\n```bash\ngit clone https://github.com/RahulDhiman93/Tokenomy \u0026\u0026 cd Tokenomy\nnpm install \u0026\u0026 npm run build\nnpm test             # all green\nnpm run coverage     # c8 → coverage/lcov.info + HTML\nnpm run typecheck    # tsc --noEmit\nnpm link             # point `tokenomy` at your local build\ntokenomy doctor\n```\n\n**Guiding principles.** (1) Fail-open always — broken hook worse than no hook; never exit 2. (2) Schema invariants over trust — outputs never fabricate keys, flip types, shrink arrays. (3) Path-match over markers — uninstall identifies entries by absolute command path. (4) Measure before bragging — no \"X % savings\" claims without Phase 2 benchmark data. (5) Small + legible — a dozen lines aren't worth a 200 KB install.\n\n**Before opening a PR.** `npm test` green. Touched a rule → add passthrough *and* trim tests. Touched `init`/`uninstall` → extend the round-trip integration test. Added a config field → document it in [docs/features/configure.md](./docs/features/configure.md).\n\n---\n\n## 📜 License\n\nMIT — see [LICENSE](./LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg alt=\"Tokenomy mark\" src=\"https://raw.githubusercontent.com/RahulDhiman93/Tokenomy/main/src/assets/logo.jpg\" width=\"56\"\u003e\n\n*Save tokens. Save money.*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahuldhiman93%2Ftokenomy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahuldhiman93%2Ftokenomy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahuldhiman93%2Ftokenomy/lists"}