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.21.1 — Multi-daemon spam fix — dozens of idle icmg.exe no more. On busy multi-user servers, concurrent hook calls raced ensureDaemon(): every spawned rule-daemon created the same named pipe successfully (PIPE_UNLIMITED_INSTANCES, no FILE_FLAG_FIRST_PIPE_INSTANCE, no cross-process lock) and then parked in ConnectNamedPipe forever — accumulating dozens of ~2-3 MB icmg.exe processes per user. Fixed belt-and-braces: RuleDaemon::acquireSingleton() per-user cross-process lock (Windows: named mutex Local\icmg-rule-daemon-<user>; POSIX: flock on ~/.icmg/rule-daemon.lock) required by run() — the losing daemon exits quietly — plus FILE_FLAG_FIRST_PIPE_INSTANCE so a raced second daemon can never share the pipe even if the mutex path regresses. One-time cleanup on affected servers: taskkill /F /IM icmg.exe, then update. 2419/2419 tests ✓.
• v2.21.0 — Brain + token trio: session-aware recall delta, contradiction sentinel, adaptive recall depth. When the session TTL dedup suppresses memory nodes you already saw this session, recall now emits a single stdout line [N prior memories still apply: #ids] instead of silently dropping the reference — the agent keeps the pointer without re-paying the tokens for full bodies. New icmg memory-health --contradictions scans the memory store for node pairs that overlap heavily (Jaccard ≥ 0.6 default, --jaccard-min to tune) yet disagree — a negation marker on one side or a conflicting key=value fact; flag-only (never deletes), strongest-first, capped at --max (default 25), each hit suggesting the existing bi-temporal fix icmg memory invalidate <old> --by <new>. Verified live on a 31k-node store: caught real icmg_version and prefix conflicts at 100% overlap. And recall --adaptive sizes recall depth with the deterministic v2.20 intent classifier — simple task = 3 results, unknown = 7, complex = 12; an explicit --limit always wins. All deterministic, no LLM. 2416/2416 tests ✓.
• v2.20.0 — Model-era capability pack. As frontier models grew 1M-token windows and extended-thinking budgets, the token lever shifted from how much to trim toward cache-hit rate and reasoning-token cost. Five shipped: pack --cache-aware classifies sections (conventions/rules/graph/files = stable; task/recall/diff = volatile), orders stable-first, and wraps ONLY the byte-stable prefix (FNV-1a prefix_hash makes drift visible) so prompt caching (-90% cost / -85% latency) actually hits. MCP tool annotations — every tools/list entry now carries readOnlyHint/destructiveHint/idempotentHint/openWorldHint so an agent host can plan safely. New icmg_graph_query MCP tool: deterministic multi-hop structural search (blast_radius | who_calls | path_between). pack --effort-hint recommends an extended-thinking budget from task intent + graph fan-out. token-ledger stats/otel report cache-hit ratio + honest cost estimate, OpenTelemetry GenAI-style JSON offline. 2406/2406 tests ✓.
• v2.19.1 — icmg run destructive-op guard goes argv-aware — no more false positives. The guard gating rm -rf/Remove-Item/DROP TABLE used a whole-string substring scan, so any command merely containing the pattern — grep 'rm -rf' notes.txt, a path like src/farm/ — was wrongly refused, and a --yes/ICMG_ASSUME_YES=1 bypass on an auto-wrapped child never reached the icmg process. Now detection is argv-aware (isDestructiveArgv): flags only when the leading verb is the destructive tool (skipping env VAR=val/sudo prefixes), honors a leading ICMG_ASSUME_YES=1/FORCE=1 env-prefix as explicit bypass intent. psql -c "DROP TABLE t" still caught; git rm --cached no longer trips. 10 new tests, TDD.
• v2.19.0 — graphify-parity ingest & graph pack. Five gaps from the graphify landscape research, closed: icmg ingest now reads Office documents (.docx paragraphs + table cells, .xlsx all sheets) and transcribes audio/video (.mp4 .mp3 .wav … via faster-whisper sidecar, graceful when the dep is absent); .sql/.ddl files feed the code graph (CREATE TABLE→table nodes, FOREIGN KEY→references: edges); HCL/Terraform extractor (.tf/.hcl/.tfvars blocks → nodes, module.source → dependency edges); and icmg init --all-tools/--strict wires every detected host CLI (Cursor, Windsurf, Zed, Codex, Copilot, OpenCode, Gemini, Amp) in one run. 34 new tests; 2364 C++ + 15 Python green.

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