AI coding assistants burn through tokens fast. CLI output floods the context window. Files get re-read for no reason. Responses are verbose when they don't need to be. By the time you're deep in a task, half your context is gone.

tokonomics is a package manager for token optimization tools. It catalogs 26 open-source tools across 8 categories, installs them with one command, and lets you toggle anything on or off without breaking your workflow.

Works with Claude Code, Cursor, Copilot, Codex, Windsurf, and any MCP-compatible assistant. Zero dependencies.

Quick Start

npx tokonomics status            # See what you've got
npx tokonomics preset baseline   # Install the essentials
npx tokonomics catalog           # Browse all 26 tools

Demo

$ tokonomics status

Token Optimisations (tokonomics v0.1.0)

  Active:
    ✓ rtk              CLI filtering           60-90% input tokens
    ✓ ccusage           Measurement             no overhead
    ✓ codegraph         Code navigation MCP     57% fewer tokens

  Disabled:
    ✗ caveman           Terse output            (disabled by you)

  Built-in levers:
    compaction:     default (80%)
    thinking-cap:   default (31,999)
    .claudeignore:  found

  All tools are optional. Disable any safely — only affects token usage.

What Should I Install?

Start with baseline. Measure with ccusage. Add more when you see where the waste is.

Baseline (recommended for everyone)

tokonomics preset baseline

| Tool | What it does | Impact | |------|-------------|--------| | RTK | Filters CLI output before it enters context | 60-90% fewer input tokens | | ccusage | Measures where your tokens actually go | No overhead — just measurement |

RTK is the single highest-impact optimization — CLI output is the #1 source of token waste. ccusage gives you the numbers to measure everything else against.

Standard (add after a week on baseline)

tokonomics preset standard

Adds CodeGraph — a pre-indexed code knowledge graph via MCP. Instead of reading entire files, the AI queries a symbol graph. 57% fewer tokens, 71% fewer tool calls. Adds ~4.5K tokens/turn of MCP overhead, so best for implementation-heavy work.

Full (for power users)

tokonomics preset full

Adds Caveman (terse AI output, 65% fewer output tokens) and Context Mode (sandboxes tool output, up to 98% context reduction). These change how the AI communicates — try them after you're comfortable with the baseline workflow.

Beyond Presets

Install individual tools for specific needs:

tokonomics install codeburn        # Find 11 token waste patterns in your sessions
tokonomics install token-savior    # Persistent memory + structural navigation
tokonomics install lean-cortex     # 51+ MCP tools for fine-grained context control

Run tokonomics catalog for the full list.

Commands

tokonomics status                   Show active tools + estimated overhead
tokonomics catalog [category]       Browse all 26 tools
tokonomics install <tool|preset>    Install a tool or apply a preset
tokonomics uninstall <tool>         Remove a tool
tokonomics enable <tool>            Re-enable a disabled tool
tokonomics disable <tool>           Disable without uninstalling
tokonomics preset <name>            Apply baseline / standard / full
tokonomics benchmark                Measure token usage via ccusage
tokonomics config <key> [value]     Manage built-in levers
tokonomics help                     Show usage

Toggling Is Always Safe

Every tool is optional. Disabling anything never breaks your workflow — the only effect is more token usage.

tokonomics disable caveman      # Want verbose output for a tricky debug session
tokonomics enable caveman       # Back to terse

tokonomics disable codegraph    # Save ~4.5K tokens/turn during pure planning
tokonomics enable codegraph     # Re-enable for implementation

Under the hood:

• Skills move between ~/.claude/skills/ and ~/.claude/skills/.disabled/
• MCP servers get added/removed from settings
• Hooks use the tool's own init/deinit commands
• Env vars get set/unset in Claude Code settings

Tool Catalog

26 tools across 8 categories. Run tokonomics catalog for the live version with install status.

| Tool | Savings | License | |------|---------|---------| | rtk | 60-90% input | Apache-2.0 | | snip | 60-90% input | MIT |

| Tool | Savings | License | |------|---------|---------| | caveman | 65% output | MIT | | claude-token-efficient | ~50% output | MIT |

| Tool | Savings | License | |------|---------|---------| | codegraph | 57% tokens, 71% fewer tool calls | MIT | | codebase-memory | 10x fewer tokens | MIT | | jcodemunch | ~80% | Commercial | | code-review-graph | 8.2x average | MIT | | coderlm | varies | MIT |

| Tool | Savings | License | |------|---------|---------| | context-mode | up to 98% | Elastic 2.0 | | lean-cortex | 60-99% per file | MIT | | context-gateway | ~23% average | MIT |

| Tool | What it does | License | |------|-------------|---------| | ccusage | Token + cost tracking from session files | MIT | | codeburn | TUI dashboard + 11 waste pattern detector | MIT | | token-optimizer | Ghost token detection + quality scoring | MIT | | claude-context-optimizer | Read deduplication + budget alerts | MIT |

| Tool | Savings | License | |------|---------|---------| | token-optimizer-mcp | 95%+ | MIT | | token-savior | -77% active tokens | MIT | | codesight | 9-13x fewer tokens | MIT |

| Tool | Savings | License | |------|---------|---------| | claude-token-optimizer | 90% session start | MIT | | claude-cost-optimizer | 30-60% | MIT | | prompt-optimizer | varies | MIT |

| Lever | Command | |-------|---------| | .claudeignore | tokonomics install claudeignore | | Compaction threshold | tokonomics config compaction 50 | | Thinking token cap | tokonomics config thinking-cap 10000 | | /compact and /clear | Built into Claude Code |

Built-in Config

Manage Claude Code's optimization levers without editing JSON files:

tokonomics config show                  # Current settings
tokonomics config compaction 50         # Compact at 50% instead of 80%
tokonomics config thinking-cap 10000    # Cap extended thinking tokens
tokonomics config compaction default    # Reset to default

Requirements

• Node.js >= 18
• macOS (primary), Linux (secondary)
• Individual tools may require Homebrew, Python/pip, Go, or MCP clients

Contributing

See CONTRIBUTING.md. The short version: add a tool entry to src/catalog.js, test the cycle, submit a PR with the tool's URL, savings data, and license.

License

MIT