Open-source token consumption optimization engine. One command. Attach once. Track, audit, advise and auto-compress across every AI tool.
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.
Developers now run several AI tools at once: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, opencode, often simultaneously. Two facts hold in 2026:
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.
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.
Every token and cost event from every tool lands in one local SQLite database. Full data ownership, no cloud, no telemetry.
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
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.
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
# 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
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.
| 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 |
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.
| 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%).
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 |
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.
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.
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).
npm uninstall -g skitoken
# remove autostart: delete the two tokenly lines from ~/.bashrc
# optional: rm -rf ~/.local/share/tokenly ~/.config/tokenly
| 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 |
| 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 | $1.25 | $10.00 | mid | |
| gemini-2.5-flash | $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.
MIT. See LICENSE.
Local-first. Private. Free.
Links: npm | GitHub | Tawakkul Labs
FAQs
Open-source token consumption optimization engine. One command. Attach once. Track, audit, advise and auto-compress across every AI tool.
We found that skitoken demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.