Icemage (icmg)

Stop burning tokens. Stop losing context. Ship faster.

A single binary that makes Claude Code, Cursor, and every other AI coding assistant 70–90% cheaper to run — without dumbing them down.

If you've ever watched 30K tokens evaporate on a single file read, paid for "thinking" you didn't need, or re-explained the same project context after /clear for the fifth time today — this is for you.

🟢 Why Icemage

AI assistants are powerful but wasteful by default. Every time the AI opens a file, runs a command, or starts a new chat, it re-reads context it has seen many times and dumps full output into the conversation. Icemage sits quietly in the background and trims the noise before it ever reaches the AI:

• Long files → only the relevant slice
• Noisy command output → just the parts that matter
• Web pages → cached + summarised
• Past decisions → remembered across sessions so the AI doesn't ask twice
• Repeated work → results reused instead of recomputed

The AI keeps its full intelligence. Your wallet keeps more of its money.

📊 Headline numbers

✨ What's new

• v2.18.0 — Filter-coverage telemetry goes proactive + a stray-nul daemon bug fix. icmg savings now self-diagnoses filter-coverage gaps (the command verbs burning the most raw output while Tkil saves the least — born from two same-week reactive discoveries: git log 7-char hash miss and gh api 0% filtered). icmg learn turns each gap into an actionable filter recommendation, and icmg savings --json exposes a filter_gaps array for badge/CI tooling. Plus a real bug fix: RuleDaemonClient::ensureDaemon() spawned the daemon via a cmd.exe-specific >nul 2>nul redirect through safeExecShell(), which prefers bash — so on any Windows box with Git installed, nul was treated as an ordinary filename and a stray nul file was created in the current directory on every icmg invocation. Fixed with a plain-argv spawn, plus an audit that fixed three more safeExecShell sites with the same hazard (new bash-safe core::suppressStderr()). 2340/2340 tests ✓.
• v2.17.0 — gh api JSON output had zero Tkil filter coverage. Found while investigating why a release/CI-heavy session's "Command filter" savings showed only ~17% (much lower than the 60-99% typical for git/grep/build commands) — gh api <endpoint> had no CmdType at all, so every call fell through to CmdType::Default and passed through raw. Production telemetry: a single gh api gists/<id> call emitted 36,741 raw bytes with filtered_bytes IDENTICAL to raw (0% saved). New GhFilter minifies gh api's default pretty-printed JSON (2-space indent) when it round-trips as valid JSON — a strictly lossless transform (the parsed value is byte-for-byte identical before/after), typically cutting 30-50% of bytes. Non-JSON gh output (gh pr view tables, plain-text errors) and malformed/truncated JSON both fall through to raw passthrough unchanged. New CmdType::Gh + detector patterns for gh api/pr/issue/release/run/repo/gist/workflow. TDD: 5 new tests first, all green. Verified live against a real gh api call. 2309/2309 tests ✓.
• v2.16.0 — Fix icmg savings daily-history bug (user-reported). The "Daily real-token history" block (console + --html) aggregated a DIFFERENT source than the headline "Real API tokens" number — it shelled out to context-budget --all-sessions, bucketing by transcript-file MTIME with a TEXT-LENGTH ESTIMATE, while the headline reads token_ledger directly. Symptom matched exactly: busy multi-day sessions vanished (only the file's last-mtime day got credited) and shown days were off by 2-1000x. Fixed with aggregateTokenLedgerByDay(), a pure function that buckets token_ledger itself by each row's own local-calendar day — now both numbers always reconcile. TDD: 5 new tests first, including a regression guard for the exact reported symptom. 2304/2304 tests ✓.
• v2.15.2 — Search-accuracy hardening part 2: 2 more root-cause fixes, plus a stale-headline-numbers correction. Continuing the v2.15.1 telemetry investigation: powershell -File <temp>.ps1 wrappers never got unwrapped (3511 production invocations, ~38% filtered) — fixed with a best-effort read of the script's content at classification time. GitFilter's commit-hash regex required 8-40 hex chars, but git log --oneline's default short-hash is 7 chars, so the truncation cap was structurally unreachable — fixed with a one-character regex change. 2298/2298 tests ✓.
• v2.14.0 — Token-efficiency arsenal: seven new levers to cut recurring spend. icmg run --nano collapses build/test/lint diagnostics to one dense file:kind:code:line per entry (gcc/clang/rustc + MSVC), ~95% on repeat builds. icmg run --gist gives a one-line, domain-aware TL;DR of command output (12 passed, 3 failed. first fail: user.rs:45), sub-millisecond, no LLM. icmg learn mines the persistent commands table across sessions to flag consistently-noisy commands and recommend a tighter mode; ICMG_AUTO_ROUTE=1 then auto-applies --nano/--gist to them (opt-in). icmg transcript cost quantifies re-send amplification — an entry at position i of N is paid for (N−i) times — and ranks the hotspots to compact first. icmg mcp audit measures the per-turn token cost of every MCP tool schema and flags oversized ones. Recall gains an opt-in hot/warm/cold tier tie-breaker (ICMG_RECALL_TIER_BOOST) implemented as a stable tie-breaker, so it provably cannot regress well-separated rankings. +34 tests, ctest 100% (Windows).

curl -fsSL https://raw.githubusercontent.com/ncmonx/icemage/main/scripts/install.sh | sh

One line — Windows (PowerShell):

irm https://raw.githubusercontent.com/ncmonx/icemage/main/scripts/install.ps1 | iex

The installer grabs the latest release, verifies its SHA-256, and drops icmg into your bin dir (~/.local/bin on Linux/macOS, %USERPROFILE%\bin on Windows). Pin a version with ICMG_VERSION=2.1.0, or change where it lands with ICMG_BIN_DIR.

1. Download the latest archive from the Releases page — icmg-<version>-win-x64.zip for Windows, icmg-<version>-linux-x64.tar.gz for Linux, icmg-<version>-macos-arm64.tar.gz for macOS.
2. Extract it into any folder.
3. Add that folder to your PATH so icmg is available everywhere.

Then, in your project terminal:

icmg init

That's it. The next time you launch Claude Code (or Cursor / Cline / Windsurf — see below), Icemage will quietly start trimming tokens.

🧰 What you'll actually use day-to-day

After install, the only command most people type is icmg init once per project. Everything else happens automatically. A few useful commands when you want to peek under the hood:

For the full menu run icmg --help.

🤖 Works with

• Claude Code (primary target — best-tested)
• Cursor — drop-in via the same hooks
• Cline, Windsurf, OpenCode — same approach, may need a small config nudge
• Anything that exposes hooks or MCP — the MCP server bundled with Icemage is reusable

🛡️ Safety + privacy

• 100 % local. Everything Icemage knows about your projects lives in a small SQLite database next to your code. Nothing is sent to a remote server — not the project name, not the file paths, not the recalled snippets.
• No telemetry. Icemage doesn't phone home.
• Open source. Elastic License 2.0 - source-available. Free to use, copy, modify, and self-host. The one limitation: you may not offer icmg to third parties as a hosted or managed service. Everything else is fair game. Audit the binary, the release notes, and the file structure freely. Source code is held privately to keep the bug surface manageable for a solo maintainer — public reports + private fixes is the operating model.
• Tamper-evident. Every release ships with a sha256 sidecar so you can verify the binary you downloaded.

🩹 Honest limits

• Windows + Linux only for prebuilt binaries today. macOS users currently need to wait for a self-hosted runner build (planned).
• First-time install on Windows with strict antivirus can be slow until you let Icemage run once. After that it's fast.
• Not a replacement for the AI. Icemage is a token-trimming layer — it doesn't write code for you and it doesn't make a bad AI smart.

💖 Support

If Icemage saved you a few hours or a few dollars and you want to send a small thank-you, both routes work:

• GitHub Sponsors
• Ko-fi tip jar

All revenue goes straight into more releases — there is no team behind this, just one maintainer and a long backlog of "make AI agents less wasteful" ideas.

❓ FAQ

Does Icemage send my code anywhere? No. Everything is local. The only network call is when you ask Icemage to update itself or fetch a URL through icmg fetch.

Can my company use it? Yes - Elastic License 2.0: source-available, free for any use including commercial, self-hosting, and modification. The only limit is reselling icmg itself as a hosted/managed service. Want a private support arrangement or custom build? Open a sponsorship.

Why is the source code repo private? One maintainer, no security team. Public bug reports + private fixes lets me ship hotfixes the same day without telegraphing exploitable details. The release binaries and reproducible build hash are still public.

Does it slow my AI down? No. Trimming happens before the AI reads anything, so the AI sees a smaller, cleaner version of the same context. End-to-end interactions get faster, not slower.

Where are the savings stored? In .icmg/data.db inside each project (small SQLite file). Run icmg savings to see the breakdown.

How do I report a bug or ask for a feature? Open an issue at the GitHub issues page. Real-world reproductions with icmg savings --json attached get triaged fastest.

🌟 Star history

📜 License

Elastic License 2.0 - source-available. Free to use, copy, modify, and self-host. The one limitation: you may not offer icmg to third parties as a hosted or managed service. Everything else is fair game.

📚 Other docs

• CHANGELOG.md — full version history
• SECURITY.md — vulnerability reporting
• NOTICE — third-party attributions