<p align="center"> <img src="assets/logo.svg" alt="Icemage" width="160"/> </p>

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.

<p align="center"> <!-- 30-second demo. Regenerate: `vhs assets/demo.tape` (see assets/demo.tape header), commit assets/demo.gif, then uncomment the <img> below. --> <!-- <img src="assets/demo.gif" alt="icmg in action — savings, one-shot find, slim context" width="760"/> --> </p>

---

🟢 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

| Metric | Typical | Best | Since | |---|---|---|---| | File-read savings | 70 – 85 % fewer tokens | up to 92 % | v0.5 | | Test / build output | 60 – 80 % shorter | up to 90 % | v0.5 | | Multi-file UI propagation (style-clone) | 30 – 50× cheaper | up to 98 % | v1.22.0 | | Cross-project bundle (port) | 8 – 12× cheaper | up to 95 % | v1.24.0 | | Compressed-Write (AI emit diff) | 70 – 95% fewer tokens | up to 98 % | v1.25.0 | | Web-fetch reduction | 70 – 90 % smaller | up to 95 % | v0.4 | | Repeat-context recall | near-zero, < 5 ms cached | — | v1.21.8 | | Past-chat full-text search | < 10 ms across months | — | v1.21.7 | | Graph symbol lookup | 256-slot in-RAM cache | — | v1.21.8 | | First-prompt warmup | < 1 s | — | v1.18 | | Cold build time (icmg itself) | ~50 % faster (20 min → 9-10 min) | — | v1.26.0 | | MCP response filter (verbose plugins) | 50 – 80 % smaller | up to 90 % | v1.30.0 | | Auto-thinking suppress (trivial prompts) | ~1500 tok / call saved | — | v1.30.0 | | Sayless-auto (long-prose replies) | 60 – 75 % compress | up to 85 % | v1.30.0 | | Service auto-start (UserPromptSubmit) | 0-touch warm-up | — | v1.30.0 | | Path ambiguity warning (icmg context) | wrong-file lookups → loud | — | v1.29.0 | | rg-wrapper + brace glob (icmg grep/files) | flag-mirror, {a,b} expand | — | v1.29.0 | | Local AI model (built-in, opt-in) | 0 cloud calls | privacy-first | v1.31.0 | | Smart router (REGEX vs LLM_LOCAL vs CACHE) | <100 us p99 | hot-path forced regex | v1.31.0 | | HTTP streaming download (model fetch + SHA256) | 400 MB - 2 GB safe-verify | tamper-detect | v1.31.0 | | icmg git wrapper (single ergonomic entry) | Tkil-filtered + safety-gated | enforces icmg-FIRST | v1.31.0 | | Python-free core (PRECOMPACT_PY dropped) | -200-500 ms boot saved | single-binary | v1.31.0 | | pack --rerank (LLM-reorder memory hits) | opt-in warm-path | router-gated | v1.32.0 | | PreCompact LLM summary (warm-pool Qwen 0.5B) | <15 s cold | regex fallback always | v1.32.0 | | icmg compact-bg (proactive memory worker) | <3 s warm | manual + future hook | v1.32.0 | | Smarter local AI memory | multi-prompt safe | no overflow | v1.32.0 | | Code graph viz + report (icmg graph viz) | interactive D3 + god-nodes | — | v1.71.0 | | Secret scanner (icmg scan) | 21 detectors, CI-gate | redact-by-default | v1.68.0 | | MCP server hardening (token + rate-limit + path-guard) | abuse / RCE-safe | — | v1.72.0 | | Post-compact memory re-anchor | rules survive compaction | auto on init | v1.73.0 | | Scripted-safe icmg run (non-interactive guard) | no hang on destructive | --yes/env opt-in | v1.74.0 | | Clean self-upgrade (idempotent Defender step) | no phantom B: drive popup | --no-defender opt-out | v1.75.0 | | Encryption-at-rest (icmg encrypt, SQLCipher AES-256) | opt-in full-DB encrypt | BM25 recall intact | v1.76.0 | | Hot recall cache (RAM, daemon-shared) | < 5 ms repeat recall | self-governing RAM | v1.77.0 | | Cost per AI session | down 70 – 90 % vs. raw | up to 95 % | — |

✨ What's new

• 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.
• 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 ✓.

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.

<details> <summary>Prefer a manual download?</summary>

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.

</details>

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:

| Want to | Type | |---|---| | See how much you saved this month | icmg savings | | See a chart in the terminal | icmg savings --ascii | | Recall a past decision in this project | icmg recall "<question>" | | Recall something from another projec