sigmap

---

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-end line anchor; Tier-3 formats (R, Lua, Elixir, config formats) are listed without anchors, as KNOWN_LIMITATIONS.md states. sigmap verify flags any AI claim that isn’t grounded.
• Zero dependencies — npx sigmap on 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 40.0% single-shot grep baseline — 2.32× 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

Without SigMap	With SigMap
❌ Non-reproducible agent guesses	✅ Deterministic map — same input, same output, every time
❌ “Trust me” AI answers	✅ Grounded — right file in context 80% of the time, anchored tiers on a real line anchor
❌ Embeddings / vector DB required	✅ Zero deps, no infra, fully offline

---

How it works

Ask → Rank → Context → Validate → Judge → Learn

1. Ask — sigmap ask "Where is auth handled?" — ranked file list
2. Rank — TF-IDF scores every file against your query
3. Context — writes compact signatures to your AI’s context file
4. Validate — sigmap validate — confirms right files are in scope
5. Judge — sigmap judge — scores answer groundedness against context
6. Learn — sigmap weights — boosts files that keep solving your tasks

---

Benchmark

Benchmark : sigmap-v8.85-main (21 repositories, including R language)
Date      : 2026-10-28

Hit@5          : 80.4%   (retrieval corpus, 18 repos)
Honest vs grep : 92.8% vs 40.0% grep baseline — 2.32× 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_tokens column of its results file is 0 in all 405 rows (and reduction_percent is 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:

Platform	Download
macOS Apple Silicon	sigmap-darwin-arm64
macOS Intel	sigmap-darwin-x64
Linux x64	sigmap-linux-x64
Windows x64	sigmap-win32-x64.exe

Each binary ships with a .sha256 checksum. Verify a binary →

Volta:

volta install sigmap

---

Integrations

AI assistants — one run, all of them:

Adapter	Output file	Used by
copilot	.github/copilot-instructions.md	GitHub Copilot, OpenCode
claude	CLAUDE.md	Claude / Claude Code
cursor	.cursorrules	Cursor, Cline
windsurf	.windsurfrules	Windsurf
openai	.github/openai-context.md	OpenAI API, Aider, local Ollama/llama.cpp
gemini	.github/gemini-context.md	Google Gemini
codex	AGENTS.md	OpenAI Codex (legacy)
willow	Willow MCP store (HTTP POST — no file)	willow-mcp knowledge store (knowledge_ingest)

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:

IDE	Install	Source	Features
VS Code	Marketplace · Open VSX	github.com/manojmallick/sigmap-vscode	Status bar health grade, stale context alerts, one-click regen
JetBrains	Marketplace	github.com/manojmallick/sigmap-jetbrains	IntelliJ IDEA, WebStorm, PyCharm, GoLand — tool window + actions
Neovim	lazy.nvim / packer / vim-plug	github.com/manojmallick/sigmap.nvim	:SigMap, :SigMapQuery float window, statusline widget

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.

Agent	One-time setup	How it consumes SigMap
Claude Code	sigmap mcp install claude	22 MCP tools by default (search_signatures, get_lines, get_diff_context, squeeze_output…), or the seven of the core profile
OpenCode	sigmap mcp install opencode	Uses OpenCode’s local MCP config
Cursor	sigmap mcp install cursor	MCP tools, plus the cursor adapter writes .cursorrules
Cline	sigmap mcp install cursor	Reads .cursorrules; same MCP server
Continue	sigmap mcp install vscode	MCP tools inside the Continue extension
Aider	sigmap --adapter openai	Reads .github/openai-context.md before a session
OpenHands	sigmap evidence "<task>"	Consumes .context/evidence-pack.json directly
Codex CLI	sigmap mcp install codex	MCP tools, plus the codex adapter writes AGENTS.md

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

Who	Start here
👶 New	Quick start guide — setup in 60 seconds
⚡ Daily	sigmap ask / sigmap validate / sigmap judge
🧠 Advanced	Context strategies · MCP setup
🏢 Teams	Config reference · CI setup

---

Docs

sigmap.io

Section	Link
CLI reference (32 commands)	cli.html
Benchmark methodology	methodology.html
Config reference	config.html
Roadmap	roadmap.html
38 languages	generalization.html

---

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 →.

Report an issue · Changelog

---

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:

1. Read CONTRIBUTING.md
2. Check Discussions → Announcements for workflow setup
3. Target the develop branch (not main)
4. 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?

	Embeddings	SigMap
Vector DB required	✅	❌
Infrastructure to run	✅	❌
Drift over time	✅	❌
Deterministic results	❌	✅
Zero-config setup	❌	✅
Works offline	❌	✅

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

Full language table →

Extraction honesty

Not all 38 languages get the same depth — and we say so plainly:

Tier	Coverage	Depth
AST	Python (python3 on PATH; regex fallback without)	Full parse
Anchored regex	15 block-structured languages (JS, TS, Go, Rust, Java, Kotlin, Swift, PHP, Scala, Dart, C#, PowerShell, Objective-C, Ruby, C/C++)	Declarations + :start-end line anchors; doc hints on 7
Pattern/heuristic	Everything else + generic fallback	Line-oriented patterns

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

---