# SigMap — Complete LLM Reference > The deterministic, verifiable grounding layer for AI code work. > A reproducible signature-and-evidence map that agents, CI, and reviewers can trust and audit. No embeddings, no vector DB, fully offline. SigMap is the deterministic, verifiable grounding layer for AI code work. It extracts function and class signatures from a codebase and builds a byte-stable signature-and-evidence map that agents, CI, and reviewers can trust and audit — proving which files and symbols are real before acting. Deterministic BM25 ranking keeps the relevant context in scope (cutting tokens ~97% as a side effect), with no LLM calls, embeddings, or vector database. Works with Claude, Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP. # Version: 8.77.1 | Benchmark: sigmap-v8.77-main (2026-10-13) # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js # Regenerate: npm run generate:llms | Validate: npm run validate:llms --- ## Core metrics (benchmark: sigmap-v8.77-main, 2026-10-13) | Metric | Without SigMap | With SigMap | |--------|----------------|-------------| | Retrieval hit@5 (retrieval corpus) | — | 80.4% | | Honest corpus hit@5 (125 tasks) | 40.0% (single-shot grep) | 92.8% (2.32× lift) | | Token reduction | — | 95.7% average | | Task-success proxy (modeled) | — | 61.9% | | Prompts per task | 2.84 | 1.58 (44.4% fewer) | | Supported languages | — | 38 | | MCP tools | — | 22 | | npm runtime dependencies | — | 0 | --- ## Installation ```bash # Run immediately without installing npx sigmap # Install globally npm install -g sigmap # Auto-wire MCP + editor config + git hook + watcher npx sigmap --setup ``` --- ## CLI commands — complete reference Every command and flag (`sigmap --help`): ``` sigmap Generate context once and exit sigmap --monorepo Generate per-package context (monorepo) sigmap --each Run for every repo in the current directory sigmap --routing Include model routing hints in output sigmap --terse Compact signature encoding (deterministic; line anchors preserved) sigmap --format cache Also write Anthropic prompt-cache JSON sigmap --track Append run metrics to .context/usage.ndjson sigmap --watch Generate + watch for file changes sigmap --setup Generate + install git hook + watch sigmap --generate Same as a bare run — the flag the installed post-commit hook passes sigmap daemon start|stop|status Run --watch as a detached background daemon (status exits 1 when not running) sigmap --mcp Start MCP server on stdio sigmap --report Token reduction stats to stdout (exits 1 if over budget) sigmap --report --json Token report as JSON (for CI; exits 1 if over budget) sigmap --report --history Print usage log summary from .context/usage.ndjson sigmap --report --history --chart Include inline SVG charts + Unicode sparklines sigmap --report --sessions Captured agent sessions: provenance-labelled figures, per-class totals, branch rollup, coverage (--json, --agent , --limit ) sigmap --dashboard [--out ] Write .context/dashboard.html (HTML health dashboard) sigmap --suggest-tool "" Recommend model tier for a task description sigmap --suggest-tool "" --json Machine-readable tier recommendation sigmap --health Print composite health score sigmap --health --json Machine-readable health score sigmap --ci [--min-coverage N] CI exit gate — exits 1 when indexed coverage is below the threshold (default 80) sigmap --ci --json Gate verdict as JSON {pass, coverage, threshold} sigmap gain Token-savings dashboard (totals + by-operation) sigmap gain --all Add daily / weekly / monthly trend tables sigmap gain --json Aggregate savings as JSON sigmap gain --since 7d Window filter (7d, 30d, 12h, or ISO date) sigmap gain --top | --model Limit rows / set $ pricing model sigmap gain --reset Clear the local savings log (.context/gain.ndjson) sigmap ... --no-track Disable gain savings capture for this run sigmap --diff Changed files: working tree vs HEAD sigmap --diff Changed files: working tree vs (incl. uncommitted) sigmap --diff --staged Changed files: index vs HEAD (staged only) sigmap --benchmark Run retrieval benchmark (benchmarks/tasks/retrieval.jsonl) sigmap --adapter Generate for a specific adapter only (v3.0+) sigmap --adapter --json Show adapter output path as JSON sigmap --benchmark --json Benchmark results as JSON sigmap --eval Alias for --benchmark sigmap --analyze Per-file breakdown: sigs, tokens, extractor, coverage sigmap --analyze --json Breakdown as JSON sigmap --analyze --slow Re-time each extractor; flag files >50ms sigmap --diagnose-extractors Run all 21 extractors vs fixtures; show pass/fail + diff sigmap --query "" Rank files by relevance to a query sigmap --query "" --json Ranked results as JSON sigmap --query "" --top Limit results to top N files (default 10) sigmap --query "" --explain Per-file score signals, token coverage and near misses sigmap ask "" Ranked answer with signatures for a question (--json, --top , --mode) sigmap ask "" --explain Diagnose a miss: which tokens matched, why files were demoted sigmap ask "" --with-source Add top-symbol bodies + blast radius (budgeted; --source-budget ) sigmap plan "" Files to inspect, likely-to-change set, and impact radius (--json) sigmap explain Why a file is in or out of the generated context (--json) sigmap run Alias for a bare generate (gen-context run --report, etc.) sigmap learn --good Boost files in .context/weights.json sigmap learn --bad Penalize files in .context/weights.json sigmap learn --reset Delete learned file weights sigmap weights Show learned file multipliers sigmap weights --json Learned weights as JSON sigmap --impact Show every file impacted by changing sigmap --impact --json Impact as JSON {changed, direct, transitive, tests, routes} sigmap --impact --depth BFS depth limit (default 3, 0=unlimited) sigmap --callers Method-level blast radius — every function that (transitively) calls (JS/TS, Python, Java, Go, Rust) sigmap --callees Every repo function that (transitively) calls sigmap --callers --json --depth Call-graph edges as JSON (depth 0 = unlimited) sigmap verify Flagship grounding guard — flag fake files/tests/imports/symbols/npm-scripts in an AI answer (alias of verify-ai-output) sigmap verify --json Grounding report as JSON (exits 1 if issues) sigmap verify --report Write a standalone HTML report (red/amber/green) sigmap verify-ai-output Full command name for gen-context verify sigmap validate Check config + index coverage; --query "" also probes retrieval (--json) sigmap judge [--response |-] [--context ] Score an AI answer's groundedness (stdin ok; --json, --threshold , --learn) sigmap conventions Extract repo file-naming/export/test conventions (--conflicts, --inject, --report, --fix) sigmap scaffold "" Propose a convention-matched file/dir scaffold (--ext, --threshold, --force, --json) sigmap verify-plan Check a plan vs the live index — files/symbols exist, blast radius, scope (--json) sigmap verify-plan --creates Mark names the plan INTRODUCES (comma-separated) — checked in reverse: they must not exist yet sigmap review-pr Audit a diff — scope drift, god-node edits, missing tests, security files (--staged, --base, --json, --markdown) sigmap review-pr --markdown PR Evidence Report — branded Markdown (signatures + blast radius + tests) to post as a PR comment sigmap create "" Grounded-creation pipeline: scaffold → verify-plan → verify-ai-output → review-pr (--staged, --creates) sigmap wiki Deterministic architecture wiki from signatures + graph — no LLM (--json, --out ) sigmap squeeze Minimize a pasted stacktrace/CI-log/JSON blob (--json for stats) sigmap squeeze --response Minimize an agent/tool response (same engine; also exposed as the squeeze_output MCP tool) sigmap ask "" --squeeze Auto-accept input minimization (no prompt; for scripts/CI) sigmap ask "" --no-squeeze Disable input minimization entirely sigmap ask "" --squeeze-threshold N Min reduction % to prompt (default 30) sigmap deps List declared dependencies across every manifest at the root sigmap deps --json Same, as machine-readable JSON sigmap sbom CycloneDX 1.5 SBOM on stdout (pipe to osv-scanner for CVEs) sigmap sbom --out sbom.json Write the SBOM to a file (--exact-only, --no-dev) sigmap evidence "" Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json sigmap evidence "" --markdown Emit the Markdown handoff rendering to stdout sigmap evidence "" --top --budget --out Tune ranked files / token budget / write rendered output sigmap memory List cross-session stores (.context/) — entries, size, age sigmap memory --clear Clear one store: session|notes|weights|evidence|all (--json supported) sigmap budget Session spend ledger — estimated SigMap-emitted tokens, budget, context age (--json) sigmap budget --budget One-off budget override (config: sessionBudgetTokens, contextTtlDays) sigmap redact [file] Mask secrets in a file or stdin (10-pattern bank); redacted text to stdout (--json) sigmap tune Recommend config from repo detection — srcDirs, monorepo, adapters, exclude, budget (--json) sigmap tune --apply Write the recommendations into gen-context.config.json (merges; your keys preserved) sigmap skills list List skill clients (Claude/Cursor/Windsurf/Copilot/AGENTS.md) and install state (--json) sigmap skills install Install the SigMap agent playbooks for detected clients (--client | --all) sigmap lines - Print an exact line range — CLI twin of get_lines (secrets redacted) sigmap lines : --context Window around one signature anchor (default ±10) sigmap note "" Append a note to the cross-session decision log sigmap note "" --tag Tag a note; todo | open | thread | next surface as open threads in the session summary sigmap note List recent notes (also: note --list ) sigmap history Recent usage-log entries with a sparkline (--last , --json) sigmap compare SigMap vs baseline benchmark; outside the source checkout shows local history (--run, --json) sigmap share Shareable one-liner with your live numbers (copied to clipboard) sigmap bench --submit Format local benchmark history as a shareable community block sigmap roots Detect source roots for this repo (--fix, --json) sigmap sync Write every adapter output + llms.txt and print a compact diff sigmap suggest-profile Infer the task profile from staged changes (--short) sigmap session [list] Captured agent sessions — billed tokens per request category, each labelled with its provenance (--json, --agent , --limit ) sigmap session show One session in full; an unambiguous id prefix works (--json) sigmap session log --transcript --id Record a Claude Code transcript's usage, counted once per message (--agent, --end, --reason ) sigmap session log --from-json Record usage an agent reported itself: {id, agent, model, usage: {in, out, cacheRead, cacheWrite}} sigmap session log --ci Append an agent:"ci" record for this pipeline run (usage is unavailable — a CI job has no transcript) sigmap session summary Warm-start summary of the last session — deterministic, no LLM, ≤400 tokens (--json; `summary --last` is the same call) sigmap session compact Fold sessions older than session.retention.days into monthly rollups (--json) sigmap hooks install claude Wire session capture into Claude Code (--stop adds the per-turn hook; --shared writes the committed settings file) sigmap hooks status Which session hooks are wired, and whether the script they run still exists (--json) sigmap hooks remove claude Remove SigMap's session hooks from Claude Code settings sigmap status Show repo state — branch, dirty files, index freshness, notes sigmap doctor Diagnose config, index, freshness, coverage, MCP wiring — with fixes (--json; exits 1 on hard failure) sigmap mcp list List MCP clients and their config paths (--json) sigmap mcp install Wire MCP for one client (claude|cursor|windsurf|vscode|zed|codex|gemini|opencode|mcp); --global for user-level sigmap --init Write example config + .contextignore scaffold sigmap --help Show this message sigmap --version Show version ``` --- ## MCP server — 22 tools Start with `sigmap --mcp` (stdio JSON-RPC). Configure once: ```json { "mcpServers": { "sigmap": { "command": "npx", "args": ["sigmap", "--mcp"] } } } ``` ### read_context Read extracted code signatures for the project or a specific module path. Returns the full copilot-instructions.md content (~500–4K tokens) or a filtered subset when a module path is provided (~50–500 tokens). ``` Input: { module?: string } ``` ### search_signatures Search extracted code signatures for a keyword, function name, or class name. Returns matching signature lines with their file paths. ``` Input: { query: string } ``` ### get_map Read a section from PROJECT_MAP.md — import graph, class hierarchy, or route table. Requires gen-project-map.js to have been run first. ``` Input: { type: string } ``` ### create_checkpoint Create a session checkpoint summarising current project state. Returns recent git commits, active branch, token count, and a compact snapshot of the codebase context — ideal for session handoffs or periodic saves during long coding sessions. ``` Input: { note?: string } ``` ### get_routing Get model routing hints for this project — which files belong to which complexity tier (fast/balanced/powerful) and which AI model to use for each type of task. Helps reduce API costs by 40–80% by routing simple tasks to cheaper models. ``` Input: { } (no arguments) ``` ### explain_file Explain a specific file: returns its extracted signatures, direct imports (files it depends on), and callers (files that import it). Ideal for understanding a file in isolation without reading raw source. Requires the context file to have been generated first. ``` Input: { path: string } ``` ### list_modules List all top-level modules (srcDirs) present in the context file, sorted by token count descending. Use this to decide which module to pass to read_context before querying a specific area of the codebase. ``` Input: { } (no arguments) ``` ### query_context Rank and return the most relevant files for a specific task or question. Uses keyword + symbol + path scoring to surface only the top-K files relevant to the query — much cheaper than reading all context. Returns ranked file list with signatures and relevance scores. ``` Input: { query: string, topK?: number } ``` ### get_method_impact Method-level blast radius for a symbol: every FUNCTION that (transitively) calls it — or, with direction "callees", every repo function it calls. Finer-grained than the file-level get_impact: tells an agent which functions break, not just which files. JS/TS, Python, Java, Go, and Rust call-graph; deterministic, no LLM. ``` Input: { symbol: string, direction?: string, depth?: number } ``` ### get_impact Show every file that is impacted when a given file changes — direct importers, transitive importers, affected tests, and affected routes/controllers. Gives agents instant blast-radius awareness before making a change. Handles circular dependencies safely (no infinite loops). ``` Input: { file: string, depth?: number } ``` ### get_lines Fetch an exact line range from a source file on demand — the Surgical Context workhorse. Signatures carry `path:start-end` anchors; call this to read just those lines instead of re-opening the whole file. Lines are clamped to the file bounds and secret-scanned (redacted) before return. Path is sandboxed to the project root. ``` Input: { file: string, start: number, end: number } ``` ### read_memory Recall the project decision log — recent notes left by humans or agents across sessions (via `sigmap note`), plus the last ranking-session focus. Call this at the start of a task to kill cold-start: it answers "what were we doing and why" without re-reading the whole codebase. ``` Input: { limit?: number } ``` ### get_callee_signatures Return the EXACT current signature(s) of named symbols (functions, classes, methods) from the index — so an agent never guesses a callee's parameter types from training memory. Call this before writing code that uses a symbol. Unknown names get a closest-match suggestion. ``` Input: { symbols: array } ``` ### sigmap_notify_file_created Tell SigMap a file was created or modified so its signatures are indexed live for the rest of the session. Call this after writing a file — the new symbols become resolvable by search_signatures / get_callee_signatures. ``` Input: { path: string, content?: string } ``` ### sigmap_notify_symbol_added Fast path: register a single new symbol signature directly in the live index without re-reading the whole file. ``` Input: { signature: string, file: string, line?: number } ``` ### sigmap_notify_file_deleted Tell SigMap a file was deleted so its symbols are dropped from the live index. ``` Input: { path: string } ``` ### get_diff_context For every changed file in the working tree (or staged, or vs a base ref), return its current signatures plus blast radius — direct importers, transitive count, and affected tests/routes — with a risk label. One call gives an agent everything a code review or a safe edit needs. Lists changed files shell-free (git binary, never a shell). ``` Input: { base?: string, staged?: boolean, depth?: number } ``` ### get_architecture_overview A high-level map of the codebase in one call: module breakdown (files/tokens), the most depended-on "hub" files, the dependency-cycle count, and route totals. Extends get_map — use it to orient in an unfamiliar repo before drilling in with read_context / query_context. ``` Input: { } (no arguments) ``` ### verify_suggestion Ground an AI code suggestion before writing it: verify a snippet or answer against the repository AND the libraries actually installed in node_modules (the grounding moat). Flags fake file paths, unresolvable imports, symbols that are in neither the repo (its index or its source) nor the installed libraries, and non-existent npm scripts — deterministic, offline, no LLM. Reports the installed libraries it verified against with pinned versions. ``` Input: { code: string } ``` ### squeeze_output Compress noisy tool, command, or agent output before it enters context — a stack trace, CI/build log, or JSON payload. Same deterministic, offline engine as `sigmap squeeze`: keeps the signal (error frames, failing steps, JSON shape), strips the noise, and enriches the top stack frame with its signature. Returns the squeezed text plus token-reduction stats; passes the input through unchanged when no squeezable structure is detected. No LLM, no network. ``` Input: { content: string } ``` ### get_budget Session spend ledger — estimated tokens SigMap has emitted this session (chars/4 estimates from the local gain log), optional budget remaining, and context freshness. Scope honesty: counts only SigMap output, NOT the whole chat's spend. Check this mid-session and degrade gracefully when near budget: prefer terse encoding, squeeze large outputs, summarize-then-drop context. Local-only; no LLM, no network. ``` Input: { session?: string, budgetTokens?: number } ``` ### query_knowledge_map Query the unified knowledge map — typed nodes (file, symbol, library@version, route, env-var, migration, script) and edges (imports, calls, defines, tests, uses-lib, exposes-route, reads-env) assembled from SigMap's existing graphs. Pass { library: "express" } for upgrade impact: the lib → importing files → their callers → covering tests chain. Pass { file: "src/x.js" } for a file's typed neighbors. Pass { env: "DATABASE_URL" } for the files reading an environment variable. Deterministic, cached in .context, local-only; no LLM, no network. ``` Input: { library?: string, file?: string, env?: string } ``` --- ## Configuration (gen-context.config.json) Every config key and its default: ``` output = .github/copilot-instructions.md outputs = ["copilot"] adapters = null srcDirs = ["src","app","lib","packages","services","api","server","client","web","frontend","backend","desktop","mobile","shared","common","core","workers","functions","lambda","cmd","pages","components","hooks","routes","controllers","models","views","resources","config","db","projects","apps","libs","instance","blueprints","src/main/java","src/main/kotlin","src/main/scala","app/src/main/java","app/src/main/kotlin","src/test/java","src/test/kotlin"] exclude = ["node_modules",".git","dist","build","out","__pycache__",".next","coverage","target","vendor",".context","playwright-tmp","playwright-report","test-results",".turbo","storybook-static",".docusaurus"] maxDepth = 6 maxSigsPerFile = 25 maxTokens = 6000 autoMaxTokens = true coverageTarget = 0.8 modelContextLimit = 128000 models = {"asOf":null,"roster":[],"prices":{},"windows":{},"cacheMin":{},"charsPerToken":{},"tiers":{}} maxTokensHeadroom = 0.2 secretScan = true monorepo = false diffPriority = true strategy = full hotCommits = 10 watchDebounce = 300 watchIncremental = true watchSettleMs = 5000 routing = false judge = {"threshold":0.25,"learnBoostAbove":0.75,"learnPenalizeBelow":0.4} format = default cacheLayout = stable-prefix cacheTtl = 5m tracking = false sessionBudgetTokens = null contextTtlDays = null session = {"retention":{"days":90,"compact":"monthly"},"logQueries":"hashed","injectSummary":false,"mcpCapture":false} mcp = {"autoRegister":true} depMap = true versionPins = true terse = false todos = true changes = true changesCommits = 10 testCoverage = false testDirs = ["tests","test","__tests__","spec"] sigCache = false impactRadius = false retrieval = {"topK":10,"recencyBoost":1.5,"callGraphBoost":false,"centralityBlend":false,"surfaceEnrichment":false,"minedExpansions":false,"bodyWords":true} exactness = {"typescript":false,"lsp":false,"lspServers":{},"scip":false} impact = {"depth":3,"includeSigs":true} ``` --- ## Supported languages (38 extractors) astro, cpp, csharp, css, dart, dockerfile, elixir, gdscript, go, graphql, html, java, javascript, kotlin, lua, markdown, objc, php, pipeline, powershell, properties, protobuf, python, r, ruby, rust, scala, shell, sql, svelte, swift, terraform, toml, typescript, typescript_react, vue_sfc, xml, yaml --- ## Integrations Generates native context files for: claude, codex, copilot, cursor, gemini, openai, willow, windsurf — plus an MCP server for any agent (Claude Code, Cursor, Cline, Windsurf, OpenCode, Gemini CLI, Aider). One `sigmap --setup` wires the lot. --- ## Compliance evidence support SigMap can surface repository facts that *support* technical-evidence narratives (e.g. DORA Art. 8–11, NIS2 Art. 21, ISO 27001 A.8) — it is a **technical evidence pack**, never a certification or a "compliance report". Signed evidence packs are planned for a later release. Any compliance-adjacent wording is reviewed against the relevant regulation before publication; SigMap makes no legal claims. --- ## Project information - Author: Manoj Mallick - License: MIT - Repository: https://github.com/manojmallick/sigmap - Documentation: https://sigmap.io/ - npm: https://www.npmjs.com/package/sigmap - Benchmark dataset: https://doi.org/10.5281/zenodo.19898842 - Issues: https://github.com/manojmallick/sigmap/issues --- ## What SigMap does not do - **No embeddings / vector database.** Ranking is deterministic BM25 over extracted signatures and each file's rare source words — reproducible and offline, not a semantic vector search. - **No code execution.** SigMap reads source statically; it never runs your code. - **No network calls** on the core generate/ask/verify paths. Nothing is uploaded; generation works fully offline. - **Not a linter or type checker.** It maps and ranks code structure; it does not judge correctness (use `verify-ai-output` only to flag *fabricated* references). - **Not a full file reader.** It emits signatures + line anchors; an agent fetches exact bodies on demand via the `get_lines` MCP tool. - **No telemetry.** Usage tracking (`--track`, `.context/usage.ndjson`) is local and opt-in; nothing leaves your machine.