# SigMap review: a deterministic signature map that grounds AI coding agents > SigMap indexes a repository into a byte-stable signature-and-evidence map so agents and reviewers can check that AI answers point at real files, symbols and line numbers. It ships as a zero-dependency npm CLI plus an MCP server, and it is the wrong tool when you want semantic search over prose. **manojmallick/sigmap** — ~97% token reduction for AI coding sessions — zero deps, 33 languages, MCP server - Repository: https://github.com/manojmallick/sigmap - Website: https://sigmap.io/ - Stars: 638 · Forks: 50 - Language: JavaScript - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/manojmallick-sigmap ## The problem SigMap targets: agents that name files which do not exist An agent working in a large repository usually retrieves context by grepping or by embedding similarity. Both are probabilistic in practice. The grep loop depends on the query the model happens to write; the embedding index depends on a model, a vector store and a chunking strategy, and re-indexing can shift results. Neither gives you a stable artifact you can diff between two commits, and neither gives you a way to check afterwards whether the answer was anchored to anything real. SigMap's claim is narrower than "better retrieval". The README describes it as a "deterministic, verifiable grounding layer for AI code work" and states that it makes no LLM calls and uses no embeddings, producing byte-stable output where the same repository always yields the same map. That determinism is the product. It means the map can be cached, diffed and used as a CI gate, which is not true of an agent loop whose output changes with sampling temperature. The audience is therefore specific: teams already running Claude, Cursor, Copilot, Aider, OpenCode or a local model through Ollama, llama.cpp or vLLM, who want a fixed context artifact rather than another retrieval service. If you are not running an agent, the map is still readable, but the grounding checks are where the value sits. ## How SigMap builds a signature map without embeddings The pipeline in the README is a six-stage loop: Ask, Rank, Context, Validate, Judge, Learn. `sigmap ask "Where is auth handled?"` returns a ranked file list. Ranking is TF-IDF, scoring every file against the query text, so retrieval is lexical rather than semantic. The Context stage writes compact signatures to your AI's context file. `sigmap validate` confirms the right files are in scope, `sigmap judge` scores how grounded an answer is against that context, and `sigmap weights` boosts files that keep solving your tasks, which is a small feedback loop layered on top of the static index. The extraction side is language-aware rather than line-based. The package.json test scripts include a Python AST extractor test (`test/test_python_ast_extractor.py`) and a dedicated R language test (`test/r-language.test.js`), and the README claims 33 languages including TypeScript, Python, Go, Rust, Java and R. The repository also ships a KNOWN_LIMITATIONS.md at the top level, which is worth reading before you assume full parity across all 33. The grounding flagship is `sigmap verify`. According to the README, it indexes your repository plus the libraries actually installed in that environment, then flags fabricated files, imports, symbols, tests and npm scripts. That installed-library part matters: it is what lets the tool distinguish a symbol that exists in your dependency tree from one the model invented. `sigmap verify-ai-output` remains as the full command name, and a `verify_suggestion` MCP tool exposes the same check mid-session. ## Installing SigMap and running a first verification There is no install step to begin with. The README's "Try it now" section says no install is required and gives `npx` invocations that run on any machine with Node. The first command below generates the map for the current directory; the second asks a question against it and returns a ranked file list rather than prose. ```bash npx sigmap npx sigmap ask "Where is auth handled?" ``` The README states this is zero config, zero dependencies, and takes under 10 seconds. What you should see is a ranked list of files, not an answer written in sentences. SigMap does not generate text; it tells you which files match and leaves the writing to your model. The verification workflow is the one worth trying first, because it is the part with no obvious substitute. Write an AI answer to a file, then point `verify` at it: ```bash sigmap verify answer.md sigmap verify answer.md --json sigmap verify answer.md --report ``` The plain form prints a grounded check or a line-by-line list of fabrications. The README shows output of this shape, with issue counts by category and per-line findings such as a fake file at L12 and a fake symbol at L27 with a suggested correction. The `--json` flag produces a machine-readable report and exits 1 if any issue is found, which is what makes it usable as a CI gate. The `--report` flag writes a standalone red/amber/green HTML report. Note that the exit-code behaviour is documented for `--json` specifically; the README does not state what exit code the plain form returns, so check that before wiring the plain form into a pipeline. ## What the benchmark numbers do and do not establish The README publishes a benchmark block attributed to `benchmarks/latest.json`, generated by `npm run metrics:sync` rather than hand-typed, dated 2026-09-07 and covering 21 repositories. It reports 81.1% hit@5 against a 44.0% single-shot grep baseline, 96.8% average token reduction, and 45.7% prompt reduction from 2.84 to 1.54 prompts per task. The honest part is the labeling. The README marks the prompt reduction as "modeled" and the 64.8% task-success figure as a "proxy, modeled from retrieval tiers, not measured LLM sessions". That is a meaningful distinction: hit@5 is a retrieval measurement you can reproduce from the suite, while the task-success and prompt numbers are derived, not observed. Treat the retrieval figures as the evidence and the agent-behaviour figures as an estimate of what better retrieval might buy you. The 96.8% token reduction number deserves the same care. It measures the size of the signature map against the size of the files it replaces, averaged across those repositories. It is not a measurement of your bill. If your agent reads three small files per task, the saving will be smaller than the headline; if it habitually pastes whole modules, it will be larger. The README's own framing is that "token reduction comes for free, but trust is the point", which is the right way to read the number. ## Where SigMap is the wrong tool TF-IDF ranking is lexical. A query phrased in different vocabulary from the code will rank poorly, and there is no embedding fallback to catch it. If your retrieval problem is "find the module that implements retry semantics" in a codebase that never uses the word retry, SigMap's ranked list is not going to rescue you, and neither is `sigmap weights` unless a previous task already boosted the right file. Second, the tool is a code-and-signature index. It is not a search engine over your issue tracker, design docs, commit messages or Slack exports. Nothing in the README suggests it ingests prose corpora, and the grounding check is scoped to files, imports, symbols, tests and npm scripts. If your hallucination problem is a model inventing a feature that was never specified, `sigmap verify` will not see it, because there is no signature to contradict. Third, the verification is only as good as the environment it runs in. Because `verify` resolves against installed libraries, running it in a container that never ran your package install will produce false positives on real imports. That is a deployment constraint, not a bug, but it is the kind of thing that turns a CI gate into a nuisance if the job is not set up with dependencies present. The repository's KNOWN_LIMITATIONS.md exists precisely because coverage across 33 languages is not uniform, and you should read it for your language before trusting extraction. ## SigMap against embedding-based code retrieval The obvious alternative is a vector-index code search layer: chunk the repository, embed the chunks with a hosted or local model, store them in a vector database, and retrieve by similarity. The difference in approach is not cosmetic. Embedding retrieval handles vocabulary mismatch, which TF-IDF cannot, and it degrades gracefully on fuzzy conceptual queries. In exchange you take on an embedding model, a vector store, an indexing pipeline that must be kept in sync with the repository, and results that are not byte-stable across re-indexes. SigMap's trade is the inverse. It gives up semantic matching to gain reproducibility and an artifact you can commit, diff and gate. The two are not mutually exclusive; an agent could use a vector index for discovery and `sigmap verify` as a post-hoc check that the answer names real symbols. That combination is arguably where the tool is strongest, because the verification step does not care how the context was retrieved. A second alternative is the plain grep loop the README benchmarks against, and for small repositories it is genuinely competitive. Grep is already installed, needs no index, and on a few thousand lines the model can often find what it needs in one pass. SigMap's advantage grows with repository size and with the cost of a wrong file in context, and shrinks toward zero on a small project where the whole tree fits in the prompt anyway. ## Maintenance, licence and upgrade cost The repository is not archived and the last push was on 2026-09-08, which is recent. Releases are frequent and versioned in the v8.x line: v8.30.0 on 2026-09-07, v8.29.0 ("Retrieval Index Split") on 2026-09-01, and v8.28.1 on 2026-08-22. package.json in the repository shows 8.47.0, ahead of the newest release listed, so the published npm version and the repository state are not always the same thing. Pin a version in CI rather than tracking latest if you depend on the map's byte-stability, because a retrieval index change between minor versions can alter ranked output even when the tool is behaving as designed. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation and no source-disclosure requirement. This is a description of the licence text, not legal advice; if you are redistributing SigMap inside a product, have your own counsel read the LICENSE file in the repository. The operationally significant point about maintenance cost is that SigMap has zero runtime dependencies, so there is no transitive dependency tree to audit or patch. The upgrade cost is therefore mostly behavioural: regenerating the map, re-checking that `verify` still resolves your installed libraries, and re-running whatever CI gate you built on the `--json` exit code. ## Conclusion Adopt SigMap if you already run an AI coding agent and want a cheap, offline check that its answers name files and symbols that exist, or if you want a compact signature map to paste into a context file instead of whole files. Skip it if your problem is semantic retrieval over documentation, commit history or ticket text, because SigMap is lexical and signature-based, not embedding-based. Before rolling it into CI, run `npx sigmap` once on your own repository and read the generated map, then try `sigmap verify` on one real AI answer to see whether its fabricated-file detection matches the failure modes you actually hit. ## FAQ ### Does SigMap require an API key or a hosted service? No. The README states SigMap makes no LLM calls and uses no embeddings, runs offline via npx, and has zero dependencies, so there is no hosted service to sign up for and no API key involved. ### What does sigmap verify actually check in an AI answer? The README says it indexes your repository plus the libraries actually installed in that environment and flags fabricated files, imports, symbols, tests and npm scripts, reporting findings per line with suggestions such as a corrected symbol name. ### How many languages does SigMap support? The README states 33 languages, listing TypeScript, Python, Go, Rust, Java and R among them. The repository also ships a KNOWN_LIMITATIONS.md, which suggests coverage is not uniform across all of them. ### Can SigMap be used as a CI gate? Yes, in the form the README documents: `sigmap verify answer.md --json` produces a machine-readable report and exits 1 if any issue is found. The README does not state the exit code for the plain, non-JSON form. ### Is SigMap's token reduction claim a measurement of my bill? No. The README reports 96.8% average token reduction across 21 repositories as the size of the signature map relative to the files it replaces. How much that saves you depends on how much of each file your agent was reading before. ### Which AI assistants does SigMap work with? The README lists Claude, GPT-4, Copilot and Gemini among cloud models, OpenCode, Aider, OpenHands and Cline among open-source agents, and Ollama, llama.cpp and vLLM for local models, with no vendor lock-in claimed. ## Sources - [License: MIT](https://github.com/manojmallick/sigmap/blob/main/LICENSE) - [manojmallick/sigmap on GitHub](https://github.com/manojmallick/sigmap) - [Project website](https://sigmap.io/) - [README](https://github.com/manojmallick/sigmap/blob/main/README.md) - [Releases](https://github.com/manojmallick/sigmap/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/manojmallick-sigmap