# 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.82.0 | Benchmark: sigmap-v8.82-main (2026-10-23)
# 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.82-main, 2026-10-23)

| 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 <name>, --limit <n>)
sigmap --dashboard [--out <path>]        Write .context/dashboard.html (HTML health dashboard)
sigmap --suggest-tool "<task>"           Recommend model tier for a task description
sigmap --suggest-tool "<task>" --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 <n> | --model <name>   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 <base-ref>                 Changed files: working tree vs <base-ref> (incl. uncommitted)
sigmap --diff --staged                   Changed files: index vs HEAD (staged only)
sigmap --benchmark                       Run retrieval benchmark (benchmarks/tasks/retrieval.jsonl)
sigmap --adapter <name>                  Generate for a specific adapter only (v3.0+)
sigmap --adapter <name> --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 "<text>"                  Rank files by relevance to a query
sigmap --query "<text>" --json           Ranked results as JSON
sigmap --query "<text>" --top <n>        Limit results to top N files (default 10)
sigmap --query "<text>" --explain        Per-file score signals, token coverage and near misses
sigmap ask "<query>"                     Ranked files for a question, signatures written to .context/query-context.md (--json, --top <n>, --mode)
sigmap ask "<query>" --verbose           Also print the full header: intent, coverage, risk, cost (default: files + one summary line)
sigmap ask "<query>" --explain           Diagnose a miss: which tokens matched, why files were demoted
sigmap ask "<query>" --with-source       Add top-symbol bodies + blast radius (budgeted; --source-budget <n>)
sigmap plan "<goal>"                     Files to inspect, likely-to-change set, and impact radius (--json)
sigmap explain <file>                    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 <files...>           Boost files in .context/weights.json
sigmap learn --bad <files...>            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 <file>                   Show every file impacted by changing <file>
sigmap --impact <file> --json            Impact as JSON {changed, direct, transitive, tests, routes}
sigmap --impact <file> --depth <n>       BFS depth limit (default 3, 0=unlimited)
sigmap --callers <symbol>                Method-level blast radius — every function that (transitively) calls <symbol> (JS/TS, Python, Java, Go, Rust)
sigmap --callees <symbol>                Every repo function that <symbol> (transitively) calls
sigmap --callers <symbol> --json --depth <n>  Call-graph edges as JSON (depth 0 = unlimited)
sigmap verify <answer.md>                Flagship grounding guard — flag fake files/tests/imports/symbols/npm-scripts in an AI answer (alias of verify-ai-output)
sigmap verify <answer.md> --json         Grounding report as JSON (exits 1 if issues)
sigmap verify <answer.md> --report       Write a standalone HTML report (red/amber/green)
sigmap verify-ai-output <answer.md>      Full command name for gen-context verify
sigmap validate                          Check config + index coverage; --query "<text>" also probes retrieval (--json)
sigmap judge [--response <f>|-] [--context <f>]  Score an AI answer's groundedness (stdin ok; --json, --threshold <n>, --learn)
sigmap conventions                       Extract repo file-naming/export/test conventions (--conflicts, --inject, --report, --fix)
sigmap scaffold "<name>"                 Propose a convention-matched file/dir scaffold (--ext, --threshold, --force, --json)
sigmap verify-plan <plan.md|->           Check a plan vs the live index — files/symbols exist, blast radius, scope (--json)
sigmap verify-plan <plan.md> --creates <names>  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 "<task>"                   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 <path>)
sigmap squeeze <file|->                  Minimize a pasted stacktrace/CI-log/JSON blob (--json for stats)
sigmap squeeze --response <file|->       Minimize an agent/tool response (same engine; also exposed as the squeeze_output MCP tool)
sigmap ask "<query>" --squeeze           Auto-accept input minimization (no prompt; for scripts/CI)
sigmap ask "<query>" --no-squeeze        Disable input minimization entirely
sigmap ask "<query>" --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 "<query>"                Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json
sigmap evidence "<query>" --markdown     Emit the Markdown handoff rendering to stdout
sigmap evidence "<query>" --top <n> --budget <n> --out <path>  Tune ranked files / token budget / write rendered output
sigmap memory                            List cross-session stores (.context/) — entries, size, age
sigmap memory --clear <store>            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 <tokens>          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 <name> | --all)
sigmap lines <file> <start>-<end>        Print an exact line range — CLI twin of get_lines (secrets redacted)
sigmap lines <file> :<line> --context <n>  Window around one signature anchor (default ±10)
sigmap note "<text>"                     Append a note to the cross-session decision log
sigmap note "<text>" --tag <name>        Tag a note; todo | open | thread | next surface as open threads in the session summary
sigmap note                              List recent notes (also: note --list <N>)
sigmap history                           Recent usage-log entries with a sparkline (--last <n>, --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 <name>, --limit <n>)
sigmap session show <id>                 One session in full; an unambiguous id prefix works (--json)
sigmap session log --transcript <file> --id <session_id>  Record a Claude Code transcript's usage, counted once per message (--agent, --end, --reason <why>)
sigmap session log --from-json <file|->  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 <client>              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 whole project, or only a module path (~50–500 tokens scoped, ~500–4K for everything).

```
Input:  { module?: string }
```

### search_signatures

Search extracted signatures for a keyword, function name or class name; returns matching lines with their file paths.

```
Input:  { query: string }
```

### get_map

Read a section of PROJECT_MAP.md: import graph, class hierarchy or route table. Needs gen-project-map.js to have been run.

```
Input:  { type: string }
```

### create_checkpoint

Snapshot project state for a session handoff: recent commits, branch, token count and a compact context.

```
Input:  { note?: string }
```

### get_routing

Model routing hints: which files sit in which complexity tier (fast/balanced/powerful) and which model suits each type of task.

```
Input:  { } (no arguments)
```

### explain_file

Explain one file without reading its source: its signatures, what it imports and what imports it. Needs a generated context file.

```
Input:  { path: string }
```

### list_modules

List the top-level modules (srcDirs) in the context file by token count, to pick a module for read_context.

```
Input:  { } (no arguments)
```

### query_context

Rank files for a task or question and return the top-K with signatures and relevance scores — far cheaper than reading all context.

```
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 than get_impact — which functions break, not just which files. JS/TS, Python, Java, Go, Rust; deterministic.

```
Input:  { symbol: string, direction?: string, depth?: number }
```

### get_impact

Blast radius of changing a file — check it before an edit: direct and transitive importers, affected tests, routes and controllers.

```
Input:  { file: string, depth?: number }
```

### get_lines

Fetch an exact line range from a file — use the `path:start-end` anchors in signatures instead of re-opening the whole file. Clamped to the file bounds, secret-redacted, sandboxed to the project root.

```
Input:  { file: string, start: number, end: number }
```

### read_memory

Recall the project decision log — recent notes left across sessions (via `sigmap note`) plus the last ranking-session focus. Call at the start of a task to answer "what were we doing and why" without re-reading the codebase.

```
Input:  { limit?: number }
```

### get_callee_signatures

Return the EXACT current signature(s) of named symbols from the index, so you never guess a callee's parameter types from memory. Call before writing code that uses a symbol; unknown names get a closest-match suggestion.

```
Input:  { symbols: array }
```

### sigmap_notify_file_created

Call after writing or changing a file so its signatures are indexed live for this session (new symbols become resolvable by search_signatures / get_callee_signatures).

```
Input:  { path: string, content?: string }
```

### sigmap_notify_symbol_added

Fast path: register one new symbol signature in the live index without re-reading the file.

```
Input:  { signature: string, file: string, line?: number }
```

### sigmap_notify_file_deleted

Tell SigMap a file was deleted so its symbols leave the live index.

```
Input:  { path: string }
```

### get_diff_context

For every changed file (working tree, staged, or vs a base ref): its current signatures plus blast radius — importers, affected tests/routes — with a risk label. One call for a code review or a safe edit. Lists changed files shell-free.

```
Input:  { base?: string, staged?: boolean, depth?: number }
```

### get_architecture_overview

One-call map of the codebase: module breakdown (files/tokens), the most depended-on hub files, dependency-cycle count and route totals. Extends get_map; use it to orient before read_context / query_context.

```
Input:  { } (no arguments)
```

### verify_suggestion

Ground an AI code suggestion before writing it: check a snippet or answer against the repository AND the libraries actually installed in node_modules. Flags fake file paths, unresolvable imports, symbols in neither the repo nor the installed libraries, and non-existent npm scripts. Deterministic, offline, no LLM.

```
Input:  { code: string }
```

### squeeze_output

Compress noisy output (stack trace, CI/build log, JSON payload) before it enters context: keeps error frames, failing steps and JSON shape, strips the noise, adds the top frame's signature. Returns the squeezed text plus reduction stats; unchanged when nothing is squeezable. Deterministic, offline.

```
Input:  { content: string }
```

### get_budget

Session spend ledger: estimated tokens SigMap has emitted this session (chars/4, local gain log — NOT the whole chat), optional budget remaining, and context freshness. Check mid-session and degrade gracefully near budget (terse encoding, squeeze, summarize).

```
Input:  { session?: string, budgetTokens?: number }
```

### query_knowledge_map

Query the typed knowledge map: nodes (file, symbol, library@version, route, env-var, migration, script) and edges (imports, calls, defines, tests, uses-lib, exposes-route, reads-env). { library } = upgrade impact (lib → importing files → callers → covering tests); { file } = a file's typed neighbors; { env } = files reading an environment variable. Deterministic, cached in .context, local-only.

```
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
maxIndexSigsPerFile = 200
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,"tools":"all"}
depMap = true
versionPins = true
terse = false
todos = true
changes = true
changesCommits = 10
testCoverage = false
testDirs = ["tests","test","__tests__","spec"]
sigCache = false
extractCache = true
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.
