convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
ncmonx

Icemage

ncmonx/icemage

Compressão inteligente de contexto para coding agents — 70-90% menos tokens

Ver no GitHub
BomPluginScore · de 0 a 100

Motor de contexto eficiente em tokens para agentes de IA de codificação. Reduz custos de API em 70-90% comprimindo leitura de arquivos, saída de comandos e contexto de projeto sem perder qualidade. Inclui memória multi-sessão, busca de histórico e 41 ferramentas MCP prontas para uso.

Instalação

$npx convez-ai ncmonx/icemage

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
85%
Último commit
há 1 dia
Versão
v2.30.3
Issues abertas
5
Contribuidores
2

Casos de uso

  • Reduzir custos de tokens em agentes de IA (Claude, Cursor) durante desenvolvimento
  • Manter contexto de projeto persistente entre múltiplas sessões sem re-explicação
  • Processar arquivos grandes e saída de builds/testes sem desperdício de tokens

Veredito

Ferramenta sólida e bem-testada (1818 testes) para otimizar custos de tokens em workflows de coding assistants. Produção-pronta com licença Elastic 2.0 e suporte ativo, mas requer integração local como MCP server — ideal para times que usam Claude/Cursor em larga escala.

README

A tradução para o português deste README ainda está na fila.

Icemage (icmg)

release downloads last-commit tests mcp tools commands license OpenSSF Scorecard sponsor ko-fi

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

MetricTypicalBestSince
File-read savings70 – 85 % fewer tokensup to 92 %v0.5
Test / build output60 – 80 % shorterup to 90 %v0.5
Multi-file UI propagation (style-clone)30 – 50× cheaperup to 98 %v1.22.0
Cross-project bundle (port)8 – 12× cheaperup to 95 %v1.24.0
Compressed-Write (AI emit diff)70 – 95% fewer tokensup to 98 %v1.25.0
Web-fetch reduction70 – 90 % smallerup to 95 %v0.4
Repeat-context recallnear-zero, < 5 ms cached—v1.21.8
Past-chat full-text search< 10 ms across months—v1.21.7
Graph symbol lookup256-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 % smallerup to 90 %v1.30.0
Auto-thinking suppress (trivial prompts)~1500 tok / call saved—v1.30.0
Sayless-auto (long-prose replies)60 – 75 % compressup 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 callsprivacy-firstv1.31.0
Smart router (REGEX vs LLM_LOCAL vs CACHE)<100 us p99hot-path forced regexv1.31.0
HTTP streaming download (model fetch + SHA256)400 MB - 2 GB safe-verifytamper-detectv1.31.0
icmg git wrapper (single ergonomic entry)Tkil-filtered + safety-gatedenforces icmg-FIRSTv1.31.0
Python-free core (PRECOMPACT_PY dropped)-200-500 ms boot savedsingle-binaryv1.31.0
pack --rerank (LLM-reorder memory hits)opt-in warm-pathrouter-gatedv1.32.0
PreCompact LLM summary (warm-pool Qwen 0.5B)<15 s coldregex fallback alwaysv1.32.0
icmg compact-bg (proactive memory worker)<3 s warmmanual + future hookv1.32.0
Smarter local AI memorymulti-prompt safeno overflowv1.32.0
Code graph viz + report (icmg graph viz)interactive D3 + god-nodes—v1.71.0
Secret scanner (icmg scan)21 detectors, CI-gateredact-by-defaultv1.68.0
MCP server hardening (token + rate-limit + path-guard)abuse / RCE-safe—v1.72.0
Post-compact memory re-anchorrules survive compactionauto on initv1.73.0
Scripted-safe icmg run (non-interactive guard)no hang on destructive--yes/env opt-inv1.74.0
Clean self-upgrade (idempotent Defender step)no phantom B: drive popup--no-defender opt-outv1.75.0
Encryption-at-rest (icmg encrypt, SQLCipher AES-256)opt-in full-DB encryptBM25 recall intactv1.76.0
Hot recall cache (RAM, daemon-shared)< 5 ms repeat recallself-governing RAMv1.77.0
Cost per AI sessiondown 70 – 90 % vs. rawup to 95 %—

✨ What's new

  • v2.5.0 - Memory recall grew up: citable, time-aware, and disclosure-first — plus a privacy redactor and a store that tags itself. A batch of recall/memory UX upgrades. icmg recall now prints citable results by default ([score] #id <icon> topic) so you can reference a specific memory by id, and a typed icon tells decision/fix/note apart at a glance. New views: recall --index then recall --get <id> for progressive disclosure (skim a compact index, then pull the full node only when you need it — a real context saver), recall --timeline for a chronological day-grouped view (newest first), and recall --by file to bucket memories by the source file they mention. store gained two safeguards: a <private>…</private> redactor that strips secrets before they are ever persisted, and automatic keyword derivation (stopword-filtered, deduped, capped) when you omit --kw, so recall stays sharp without manual tagging. wake-up now shows a typed-icon legend, per-decision icons, and a token-cost footer. And two operability wins: icmg serve exposes GET /api/health (status / uptime / db / counts / version JSON) and icmg install does smart version caching — it skips a reinstall when the running and installed versions already match (--force to override, --status to inspect). Full automated suite passes (1818 checks).
  • v2.4.2 - icmg run now works on plain Windows (no git-bash) — plus graph-precision and store-latency fixes. The headline: icmg run "<command>" was completely broken on Windows machines without git-bash/MSYS, returning CreateProcess failed: 2 for shell lines and bare built-ins/cmdlets. It relied on CreateProcess's PATH search, which misses PowerShell under System32\WindowsPowerShell\v1.0 and the Store pwsh alias; it now resolves the shell to a full absolute path and falls back through PowerShell for builtins/cmdlets, so an entire platform configuration goes from broken to working. Two more: the code graph no longer creates dozens of false calls edges when a callee name is defined in many files (common names like run/get/value used to fan out and inflate unrelated files' PageRank) — a name resolving to more than a few definitions is now left unlinked. And the memory-store duplicate check, which scanned the entire corpus on every store (O(N) word-set Jaccard), is bounded to the most-recent candidates plus a hoisted tokenizer and a subprocess-free git-sha read, so store latency stops growing with corpus size. Full automated suite passes (1763 checks).
  • v2.4.1 - icmg run "<shell line>" works again — pipes, &&, and redirects no longer break. Two long-standing bugs in how icmg run handled a single quoted command string. A whole-command token like icmg run "echo hi" was being re-quoted, so the underlying bash -c saw "echo hi" as one word and reported command not found; and a piped command like icmg run "ls | grep x" had its | split into a literal argument fed to ls (cannot access '|'). Both are fixed: a single command token is now treated as a verbatim shell line, and any command containing an unquoted shell operator (|, &&, ;, >, `, $(…)) routes through the shell instead of argv-exec — for both the buffered and --stream paths. Quoted operators (grep 'a|b' f) stay literal and take the fast argv-safe path. Full automated suite passes (1755 checks).
  • v2.4.0 - The code graph now ranks by PageRank — and you can steer it at your task. icmg's graph views ranked files by raw degree (a 1-hop edge count that lets bundled headers dominate). They now rank by PageRank: importance propagates transitively (a symbol referenced by important symbols outranks one referenced by many trivial ones — the ranking aider and RepoGraph use), and each edge is confidence-weighted so a structural inherits edge carries more pull than a name-based calls. Two ways to make it task-aware: icmg graph skeleton --for "<task>" and icmg graph recent --for "<task>" seed a Personalized PageRank from the task's terms so the most relevant code surfaces first, and icmg pack "<task>" --pr ranks the bundle's mentioned files the same way (opt-in; the default pack path stays fast — no full-graph load). The views are also clean by default: third_party/vendored files, sibling projects that leaked in through cross-project edges, and test files are filtered out (--include-vendored / --all-paths / --tests bring them back), so a skeleton reads as a map of your production code instead of bundled headers. Pure algorithm, no new dependency. Full automated suite passes (1750 checks).
  • v2.3.1 - The B:/ "cannot find drive" popup killed at the source, plus a self-enforcing memory gate that actually fires. Two fixes born from real friction. The modal B:/ "insert disk" popup (and its beep) that flashed during icmg recall/context under git-bash is gone at the root: MSYS's path-converter was rewriting cmd.exe flags that look like POSIX paths into drive paths (/B → B:\), and the nonexistent B: drive made cmd raise a modal dialog — icmg now sets MSYS_NO_PATHCONV=1 in its own process environment so child shells pass flags verbatim and the popup is never created (not merely dismissed after the fact, which always raced and flashed). And the post-change ritual gate — meant to nudge a store+wflog after you edit code — was misfiring on every turn because its recorder never ran: a missing newline in the generated Bash hook (fi and out= fused into fiout=) syntax-errored the whole hook, and even when it ran it inspected only the first token of a command starting literally with icmg , so RAW=1 icmg store (env prefix) and icmg store && icmg wflog (chained) were never recorded. Both are fixed with a pure, unit-tested command-line parser that strips env-var prefixes and scans every &&/||/;/| segment. Full automated suite passes (1726 checks).
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:

Want toType
See how much you saved this monthicmg savings
See a chart in the terminalicmg savings --ascii
Recall a past decision in this projecticmg recall "<question>"
Recall something from another projecticmg cross-recall "<question>"
Wake-up briefing for a fresh sessionicmg wake-up
Update Icemage in placeicmg update --apply
Health-check the installicmg doctor

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:

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

Ver o original no GitHub

Bom para

Relacionados