{"id":49680216,"url":"https://github.com/ncmonx/icm-graph","last_synced_at":"2026-05-29T05:00:53.647Z","repository":{"id":356004291,"uuid":"1230572205","full_name":"ncmonx/icm-graph","owner":"ncmonx","description":"Token-efficient context CLI for Claude Code, Cursor, Cline. Cuts AI coding costs 70-90% via context packs, output filters, local memory + receipts. 40 MCP tools, 122/122 tests, Apache-2.0.","archived":false,"fork":false,"pushed_at":"2026-05-23T08:00:45.000Z","size":3846,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T09:33:58.840Z","etag":null,"topics":["ai-agents","ai-coding","anthropic","claude-code","cli","cline","context-engineering","cpp17","cursor","developer-tools","knowledge-graph","llm-tools","local-first","mcp","mcp-server","prompt-engineering","semantic-search","sqlite","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ncmonx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"ncmonx","ko_fi":"ncmonx"}},"created_at":"2026-05-06T05:59:16.000Z","updated_at":"2026-05-23T08:00:47.000Z","dependencies_parsed_at":"2026-05-12T06:00:48.173Z","dependency_job_id":null,"html_url":"https://github.com/ncmonx/icm-graph","commit_stats":null,"previous_names":["ncmonx/icm-graph"],"tags_count":213,"template":false,"template_full_name":null,"purl":"pkg:github/ncmonx/icm-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficm-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficm-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficm-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficm-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncmonx","download_url":"https://codeload.github.com/ncmonx/icm-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncmonx%2Ficm-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33637485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","anthropic","claude-code","cli","cline","context-engineering","cpp17","cursor","developer-tools","knowledge-graph","llm-tools","local-first","mcp","mcp-server","prompt-engineering","semantic-search","sqlite","token-optimization"],"created_at":"2026-05-07T06:03:35.212Z","updated_at":"2026-05-29T05:00:53.641Z","avatar_url":"https://github.com/ncmonx.png","language":"Python","funding_links":["https://github.com/sponsors/ncmonx","https://ko-fi.com/ncmonx"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"Icemage\" width=\"160\"/\u003e\n\u003c/p\u003e\n\n# Icemage \u003csub\u003e\u003csup\u003e(`icmg`)\u003c/sup\u003e\u003c/sub\u003e\n\n[![release](https://img.shields.io/github/v/release/ncmonx/icm-graph)](https://github.com/ncmonx/icm-graph/releases)\n[![downloads](https://img.shields.io/github/downloads/ncmonx/icm-graph/total)](https://github.com/ncmonx/icm-graph/releases)\n[![last-commit](https://img.shields.io/github/last-commit/ncmonx/icm-graph)](https://github.com/ncmonx/icm-graph/commits/main)\n[![ctest](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ncmonx/7d6a2efa9d6191e28ff3f6a26e6ba7c7/raw/ctest.json)](#)\n[![mcp tools](https://img.shields.io/badge/MCP%20tools-40-blueviolet)](#)\n[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ncmonx/icm-graph/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ncmonx/icm-graph)\n[![OpenSSF Best Practices](https://img.shields.io/cii/level/12818?label=OpenSSF%20Best%20Practices)](https://www.bestpractices.dev/projects/12818)\n[![sponsor](https://img.shields.io/badge/sponsor-GitHub-ea4aaa?logo=github-sponsors)](https://github.com/sponsors/ncmonx)\n[![ko-fi](https://img.shields.io/badge/Ko--fi-tip-ff5e5b?logo=ko-fi)](https://ko-fi.com/ncmonx)\n\n\u003e **Stop burning tokens. Stop losing context. Ship faster.**\n\nA small helper app that makes AI coding assistants — Claude Code, Cursor, and friends — **70 – 98 % cheaper** to run, without making them less helpful.\n\n**40 MCP tools · 1082/1082 tests · single-binary · 100 % local · pure-bash hooks** (zero Python/jq dependency).\n\nIf you've ever watched a huge token bill evaporate on a single file read, paid for \"thinking\" you didn't need, or re-explained your project to the AI for the fifth time today — Icemage is for you.\n\n---\n\n## 🟢 Why Icemage\n\nAI 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:\n\n- **Long files** → only the relevant slice\n- **Noisy command output** → just the parts that matter\n- **Web pages** → cached + summarised\n- **Past decisions** → remembered across sessions so the AI doesn't ask twice\n- **Repeated work** → results reused instead of recomputed\n\nThe AI keeps its full intelligence. Your wallet keeps more of its money.\n\n---\n\n## 📊 Headline numbers\n\n| Metric | Typical | Best | Since |\n|---|---|---|---|\n| File-read savings | 70 – 85 % fewer tokens | up to 92 % | v0.5 |\n| Test / build output | 60 – 80 % shorter | up to 90 % | v0.5 |\n| **Multi-file UI propagation** (style-clone) | **30 – 50× cheaper** | up to 98 % | v1.22.0 |\n| **Cross-project bundle** (port) | **8 – 12× cheaper** | up to 95 % | v1.24.0 |\n| **Compressed-Write** (AI emit diff) | **70 – 95% fewer tokens** | up to 98 % | v1.25.0 |\n| Web-fetch reduction | 70 – 90 % smaller | up to 95 % | v0.4 |\n| Repeat-context recall | near-zero, **\u003c 5 ms cached** | — | v1.21.8 |\n| Past-chat full-text search | **\u003c 10 ms** across months | — | v1.21.7 |\n| Graph symbol lookup | **256-slot in-RAM cache** | — | v1.21.8 |\n| First-prompt warmup | \u003c 1 s | — | v1.18 |\n| **Cold build time** (icmg itself) | **~50 % faster** (20 min → 9-10 min) | — | v1.26.0 |\n| **MCP response filter** (verbose plugins) | **50 – 80 % smaller** | up to 90 % | v1.30.0 |\n| **Auto-thinking suppress** (trivial prompts) | **~1500 tok / call saved** | — | v1.30.0 |\n| **Caveman-auto** (long-prose replies) | **60 – 75 % compress** | up to 85 % | v1.30.0 |\n| **Service auto-start** (UserPromptSubmit) | **0-touch warm-up** | — | v1.30.0 |\n| **Path ambiguity warning** (icmg context) | wrong-file lookups → loud | — | v1.29.0 |\n| **rg-wrapper + brace glob** (icmg grep/files) | flag-mirror, **{a,b}** expand | — | v1.29.0 |\n| **Local AI model** (built-in, opt-in) | **0 cloud calls** | privacy-first | v1.31.0 |\n| **Smart router** (REGEX vs LLM_LOCAL vs CACHE) | **\u003c100 us p99** | hot-path forced regex | v1.31.0 |\n| **HTTP streaming download** (model fetch + SHA256) | **400 MB - 2 GB** safe-verify | tamper-detect | v1.31.0 |\n| **icmg git** wrapper (single ergonomic entry) | **Tkil-filtered** + safety-gated | enforces icmg-FIRST | v1.31.0 |\n| **Python-free core** (PRECOMPACT_PY dropped) | **-200-500 ms** boot saved | single-binary | v1.31.0 |\n| **pack --rerank** (LLM-reorder memory hits) | **opt-in** warm-path | router-gated | v1.32.0 |\n| **PreCompact LLM summary** (warm-pool Qwen 0.5B) | **\u003c15 s** cold | regex fallback always | v1.32.0 |\n| **icmg compact-bg** (proactive memory worker) | **\u003c3 s** warm | manual + future hook | v1.32.0 |\n| **Smarter local AI memory** | **multi-prompt safe** | no overflow | v1.32.0 |\n| Cost per AI session | **down 70 – 90 %** vs. raw | up to 95 % | — |\n\nMeasured on real-world sessions. Your mileage will vary with project size and habits — anyone running a busy AI agent for a day already sees meaningful savings.\n---\n\n## ✨ What's new\n\n\u003e **Recent releases.** Older entries archived in [`CHANGELOG.md`](CHANGELOG.md).\n\n- **v1.70.0** - **Fixes from user reports: cleaner CLI output and command pass-through**. `icmg run` no longer swallows flags meant for the program you're wrapping - `icmg run ./tool --json` now passes `--json` to the tool, and `icmg run -- ...` forwards everything after `--` verbatim. `icmg llm list` now prints a single clean JSON document (it used to tack on a trailing text line that broke JSON parsers). And `icmg recall --json` always returns valid UTF-8, so tools that re-serialize its output no longer choke on notes that captured stray binary bytes. Full automated suite passes 1082 of 1082 checks.\n- **v1.69.0** - **The icmg-first rule now enforces itself**. Getting an AI assistant to reliably go through icmg (instead of raw file reads or shell) used to mean hand-seeding a rule into memory for every new project and every new teammate. Now `icmg init` installs a small hook that reminds the assistant of the rule on every prompt automatically - the full rule on the first turn, a one-liner after - so a fresh project or a new user just runs `icmg init` and it's handled (opt out with ICMG_NO_ICMG_FIRST=1). This release also fixes a crash where building the assistant's context could abort if a saved note contained non-text bytes. Full automated suite passes 1071 of 1071 checks.\n- **v1.68.0** - **Security: a locked-down daemon and a secret scanner**. The optional background daemon now requires a per-user token before it will accept any command (even shutdown), so no other local program can quietly drive it. And a new \"icmg scan\" command walks your project and flags hardcoded secrets - API keys, access tokens and the like - showing where each one is (redacted by default) and failing if any are found, so it drops straight into a pre-commit or CI check. Full automated suite passes 1068 of 1068 checks.\n- **v1.67.0** - **Fix: clean new-project setup**. Initializing icmg in a brand-new project could hit a 'duplicate column' error if a background task touched the just-created database at the same moment. The database setup now locks and re-checks before applying each step, so concurrent access is safe and a new project initializes cleanly. Full automated suite passes 1060 of 1060 checks.\n- **v1.66.0** - **Per-project terse mode**. The compact 'caveman' response mode is now decided per project instead of one global switch - handy when using icmg as a dedicated brain for a project that should behave differently from the rest. `icmg caveman on/off` targets the current project by default (add `--global` for all); a project can even stay off while the global setting is on. Full automated suite passes 1057 of 1057 checks.\n\n## 🚀 Quick start\n\n1. **Download** the latest installer from the [Releases page](https://github.com/ncmonx/icm-graph/releases) — `icmg-\u003cversion\u003e-win-x64.zip` for Windows, `icmg-\u003cversion\u003e-linux-x64.tar.gz` for Linux.\n2. **Extract** the archive into any folder of your choice.\n3. **Add the folder to your `PATH`** so the `icmg` command is available everywhere.\n4. **Open your project** in a terminal and run:\n\n   ```text\n   icmg init\n   ```\n\n   That's it. The next time you launch Claude Code (or Cursor / Cline / Windsurf — see below), Icemage will quietly start trimming tokens.\n\n---\n\n## 🧰 What you'll actually use day-to-day\n\nAfter 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:\n\n| Want to | Type |\n|---|---|\n| See how much you saved this month | `icmg savings` |\n| See a chart in the terminal | `icmg savings --ascii` |\n| Recall a past decision in this project | `icmg recall \"\u003cquestion\u003e\"` |\n| Recall something from another project | `icmg cross-recall \"\u003cquestion\u003e\"` |\n| Wake-up briefing for a fresh session | `icmg wake-up` |\n| Update Icemage in place | `icmg update --apply` |\n| Health-check the install | `icmg doctor` |\n\nFor the full menu run `icmg --help`.\n\n---\n\n## 🤖 Works with\n\n- **Claude Code** (primary target — best-tested)\n- **Cursor** — drop-in via the same hooks\n- **Cline**, **Windsurf**, **OpenCode** — same approach, may need a small config nudge\n- **Anything that exposes hooks or MCP** — the MCP server bundled with Icemage is reusable\n\n---\n\n## 🛡️ Safety + privacy\n\n- **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.\n- **No telemetry.** Icemage doesn't phone home.\n- **Open source.** [Apache-2.0](LICENSE). 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.\n- **Tamper-evident.** Every release ships with a `sha256` sidecar so you can verify the binary you downloaded.\n\n---\n\n## 🩹 Honest limits\n\n- **Windows + Linux only** for prebuilt binaries today. macOS users currently need to wait for a self-hosted runner build (planned).\n- **First-time install on Windows with strict antivirus** can be slow until you let Icemage run once. After that it's fast.\n- **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.\n\n---\n\n## 💖 Support\n\nIf Icemage saved you a few hours or a few dollars and you want to send a small thank-you, both routes work:\n\n- [GitHub Sponsors](https://github.com/sponsors/ncmonx)\n- [Ko-fi tip jar](https://ko-fi.com/ncmonx)\n\nAll 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.\n\n---\n\n## ❓ FAQ\n\n**Does Icemage send my code anywhere?**\nNo. Everything is local. The only network call is when you ask Icemage to update itself or fetch a URL through `icmg fetch`.\n\n**Can my company use it?**\nYes — Apache-2.0 licensed, free for any use including commercial. If you want a private support arrangement or a custom build, [open a sponsorship](https://github.com/sponsors/ncmonx).\n\n**Why is the source code repo private?**\nOne 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.\n\n**Does it slow my AI down?**\nNo. 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.\n\n**Where are the savings stored?**\nIn `.icmg/data.db` inside each project (small SQLite file). Run `icmg savings` to see the breakdown.\n\n**How do I report a bug or ask for a feature?**\nOpen an issue at the [GitHub issues](https://github.com/ncmonx/icm-graph/issues) page. Real-world reproductions with `icmg savings --json` attached get triaged fastest.\n\n---\n\n## 🌟 Star history\n\n\u003ca href=\"https://star-history.com/#ncmonx/icm-graph\u0026Date\"\u003e\n  \u003cimg src=\"https://api.star-history.com/svg?repos=ncmonx/icm-graph\u0026type=Date\" alt=\"Star history\" width=\"600\"/\u003e\n\u003c/a\u003e\n\n---\n\n## 📜 License\n\n[Apache-2.0](LICENSE).\n\n---\n\n## 📚 Other docs\n\n- [CHANGELOG.md](CHANGELOG.md) — full version history\n- [SECURITY.md](SECURITY.md) — vulnerability reporting\n- [NOTICE](NOTICE) — third-party attributions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncmonx%2Ficm-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncmonx%2Ficm-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncmonx%2Ficm-graph/lists"}