Open-source token consumption optimization engine. One command. Attach once. Then it tracks, audits and advises forever, and auto-compresses before you burn tokens.

npm install -g skitoken gives you the tokenly command. Local-first. Private. Free. MIT licensed.

The problem

Developers now run several AI tools at once: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, opencode, often simultaneously. Two facts hold in 2026:

• Subscriptions stack up fast: $150-400+/month across tools, $1,800-4,800/year, with pricing models still shifting under you.
• MCP servers hide a token tax: tool schemas load into context before a single message is processed. Verbose outputs and multi-turn call history pile on after every call. A naive setup can burn 30-50% of your context before real work starts.

Existing tools either track usage or optimize payloads. None do both, none attach automatically, and none compress your sessions for you. Tokenly does all three.

What Tokenly does

1. Attach with one command

tokenly install

Detects the AI clients on your machine, registers the Tokenly MCP server in each, installs hooks, and sets auto-start. Global everywhere, zero per-project config.

2. Track in one ledger

Every token and cost event from every tool lands in one local SQLite database. Full data ownership, no cloud, no telemetry.

3. Audit and advise like a financial advisor for AI spend

tokenly audit    # cross-tool usage and cost breakdown
tokenly advise   # concrete savings, for example "route X to mistral-small"
tokenly budget 50  # monthly cap with over-budget alerts

4. Auto-compress before you hit the ceiling

Sessions compress automatically at 60k tokens (default trigger), with a hard ceiling at 80k. Older turns fold into a compact digest, the last 5 turns stay verbatim, and critical facts are pinned so nothing important is lost.

Install

Requirements: Node.js 22.5 or newer (uses the built-in node:sqlite, zero native dependencies).

# global install (recommended)
npm install -g skitoken

# or run without installing
npx skitoken install

# or build from source
git clone https://github.com/AbduljabbarBXR/Tokenly.git
cd Tokenly
npm install
npm run build
npm link

Then attach:

tokenly install

Quickstart

# log usage from any tool
tokenly track --tool cursor --model claude-sonnet-4 --in 5000 --out 1200 --project myapp
# recorded cursor claude-sonnet-4: 5.0k in / 1.2k out, $0.0330

# see the live gauges
tokenly status

# cross-tool report for the last 30 days
tokenly audit

# get deterministic savings advice
tokenly advise

# set a monthly budget in USD
tokenly budget 50

Live status bars

tokenly install adds a two-bar gauge to every new terminal: token usage and compression level, live.

Usage     [############........................] 30%   (green)
Compress  [###############.....................] 38%   (green)
tokenly ctx=30.0k/100.0k state=ok

| Zone | Meaning | |------|---------| | Green at the start | Healthy headroom, state ok | | Orange in the middle | Past the 60k trigger, compression advised, state warm | | Red when full | Past 80k/90%, compression begins automatically, state COMPRESSING |

Run tokenly status any time for the live view. All thresholds are configurable (see Configuration). New shells show the bars on startup; remove the two tokenly lines from ~/.bashrc to disable.

CLI reference

| Command | What it does | |---------|--------------| | tokenly install | Detect clients, register MCP server, install hooks, enable autostart | | tokenly track --tool T --model M --in N --out N [--project P] | Log one usage event into the ledger | | tokenly audit | Cross-tool usage and cost report, last 30 days, split by tool and model | | tokenly advise | Deterministic recommendations: overpay detection, compression savings, budget alerts | | tokenly budget [amount] | Set the monthly budget in USD, or show spend versus budget | | tokenly compress [session] | Evaluate and apply context compression for a session | | tokenly status | Render the live usage plus compression gauges | | tokenly mcp | Start the MCP server over stdio | | tokenly version | Print the version |

MCP server

One server, 8 tools, stdio transport. Any agent or MCP client can call them for deterministic answers about usage, cost, and compression. No guessing about your bill.

| Tool | Purpose | Key params | |------|---------|------------| | tokenly.track | Log a usage event | toolName, model, inputTokens, outputTokens, project? | | tokenly.audit | 30-day usage and cost breakdown | none | | tokenly.advise | Optimization recommendations as JSON | none | | tokenly.status | Live context tokens, headroom, compress state | none | | tokenly.compress | Compress a session now | sessionId, turns?, pinFacts? | | tokenly.budget | Set or check monthly budget | amountUSD? | | tokenly.models | Supported models with pricing and tier | none | | tokenly.count_tokens | Estimate tokens plus cost, suggest cheaper model | prompt, model |

Add it to any client manually:

{
  "mcpServers": {
    "tokenly": {
      "command": "node",
      "args": ["/path/to/skitoken/dist/mcp.js"]
    }
  }
}

tokenly install writes this for you in every client it detects.

Cursor hooks: when Cursor is detected, Tokenly adds an observational beforeSubmitPrompt hook in ~/.cursor/hooks.json. It only reads context size and never blocks.

Compression design

| Setting | Default | Meaning | |---------|---------|---------| | compress.trigger_tokens | 60,000 | Context crossing this is compressed | | compress.aggressive_tokens | 80,000 | Hard ceiling, compress immediately | | compress.keep_recent_turns | 5 | Turns kept verbatim after compression | | compress.pin_facts | true | Critical facts survive compression |

What happens on compress: earlier turns fold into a structured digest ([Tokenly-compressed digest: N earlier turns summarized. Key facts: ...]), recent turns stay untouched, the session record updates with the smaller context size, and a ledger entry records the tokens saved. The gauges drop back to green.

Beyond compression, the roadmap automates: tool-search schema loading (80-95% schema cut), code-execution consolidation (80-90%), TOON output compression (50-70%), semantic caching (80%+ on repeats), and model routing (up to 60%).

Configuration

Config file: ~/.config/tokenly/config.json (override dir with TOKENLY_CONFIG_DIR). Data: ~/.local/share/tokenly/tokenly.db (override with TOKENLY_DATA_DIR).

| Env var | Default | Meaning | |---------|---------|---------| | TOKENLY_TRIGGER_TOKENS | 60000 | Compression trigger | | TOKENLY_AGGRESSIVE_TOKENS | 80000 | Hard compression ceiling | | TOKENLY_KEEP_RECENT | 5 | Turns kept verbatim | | TOKENLY_PIN_FACTS | true | Pin facts through compression | | TOKENLY_ROUTING | true | Enable model routing advice | | TOKENLY_CACHE_TTL | 300 | Tool-output cache lifetime (s) | | TOKENLY_CONTEXT_WINDOW | 100000 | Context window the gauges measure against | | TOKENLY_DATA_DIR | ~/.local/share/tokenly | Ledger location | | TOKENLY_CONFIG_DIR | ~/.config/tokenly | Config location |

Privacy

Everything stays on your machine. SQLite ledger, local config, no accounts, no telemetry, no cloud calls. Uninstall removes tracking; your data files remain yours to delete.

Tech stack

TypeScript on Node 22, node:sqlite ledger (zero native deps), official @modelcontextprotocol/sdk, zero-dependency CLI parser, Cursor hooks.json plus opencode MCP integration. 25 unit tests plus end-to-end CLI and MCP verification.

Roadmap

• v0.1 (shipped): install/track/audit/advise/budget/compress/status CLI, SQLite ledger, 13-model cost math, MCP server with 8 tools, live gauges with autostart, opencode auto-attach plus Cursor hooks.
• v0.2: model routing engine, semantic caching, TOON output optimization, tool-search schema loading.
• v0.3: code-execution consolidation, raw-API transparent proxy, Antigravity/Windsurf/Codex/Claude Code adapters, self-hosted dashboard.

Development

git clone https://github.com/AbduljabbarBXR/Tokenly.git
cd Tokenly
npm install
npm run build   # compile src/ to dist/
npm test        # 25 unit tests

Project layout: src/ (config, costs, ledger, compression, advice, statusbar, cli, mcp, install, status, hooks), test/ (unit tests), assets/ (logo, diagrams, badges), dist/ (build output, gitignored).

Uninstall

npm uninstall -g skitoken
# remove autostart: delete the two tokenly lines from ~/.bashrc
# optional: rm -rf ~/.local/share/tokenly ~/.config/tokenly

Supported tools

| Client | Integration | Status in v0.1 | |--------|-------------|----------------| | Cursor (IDE) | hooks.json observer plus MCP | Working | | Cursor CLI | Partial hooks | Tracking | | Claude Code | Hooks plus MCP config | Tracking | | opencode | MCP auto-attach | Working | | Antigravity | MCP / CLI | Via MCP | | Windsurf | MCP / CLI | Via MCP | | Codex CLI | Session log parsing | Tracking | | Any MCP client | MCP server discovery | Working | | Raw API (any provider) | Unified ledger via track | Working, transparent proxy in v0.3 |

Supported providers and models

| Model | Provider | Input / 1M | Output / 1M | Tier | |-------|----------|-----------|------------|------| | gpt-5 | OpenAI | $1.25 | $10.00 | frontier | | gpt-4o | OpenAI | $2.50 | $10.00 | frontier | | gpt-4o-mini | OpenAI | $0.15 | $0.60 | budget | | gpt-4.1-mini | OpenAI | $0.40 | $1.60 | budget | | claude-opus-4 | Anthropic | $15.00 | $75.00 | frontier | | claude-sonnet-4 | Anthropic | $3.00 | $15.00 | frontier | | claude-haiku-4.5 | Anthropic | $1.00 | $5.00 | budget | | gemini-2.5-pro | Google | $1.25 | $10.00 | mid | | gemini-2.5-flash | Google | $0.30 | $2.50 | budget | | deepseek-chat | DeepSeek | $0.27 | $1.10 | budget | | deepseek-reasoner | DeepSeek | $0.55 | $2.19 | mid | | mistral-large | Mistral | $2.00 | $6.00 | mid | | mistral-small | Mistral | $0.10 | $0.30 | budget |

Pricing is compiled into the cost engine so audits and advice work offline. Validate against live provider pricing for billing decisions.

License

MIT. See LICENSE.

Local-first. Private. Free.

Links: npm | GitHub | Tawakkul Labs