Sigmap

⚡ SigMap

SigMap is the deterministic, verifiable grounding layer for AI code work.

[](https://www.npmjs.com/package/sigmap) [](https://www.npmjs.com/package/sigmap) [](https://github.com/manojmallick/sigmap/actions/workflows/ci.yml) [](package.json) [](LICENSE) [](https://github.com/manojmallick/sigmap/stargazers) [](https://starmapper.bruniaux.com/manojmallick/sigmap) [](https://star-history.com/#manojmallick/sigmap&Date) [](https://shypd.ai/tools/sigmap)

---

Try it now

No install required. Run instantly on any machine:

npx sigmap
npx sigmap ask "Where is auth handled?"

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 — 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 file and symbol traces to a real line anchor; sigmap verify-ai-output flags any AI claim that isn't.
• Zero dependencies — npx sigmap on any machine; no embeddings, no vector DB, no hosted service, fully offline.

Proof it pays off (full benchmark below):

• 75.6% hit@5 — right file found in top 5 results (vs 13.6% baseline)
• 97.0% token reduction — average across 21 real repos
• 52.2% task success rate — up from 10% without context
• 1.72 prompts per task — down from 2.84 (39.4% fewer retries)

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

---

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 76% of the time, every symbol 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-v7.30-main (21 repositories, including R language)
Date      : 2026-06-23

Hit@5          : 75.6%   (baseline 13.6%  — 5.6× lift)
Token reduction: 97.0%   (across 21 repos)
Prompt reduction : 39.4% (2.84 → 1.72 prompts per task)
Task success   : 52.2%   (baseline 10%)
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 90 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) — archived results for reproducibility

---

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 →](docs/readmes/binaries.md)

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 knowledge store |

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 — 17 on-demand tools for Claude Code and Cursor:

sigmap --mcp

Tools: read_context, search_signatures, get_map, create_checkpoint, get_routing, explain_file, list_modules, query_context, get_impact, get_lines, read_memory, get_callee_signatures, get_diff_context (changed files + signatures + blast radius), get_architecture_overview (modules, hub files, cycles), plus the live-index notifications sigmap_notify_file_created, sigmap_notify_symbol_added, and sigmap_notify_file_deleted. Full reference: [llms-full.txt](llms-full.txt).

---

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 ""            # propose a convention-matched file/dir (refuses if conventions conflict)
sigmap verify-plan         # check a plan: do the files/symbols exist? blast radius? scope?
sigmap verify-ai-output  # 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 ""             # 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 | 17 MCP tools (search_signatures, get_lines, get_diff_context…) | | 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 "" | Consumes .context/evidence-pack.json directly | | Codex CLI | sigmap mcp install codex | MCP tools, plus the codex adapter writes AGENTS.md |

# 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

# 5. Inspect health
sigmap --health

---

Start guide

| Who | Start here | |---|---| | 👶 New | [Quick start guide](docs/readmes/GETTINGSTARTED.md) — setup in 60 seconds | | ⚡ Daily | sigmap ask / sigmap validate / sigmap judge | | 🧠 Advanced | [Context strategies](docs/readmes/CONTEXTSTRATEGIES.md) · [MCP setup](docs/readmes/MCPSETUP.md) | | 🏢 Teams | Config reference · [CI setup](docs/readmes/ENTERPRISE_SETUP.md) |

---

Docs

sigmap.io

| Section | Link | |---|---| | CLI reference (32 commands) | cli.html | | Benchmark methodology | benchmark.html | | Config reference | config.html | | Roadmap | roadmap.html | | 33 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 →.

Report an issue · [Changelog](CHANGELOG.md)

---

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](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](CONTRIBUTING.md)
2. Check [Discussions → Announcements](../../discussions) for workflow setup
3. Target the develop branch (not main)
4. Follow the [contributor checklist](.github/CONTRIBUTOR_CHECKLIST.txt)

See [.github/PULLREQUESTTEMPLATE.md](.github/PULLREQUESTTEMPLATE.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

---

33 languages

TypeScript · JavaScript · Python · Java · Kotlin · Go · Rust · C# · C/C++ · Ruby · PHP · Swift · Dart · Scala · Vue · Svelte · HTML · CSS/SCSS · YAML · Shell · SQL · GraphQL · Terraform · Protobuf · Dockerfile · TOML · XML · Properties · Markdown · R · GDScript

All implemented with zero external dependencies.

Full language table →

---

License

MIT © 2026 Manoj Mallick · Made in Amsterdam

---

Docs · [Changelog](CHANGELOG.md) · Roadmap · npm

⭐ Star on GitHub if SigMap saves you tokens.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: manojmallick
• Source: manojmallick/sigmap
• License: MIT
• Homepage: https://sigmap.io/

Install and usage instructions live in the source repository linked above.