⚡ SigMap
SigMap is the deterministic, verifiable grounding layer for AI code work.
Try it now
No install required. Run instantly on any machine:
npx sigmap
npx sigmap ask "Where is auth handled?"
npx sigmap verify answer.md # flags files, imports and symbols an AI answer made up
Zero config. Zero dependencies. Under 10 seconds.
What is SigMap?
SigMap builds a deterministic, auditable signature-and-evidence map of your codebase — no LLM calls, no embeddings, byte-stable output (apart from one trailing timestamp line, and independent of where the repo is checked out) — so AI agents, CI, and reviewers can trust and verify which files and symbols are real before acting. Same repo in, same map out, every time.
That map is exactly what agentic grep is worst at: reproducible, auditable context an agent can consume without a copy-paste, and a grounding check that proves an AI answer is anchored to real signatures and line numbers. Token reduction comes for free — but trust is the point.
Model-agnostic. Works with:
- Cloud LLMs: Claude, GPT-4, Copilot, Gemini
- Open-source agents: OpenCode, Aider, OpenHands, Cline
- Local LLMs: Ollama, llama.cpp, vLLM (no API keys, full privacy)
- Any editor: VS Code, Cursor, Windsurf, Neovim, JetBrains
- Any model: Use what you want, no vendor lock-in
Why SigMap?
Deterministic and verifiable — the two things an agentic-grep loop can't give you:
- Deterministic — no LLM calls, no agent loop; the same repo always produces a byte-identical map you can diff, cache, and gate in CI.
- Auditable & grounded — every symbol in the AST and anchored-regex tiers carries a real
:start-endline anchor; Tier-3 formats (R, Lua, Elixir, config formats) are listed without anchors, as KNOWN_LIMITATIONS.md states.sigmap verifyflags any AI claim that isn't grounded. - Zero dependencies —
npx sigmapon any machine; no embeddings, no vector DB, no hosted service, fully offline.
Proof it pays off (full benchmark below):
-
80.4% hit@5 — right file in top 5 results (retrieval corpus, 18 repos)
-
92.8% vs 39.2% single-shot grep baseline — 2.37× measured lift on the honest corpus (125 tasks / 19 repos)
-
56.7% hit@5 on repositories we do not control — the third-party corpus: 118 of 208 questions over 35 repos, 95% interval 49.9–63.3%, labelled by two language-model annotators before SigMap ran on them. The stricter number to read beside the honest corpus above, which includes this repository
-
95.2% smaller than the full repository — the generated map vs every source file, averaged across 21 real repos. A map-size measurement, not a per-call cost saving: an agent's context footprint is not the whole repo
-
61.9% task-success proxy — modeled from retrieval tiers, not measured LLM sessions
-
1.58 prompts per task — down from 2.84 (44.4% fewer retries, modeled)
-
38 languages supported — TypeScript, Python, Go, Rust, Java, R, and more
-
No vendor lock-in — works with any AI assistant or local LLM
-
No API costs — use local models (Ollama, llama.cpp, vLLM) with zero token fees
-
Full privacy — keep your code and context on your machine
🔒 sigmap verify — the grounding flagship
A zero-config, offline linter for the claims an AI answer makes about your repo: the files and test files it names, its npm run scripts, its relative and Python imports and the names it takes from repo modules, the functions it calls in backticks, and the argument counts of top-level calls — each looked up in a fresh SigMap index. Deterministic, no LLM. It cannot tell you that a method, an option or a library API exists, so it complements tsc / pyright rather than replacing them, and every run prints what it checked and what it did not.
sigmap verify answer.md # a line-by-line list of what the repo does not have, and what was not checked
sigmap verify answer.md --json # machine-readable report (CI gate): exit 0 clean · 1 issues · 2 usage · 3 index missing or stale
sigmap verify answer.md --report # standalone red/amber/green HTML report
[sigmap] ✗ answer.md — 2 issues found
fake-file: 1 fake-test-file: 0 fake-import: 0 fake-import-name: 0 fake-symbol: 1 fake-npm-script: 0
L2 [Fake file] File not found on disk: src/auth/session-store.js
↳ Did you mean `session-store.test.js` in test/integration/session-store.test.js?
L2 [Fake symbol] Symbol not found in repo index: authorize()
↳ Did you mean `summarize()` in scripts/lib/agent-ab.mjs?
checked 2 claims — 1 file path · 1 backticked call
not checked: calls in fenced or raw code · member calls (obj.method()) · library APIs (named imports from, and members of, installed libraries)
Real output of sigmap verify on a two-line answer.md that names a file and a function this repository does not have; the "Did you mean" targets depend on the repository.
verify is the flagship; verify-ai-output remains as the full command name. Pair it with sigmap verify-plan (check a plan before execution) and the verify_suggestion MCP tool (verify AI code against repo + private + installed-library symbols mid-session).
Replace this with SigMap
How it works
Ask → Rank → Context → Validate → Judge → Learn
- Ask —
sigmap ask "Where is auth handled?"— ranked file list - Rank — TF-IDF scores every file against your query
- Context — writes compact signatures to your AI's context file
- Validate —
sigmap validate— confirms right files are in scope - Judge —
sigmap judge— scores answer groundedness against context - Learn —
sigmap weights— boosts files that keep solving your tasks
Benchmark
Benchmark : sigmap-v8.85-main (21 repositories, including R language)
Date : 2026-10-27
Hit@5 : 80.4% (retrieval corpus, 18 repos)
Honest vs grep : 92.8% vs 39.2% grep baseline — 2.37× lift (125 tasks / 19 repos)
Third-party : 56.7% hit@5 (118 of 208 questions / 35 repos, 95% interval 49.9–63.3%)
Map vs repo : 95.2% smaller (generated map vs all source files, 21 repos — not a per-call cost saving)
Prompt reduction : 44.4% (2.84 → 1.58 prompts per task, modeled)
Task success : 61.9% (proxy — modeled from retrieval tiers)
Repos tested : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
All numbers above are generated from benchmarks/latest.json (npm run metrics:sync) — never hand-typed.
Measured on 105 coding tasks across 18 real public repos. No LLM API — fully reproducible.
Resources:
- Full methodology →
- Benchmark suite (GitHub) — scripts, tasks, and raw data
- Benchmark data (Zenodo) — 2026-04-29 snapshot, known defect: the
final_tokenscolumn of its results file is 0 in all 405 rows (andreduction_percentis 100 in 395), so do not reload results from it —benchmarks/reports/in this repository is the current record
Install
Try without installing:
npx sigmap
Install globally:
npm install -g sigmap
Install per-project:
npm install --save-dev sigmap
Standalone binary — no Node.js required:
Each binary ships with a .sha256 checksum. Verify a binary →
Volta:
volta install sigmap
Integrations
AI assistants — one run, all of them:
sigmap --adapter copilot # default — works with Copilot, OpenCode
sigmap --adapter openai # works with Ollama, llama.cpp, vLLM, Aider
sigmap --adapter claude # works with Claude Code
Open-source agents & local LLMs:
Use SigMap with open-source tools and fully self-hosted setups:
- Open-source agents guide → — OpenCode, Aider, OpenHands, Cline
- Local LLMs guide → — Ollama, llama.cpp, vLLM (no API keys, full privacy)
IDE extensions:
MCP server — 22 on-demand tools for Claude Code, Codex CLI, OpenCode, Cursor, and other supported clients:
sigmap --mcp
Tools: read_context, search_signatures, get_map, create_checkpoint, get_routing, explain_file, list_modules, query_context, get_method_impact (per-symbol blast radius), get_impact, get_lines, read_memory, get_callee_signatures, get_diff_context (changed files + signatures + blast radius), get_architecture_overview (modules, hub files, cycles), verify_suggestion (ground AI code against repo + installed libraries), squeeze_output (compress noisy tool/log/JSON output mid-session), get_budget (what SigMap has emitted this session), query_knowledge_map (typed nodes and edges: a library's upgrade impact, a file's neighbors, who reads an env var), plus the live-index notifications sigmap_notify_file_created, sigmap_notify_symbol_added, and sigmap_notify_file_deleted. All 22 are advertised unless mcp.tools says otherwise: "core" is seven of them (query_context, read_context, get_callee_signatures, get_lines, get_impact, get_method_impact, verify_suggestion) for about 0.9k tokens of definitions where all 22 cost about 2.5k, and sigmap --init writes it into a new config. Full reference: llms-full.txt.
SigMap doesn't compete with your agent's live search — it's what the live loop calls for grounding: grep finds the file; query_context → get_callee_signatures → get_lines → verify_suggestion → get_method_impact prove the symbols, lines, calls, and blast radius — deterministically. See the agent live-loop guide.
Grounded creation & guardrails
Verify AI work against the live index instead of trusting it blind:
sigmap conventions # extract the repo's file-naming / export / test conventions
sigmap scaffold "<name>" # propose a convention-matched file/dir (refuses if conventions conflict)
sigmap verify-plan <plan.md> # check a plan: do the files/symbols exist? blast radius? scope?
sigmap verify-ai-output <answer.md> # flag fabricated files/imports/symbols/tests in an AI answer
sigmap review-pr # audit a diff: scope drift, god-node edits, missing tests, security files
sigmap create "<task>" # run the whole pipeline: scaffold → verify-plan → verify-ai-output → review-pr
Evidence Pack & diagnostics
The Evidence Pack is the consumable, machine-readable replacement for "paste this into your prompt" — a deterministic JSON artifact (with a Markdown handoff mode) that an agent or CI step reads directly, with zero copy-paste:
sigmap evidence "how does auth work" # → .context/evidence-pack.json (deterministic, byte-stable)
sigmap evidence "how does auth work" --markdown # Markdown handoff to stdout
sigmap doctor # diagnose config, index, freshness, coverage, MCP wiring — with fixes
Each pack carries the ranked files, the symbols and line anchors that justify them, the token budget, the dropped files (and why), and the grounding summary — so a consumer can trust and audit the context instead of guessing.
Agent recipes
SigMap treats coding agents as consumers, not competitors: it hands them a deterministic, auditable map the agent can read on demand. Wire any of them up once, then let the agent pull context or consume an Evidence Pack.
Claude Code uses .mcp.json, Codex CLI uses ~/.codex/config.toml, and OpenCode uses opencode.json. When those host CLIs are installed, mcp install verifies the entry with each host's mcp list command.
# Pattern 1 — give the agent live, on-demand access (MCP)
sigmap mcp install claude # one of: claude|cursor|windsurf|vscode|zed|codex|gemini|opencode|mcp
# add --global for a user-level install
# Pattern 2 — hand the agent a deterministic Evidence Pack (no MCP, no copy-paste)
sigmap evidence "implement rate limiting" --markdown # or read .context/evidence-pack.json
See sigmap mcp list for every supported client.
Try it
# 1. Generate context for your project
npx sigmap
# 2. Ask a question — get ranked files
sigmap ask "Where is auth handled?"
# 3. Validate — confirm the right files are in scope
sigmap validate --query "auth login token"
# 4. Judge — score your AI's answer for groundedness
sigmap judge --response response.txt --context .context/query-context.md
claude -p "how does ranking work?" | sigmap judge # stdin; --context defaults to the generated one
# 5. Inspect health
sigmap --health
Start guide
Docs
Support
If SigMap saves you context or API spend, a ⭐ on GitHub helps others find it.
🌍 See where SigMap's stargazers are around the world on the StarMapper star map →.
📈 Watch SigMap's growth on the Star History chart →.
Sponsor
SigMap is built and maintained by one developer, kept zero-dependency, offline, and free. If it saves your team context or API spend, sponsoring keeps it that way — and funds the benchmark CI, the sigmap.io domain, and ongoing supply-chain hardening.
💜 Become a sponsor → · see SPONSOR.md for tiers and exactly where your support goes. Any amount helps — even $1/mo — and a ⭐ or a share counts too.
Contributing
SigMap welcomes contributions!
Before submitting a PR:
- Read CONTRIBUTING.md
- Check Discussions → Announcements for workflow setup
- Target the
developbranch (not main) - Follow the contributor checklist
See .github/PULL_REQUEST_TEMPLATE.md for the PR checklist. All contributors are credited in the CHANGELOG and release notes.
Why not embeddings?
- No vector DB — signatures are plain text files committed to your repo
- No infra — runs locally, zero cloud dependencies
- No drift — regenerating is
npx sigmap, not a reindex pipeline - Deterministic — same input always produces same ranked output
- Faster — TF-IDF ranking runs in milliseconds, no embeddings to compute
38 languages
TypeScript · JavaScript · Python · Java · Kotlin · Go · Rust · C# · C/C++ · Objective-C · Ruby · PHP · Swift · Dart · Scala · Vue · Svelte · HTML · CSS/SCSS · YAML · Shell · PowerShell · SQL · GraphQL · Terraform · Protobuf · Dockerfile · TOML · XML · Properties · Markdown · R · GDScript
All implemented with zero external dependencies.
Extraction honesty
Not all 38 languages get the same depth — and we say so plainly:
Caps: 25 signatures/file in the context file, up to 200 in the retrieval index · 120 members/class (the extractors' own limit). Full details, known regex gaps, and what they mean for verify: KNOWN_LIMITATIONS.md.
License
MIT © 2026 Manoj Mallick · Made in Amsterdam
Docs · Changelog · Roadmap · npm
⭐ Star on GitHub if SigMap saves you tokens.
