⚡ SigMap

WITHOUT SIGMAP, YOUR AI IS GUESSING.
Without structured context, AI often reads the wrong file and fills the gaps with guesses.

_{Run one command. Force every answer to come from real code.}

npx sigmap   # 10 seconds. zero config. your AI never reads the wrong file again.

What you get in ~10 seconds

A compact signature map of your codebase
The right file in context far more often (78.9% hit@5 vs 13.6% random)
Fewer retries (1.69 vs 2.84 prompts per task)
Far smaller context (~2K–4K tokens instead of ~80K)

Latest: v5.6.0 — Website & docs sync. All guide pages updated to v5.5 reality: canonical metrics, judge vocabulary, language count, MCP tool count, and troubleshooting coverage entry. (sigmap.nvim). :SigMap, :SigMapQuery, auto-run on save, statusline widget, and :checkhealth sigmap for the #1 most-admired editor.

What is new in v5.2

sigmap ask creates task-focused context in one step
sigmap validate checks config health and query coverage
sigmap judge scores groundedness against the supplied context
sigmap learn and sigmap weights add safe local-only ranking feedback
node scripts/run-benchmark-matrix.mjs --save --skip-clone now writes an HTML benchmark dashboard

Daily workflow

npx sigmap
sigmap ask "explain the auth flow"
sigmap validate --query "auth login token"
sigmap judge --response response.txt --context .context/query-context.md
sigmap weights

SigMap demo — reducing 80K tokens to 4K in under 10 seconds

Trust signals

Full benchmark breakdown →

SigMap benchmark — before vs after across 3 RAG quality metrics

_{90 tasks · 18 real repos · no LLM API · full methodology →}

	Without SigMap	With SigMap
Task success	10%	52.2%
Prompts per task	2.84	1.69
Tokens per session	~80,000	~2,000
Right file found	13.6%	78.9%
Hidden-symbol risk	74.7%	context surfaced locally

Measured on 90 coding tasks across 18 real public repos. Full methodology and raw benchmark pages are linked below.


What it does	Token reduction table, pipeline overview
Quick start	Install (binary or npm), generate in 60 seconds
Standalone binaries	macOS, Linux, Windows — no Node required
VS Code extension	Status bar, stale alerts, commands
JetBrains plugin	IntelliJ IDEA, WebStorm, PyCharm support
Neovim plugin	`:SigMap`, `:SigMapQuery`, statusline, health check
Languages supported	29 languages
Context strategies	full / per-module / hot-cold
MCP server	8 on-demand tools
CLI reference	All flags
Configuration	Config file + .contextignore
Observability	Health score, reports, CI
Programmatic API	Use as a Node.js library
Testing	Run the test suite
Project structure	File-by-file map
Principles	Design decisions

📖 New to SigMap? Read the Complete Getting Started Guide — token savings walkthrough, every command, VS Code plugin, and CI setup.

🔍 What it does

SigMap scans your source files and extracts only the function and class signatures — no bodies, no imports, no comments — then writes a compact context file that Copilot, Claude, Cursor, and Windsurf read automatically. Every session starts with full codebase awareness at a fraction of the token cost.

Your codebase
    │
    ▼
sigmap ─────────► extracts signatures from 29 languages
    │
    ▼
.github/copilot-instructions.md   ◄── auto-read by Copilot / Claude / Cursor
    │
    ▼
AI agent session starts with full context

Dogfooding: SigMap runs on itself — 40 JS files, 8,600 lines of code. View the generated context: .github/copilot-instructions.md

Token reduction at every stage

Stage	Tokens	Reduction
Raw source files	~80,000	—
Repomix compressed	~8,000	90%
SigMap signatures	~4,000	95%
SigMap + MCP (`hot-cold`)	~200	99.75%

98.1% fewer tokens in the latest saved benchmark snapshot.

Benchmark: real-world repos

Reproduced with node scripts/run-benchmark.mjs on public repos:

Repo	Language	Raw tokens	After SigMap	Reduction
express	JavaScript	70.6K	911	98.7%
flask	Python	147.9K	6.7K	95.4%
gin	Go	216.4K	6.0K	97.2%
spring-petclinic	Java	97.9K	3.4K	96.5%
rails	Ruby	1.5M	7.1K	99.5%
axios	TypeScript	105.7K	6.1K	94.3%
rust-analyzer	Rust	3.5M	6.3K	99.8%
abseil-cpp	C++	2.3M	6.3K	99.7%
serilog	C#	195.5K	6.9K	96.4%
riverpod	Dart	747.2K	6.5K	99.1%
okhttp	Kotlin	31.3K	1.4K	95.5%
laravel	PHP	1.7M	7.2K	99.6%
akka	Scala	790.5K	7.1K	99.1%
vapor	Swift	171.4K	6.4K	96.2%
vue-core	Vue	414.4K	8.6K	97.9%
svelte	Svelte	438.2K	8.0K	98.2%
fastify	JavaScript	54.4K	2.6K	95.3%
fastapi	Python	178.4K	5.2K	97.1%

Average: 97.6% reduction across 18 repos (16 languages). See benchmarks/reports/token-reduction.md, open benchmarks/reports/benchmark-report.html after a matrix run, or reproduce with node scripts/run-benchmark.mjs.

⚡ Installation

Pick the method that fits your workflow — all produce the same output.

npx — try without installing

npx sigmap

Runs the latest version without any permanent install. Great for a quick try.

npm global — install once, run anywhere

npm install -g sigmap
sigmap

Available from any directory on your machine.

Standalone binaries — no Node.js, no npm

Download from the latest release:

https://github.com/manojmallick/sigmap/releases/latest

Available assets:

sigmap-darwin-arm64 (macOS Apple Silicon)
sigmap-linux-x64 (Linux x64)
sigmap-win32-x64.exe (Windows x64)
sigmap-checksums.txt (SHA-256 checksums)

macOS / Linux

Run directly:

chmod +x ./sigmap-darwin-arm64   # or ./sigmap-linux-x64
./sigmap-darwin-arm64 --help
./sigmap-darwin-arm64

Make it globally available in Bash/Zsh (no ./ needed):

# 1) Pick a user bin dir and move/rename the binary
mkdir -p "$HOME/.local/bin"
mv ./sigmap-darwin-arm64 "$HOME/.local/bin/sigmap"   # or sigmap-linux-x64
chmod +x "$HOME/.local/bin/sigmap"

# 2) Add to PATH in your shell profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zshrc"    # zsh
# echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"  # bash

# 3) Reload shell and verify
source "$HOME/.zshrc"   # or: source "$HOME/.bashrc"
sigmap --version

Windows (PowerShell)

Run directly:

.\sigmap-win32-x64.exe --help
.\sigmap-win32-x64.exe

Make it globally available:

# 1) Create a user bin directory and rename the binary
New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
Move-Item .\sigmap-win32-x64.exe "$HOME\bin\sigmap.exe"

# 2) Add user bin to PATH (current user)
[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";$HOME\bin",
  "User"
)

# 3) Restart PowerShell and verify
sigmap --version

Optional checksum verification:

shasum -a 256 sigmap-darwin-arm64
# Compare with sigmap-checksums.txt

Full guide: docs/readmes/binaries.md

npm local — per-project, version-pinned

npm install --save-dev sigmap

Add to package.json scripts for team consistency:

{
  "scripts": {
    "context": "sigmap",
    "context:watch": "sigmap --watch"
  }
}

Run with npm run context. Version is pinned per project.

Volta — team-friendly, auto-pinned version

volta install sigmap
sigmap

Volta pins the exact version in package.json — every team member runs the same version automatically without configuration.

Single-file download — no npm, any machine

curl -O https://raw.githubusercontent.com/manojmallick/sigmap/main/gen-context.js
node gen-context.js

No npm, no node_modules. Drop gen-context.js into any project and run it directly. Requires only Node.js 18+. Ideal for CI, locked-down environments, or one-off use.

🚀 Features

Multi-adapter output

Generate context for any AI assistant from a single run:

sigmap --adapter copilot    # → .github/copilot-instructions.md
sigmap --adapter claude     # → CLAUDE.md (appended below marker)
sigmap --adapter cursor     # → .cursorrules
sigmap --adapter windsurf   # → .windsurfrules
sigmap --adapter openai     # → .github/openai-context.md
sigmap --adapter gemini     # → .github/gemini-context.md (appended below marker)
sigmap --adapter codex      # → AGENTS.md (appended below marker)

Adapter	Output file	AI assistant
`copilot`	`.github/copilot-instructions.md` (append)	GitHub Copilot
`claude`	`CLAUDE.md` (append)	Claude / Claude Code
`cursor`	`.cursorrules`	Cursor
`windsurf`	`.windsurfrules`	Windsurf
`openai`	`.github/openai-context.md`	Any OpenAI model
`gemini`	`.github/gemini-context.md` (append)	Google Gemini
`codex`	`AGENTS.md` (append)	OpenAI Codex

Configure multiple adapters at once in gen-context.config.json:

{ "outputs": ["copilot", "claude", "cursor"] }

Programmatic API

Use SigMap as a Node.js library without spawning a subprocess. See the full API reference below.

Custom output path

Write signatures to any file location — useful for shared docs folders, monorepos, or tooling that expects context at a non-standard path:

sigmap --output .context/ai-context.md           # write to custom path
sigmap --adapter claude --output shared/sigs.md  # adapter + custom path

The path is persisted to gen-context.config.json, so --query finds it automatically on subsequent runs — no need to pass --output again:

sigmap --output .context/ai-context.md  # generates and saves the path
sigmap --query "add an extractor"        # auto-discovers .context/ai-context.md

Query-aware retrieval

Find the most relevant files for any task without reading the whole codebase:

sigmap --query "authentication middleware"   # ranked file list
sigmap --query "auth" --json                 # machine-readable output
sigmap --query "auth" --top 5               # top 5 results only
sigmap --query "auth" --adapter claude       # query against CLAUDE.md specifically

Diagnostic and evaluation tools

sigmap --analyze                  # per-file: sigs, tokens, extractor, coverage
sigmap --analyze --slow           # include extraction timing
sigmap --diagnose-extractors      # self-test all 21 extractors against fixtures
sigmap --benchmark                # hit@5 and MRR retrieval quality
sigmap --benchmark --json         # machine-readable benchmark results

⚡ Quick start

Install

Standalone binary — no Node.js or npm 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`

# macOS / Linux
chmod +x ./sigmap-darwin-arm64
./sigmap-darwin-arm64

See docs/readmes/binaries.md for Gatekeeper / SmartScreen notes and checksum verification.

npm (requires Node.js 18+):

npx sigmap                  # run once without installing
npm install -g sigmap       # install globally

Generate context

Once installed, run from your project root:

sigmap                         # generate once and exit
sigmap --watch                 # regenerate on every file save
sigmap --setup                 # generate + install git hook + start watcher
sigmap --diff                  # context for git-changed files only (PR mode)
sigmap --diff --staged         # staged files only (pre-commit check)
sigmap --health                # show context health score (grade A–D)
sigmap --mcp                   # start MCP server on stdio

Companion tool: Repomix

SigMap and Repomix are complementary, not competing:

Tool	When to use
SigMap	Always-on, git hooks, daily signature index (~4K tokens)
Repomix	On-demand deep sessions, full file content, broader language support

sigmap --setup         # always-on context
npx repomix --compress # deep dive sessions

"SigMap for daily always-on context; Repomix for deep one-off sessions — use both."

🧩 VS Code extension

The official SigMap VS Code extension keeps your context fresh without any manual commands. Install it once and it runs silently in the background.

Feature	Detail
Status bar item	Shows health grade (`A`/`B`/`C`/`D`) + time since last regen; refreshes every 60 s
Stale notification	Warns when `copilot-instructions.md` is > 24 h old; one-click regeneration
Regenerate command	`SigMap: Regenerate Context` — runs `sigmap` in the integrated terminal
Open context command	`SigMap: Open Context File` — opens `.github/copilot-instructions.md`
Script path setting	`sigmap.scriptPath` — override the path to the `sigmap` binary or `gen-context.js`

SigMap VS Code extension — status bar, stale notification, regenerate context

Activates on startup (onStartupFinished) — loads within 3 s, never blocks editor startup.

Install: VS Code Marketplace | Open VSX Registry

🔧 JetBrains plugin

The official SigMap JetBrains plugin brings the same features to IntelliJ-based IDEs. Install it from the JetBrains Marketplace and it works identically to the VS Code extension.

Feature	Detail
Status bar widget	Shows health grade (`A`-`F`) + time since last regen; updates every 60 s
Regenerate action	`Tools → SigMap → Regenerate Context` or Ctrl+Alt+G — runs `sigmap`
Open context action	`Tools → SigMap → Open Context File` — opens `.github/copilot-instructions.md`
View roadmap action	`Tools → SigMap → View Roadmap` — opens roadmap in browser
One-click regen	Click status bar widget to regenerate context instantly

Compatible with IntelliJ IDEA 2024.1+ (Community & Ultimate), WebStorm, PyCharm, GoLand, RubyMine, PhpStorm, and all other IntelliJ-based IDEs.

Install: JetBrains Marketplace | Manual setup guide

🖥️ Neovim plugin

The official SigMap Neovim plugin (sigmap.nvim) brings first-class integration to the #1 most-admired editor (Stack Overflow 2025, 83% admiration rate). Power users who live in the terminal get context regeneration, ranked retrieval, and health checks without leaving Neovim.

Feature	Detail
`:SigMap [args]`	Regenerate your AI context file asynchronously
`:SigMapQuery <text>`	TF-IDF ranked retrieval — results appear in a centered floating window
Auto-run on save	`auto_run = true` triggers regen on `BufWritePost` for `.js/ts/py/go/rs/java/rb/lua`
Statusline widget	`require('sigmap').statusline()` returns `sm:✓` (fresh) or `sm:⚠ Nh` (stale)
`:checkhealth sigmap`	Validates Node 18+, binary presence, and context file freshness
Binary auto-detection	Finds `sigmap` → `npx sigmap` → local `gen-context.js` automatically

Install (lazy.nvim):

{ 'manojmallick/sigmap.nvim',
  config = function()
    require('sigmap').setup({
      auto_run    = true,   -- regenerate on save
      float_query = true,   -- show query results in a floating window
    })
  end,
}

Repo: manojmallick/sigmap.nvim

🌐 Languages supported

29 languages and formats. All implemented with zero external dependencies — pure regex + Node built-ins.

Also includes lightweight config/doc extraction for .toml, .properties, .xml, and .md to improve real-repo coverage beyond source-code files.

Show all 29 languages

Language	Extensions	Extracts
TypeScript	`.ts` `.tsx`	interfaces, classes, functions, types, enums
JavaScript	`.js` `.jsx` `.mjs` `.cjs`	classes, functions, exports
Python	`.py` `.pyw`	classes, methods, functions
Java	`.java`	classes, interfaces, methods
Kotlin	`.kt` `.kts`	classes, data classes, functions
Go	`.go`	structs, interfaces, functions
Rust	`.rs`	structs, impls, traits, functions
C#	`.cs`	classes, interfaces, methods
C/C++	`.cpp` `.c` `.h` `.hpp` `.cc`	classes, functions, templates
Ruby	`.rb` `.rake`	classes, modules, methods
PHP	`.php`	classes, interfaces, functions
Swift	`.swift`	classes, structs, protocols, functions
Dart	`.dart`	classes, mixins, functions
Scala	`.scala` `.sc`	objects, classes, traits, functions
Vue	`.vue`	`<script>` functions and components
Svelte	`.svelte`	`<script>` functions and exports
HTML	`.html` `.htm`	custom elements and script functions
CSS/SCSS	`.css` `.scss` `.sass` `.less`	custom properties and keyframes
YAML	`.yml` `.yaml`	top-level keys and pipeline jobs
Shell	`.sh` `.bash` `.zsh` `.fish`	function declarations
SQL	`.sql`	tables, views, indexes, functions, procedures
GraphQL	`.graphql` `.gql`	types, interfaces, enums, operations, fragments
Terraform	`.tf` `.tfvars`	resources, modules, variables, outputs
Protobuf	`.proto`	messages, services, rpc, enums
Dockerfile	`Dockerfile` `Dockerfile.*`	stages and key instructions

🗂 Context strategies

Reduce always-injected tokens by 70–90%.

Set "strategy" in gen-context.config.json:

Strategy	Always-injected	Context lost?	Needs MCP?	Best for
`full`	~4,000 tokens	No	No	Starting out, cross-module work
`per-module`	~100–300 tokens	No	No	Large codebases, module-focused sessions
`hot-cold`	~200–800 tokens	Cold files only	Yes	Claude Code / Cursor with MCP enabled

`full` — default, works everywhere

{ "strategy": "full" }

One file, all signatures, always injected on every question.

`per-module` — 70% fewer injected tokens, zero context loss

{ "strategy": "per-module" }

One .github/context-<module>.md per top-level source directory, plus a tiny overview table. Load the relevant module file for focused sessions. No MCP required.

.github/copilot-instructions.md   ← overview table, ~117 tokens (always-on)
.github/context-server.md         ← server/ signatures, ~2,140 tokens
.github/context-web.md            ← web/ signatures,    ~335 tokens
.github/context-desktop.md        ← desktop/ signatures, ~1,583 tokens

`hot-cold` — 90% fewer injected tokens, requires MCP

{ "strategy": "hot-cold", "hotCommits": 10 }

Recently committed files are hot (auto-injected). Everything else is cold (on-demand via MCP). Best reduction available — ~200 tokens always-on.

📖 Full guide: docs/readmes/CONTEXT_STRATEGIES.md — decision tree, scenario comparisons, migration steps.

🔌 MCP server

Start the MCP server on stdio:

sigmap --mcp

Available tools

Tool	Input	Output
`read_context`	`{ module?: string }`	Signatures for one module or entire codebase
`search_signatures`	`{ query: string }`	Matching signatures with file paths
`get_map`	`{ type: "imports"\|"classes"\|"routes" }`	Structural section from `PROJECT_MAP.md`
`explain_file`	`{ path: string }`	Signatures + imports + reverse callers for one file
`list_modules`	—	Token-count table of all top-level module directories
`create_checkpoint`	`{ summary: string }`	Write a session checkpoint to `.context/`
`get_routing`	—	Full model routing table
`query_context`	`{ query: string, topK?: number }`	Files ranked by relevance to the query

Reads files on every call — no stale state, no restart needed.

📖 Setup guide: docs/readmes/MCP_SETUP.md

⚙️ CLI reference

See CHANGELOG.md for the full history.

All flags are the same regardless of how you invoke SigMap — swap the prefix to match your install:

sigmap · npx sigmap · gen-context · node gen-context.js

All flags

sigmap                                        Generate once and exit
sigmap --watch                                Generate and watch for file changes
sigmap --setup                                Generate + install git hook + start watcher
sigmap --diff                                 Generate context for git-changed files only
sigmap --diff --staged                        Staged files only (pre-commit check)
sigmap --mcp                                  Start MCP server on stdio

sigmap --output <file>                        Write signatures to a custom path (persists for --query)
sigmap --output <file> --adapter <name>       Adapter output + custom copy

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>" --adapter <name>      Query against a specific adapter's output file
sigmap --query "<text>" --output <file>       Query against a specific custom file

sigmap --analyze                              Per-file breakdown (sigs / tokens / extractor / coverage)
sigmap --analyze --json                       Analysis as JSON
sigmap --analyze --slow                       Include extraction timing per file
sigmap --diagnose-extractors                  Self-test all 21 extractors against fixtures

sigmap --benchmark                            Run retrieval quality benchmark (hit@5 / MRR)
sigmap --benchmark --json                     Benchmark results as JSON
sigmap --eval                                 Alias for --benchmark

sigmap --report                               Token reduction stats
sigmap --report --json                        Structured JSON report (exits 1 if over budget)
sigmap --report --history                     Usage log summary
sigmap --report --history --json              Usage history as JSON

sigmap --health                               Composite health score (0–100, grade A–D)
sigmap --health --json                        Machine-readable health JSON

sigmap --suggest-tool "<task>"                Recommend model tier for a task
sigmap --suggest-tool "<task>" --json         Machine-readable tier recommendation

sigmap --monorepo                             Per-package context for monorepos (packages/, apps/, services/)
sigmap --each                                 Process each sub-repo under a parent directory
sigmap --routing                              Include model routing hints in output
sigmap --format cache                         Write Anthropic prompt-cache JSON
sigmap --track                                Append run metrics to .context/usage.ndjson

sigmap --init                                 Write config + .contextignore scaffold
sigmap --version                              Version string
sigmap --help                                 Usage information

Task classification — `--suggest-tool`

sigmap --suggest-tool "security audit of the auth module"
# tier   : powerful
# models : claude-opus-4-6, gpt-5-4, gemini-2-5-pro

sigmap --suggest-tool "fix a typo in the yaml config" --json
# {"tier":"fast","label":"Fast (low-cost)","models":"claude-haiku-4-5, ...","costHint":"~$0.0008 / 1K tokens"}

Tiers: fast (config/markup/typos) · balanced (features/tests/debug) · powerful (architecture/security/multi-file)

🔒 Security scanning

SigMap automatically redacts secrets from all extracted signatures. Ten patterns are checked on every file:

Pattern	Example match
AWS Access Key	`AKIA...`
AWS Secret Key	40-char base64
GCP API Key	`AIza...`
GitHub Token	`ghp_...` `gho_...`
JWT	`eyJ...`
DB Connection String	`postgres://user:pass@...`
SSH Private Key	`-----BEGIN ... PRIVATE KEY-----`
Stripe Key	`sk_live_...` `sk_test_...`
Twilio Key	`SK[32 hex chars]`
Generic secret	`password = "..."`, `api_key: "..."`

If a match is found, the signature is replaced with [REDACTED — {pattern} detected in {file}]. The run continues — no silent failures.

⚙️ Configuration

Copy gen-context.config.json.example to gen-context.config.json:

{
  "output": ".github/copilot-instructions.md",
  "srcDirs": ["src", "app", "lib"],
  "outputs": ["copilot"],
  "secretScan": true,
  "strategy": "full",
  "watchDebounce": 300,
  "tracking": false
}

Key fields:

output — custom path for the primary markdown output file (used by copilot adapter). Default: .github/copilot-instructions.md
outputs — which adapters to write to: copilot | claude | cursor | windsurf
srcDirs — directories to scan (relative to project root)
secretScan — redact secrets (AWS keys, tokens, etc.) from output
strategy — output mode: full (default) | per-module | hot-cold

Token budget (auto-scaling):

Key	Default	Description
`autoMaxTokens`	`true`	Auto-scale budget to repo size. Set `false` to pin a fixed `maxTokens`.
`coverageTarget`	`0.80`	Fraction of source files to target (0.0–1.0).
`modelContextLimit`	`128000`	Model context window size. Hard cap = `limit × maxTokensHeadroom`.
`maxTokensHeadroom`	`0.20`	Fraction of the context window reserved for SigMap output (default: 25 600 tokens).
`maxTokens`	`6000`	Used only when `autoMaxTokens: false`, or as a floor.

The formula: effective = clamp(ceil(totalSigTokens × coverageTarget), 4000, floor(modelContextLimit × maxTokensHeadroom)).

Exclusions go in .contextignore (gitignore syntax). Also reads .repomixignore if present.

# .contextignore
node_modules/
dist/
build/
*.generated.*
test/fixtures/

Run sigmap --init to scaffold both files in one step.

Output targets

Key	Output file	Read by
`"copilot"`	`.github/copilot-instructions.md` (or custom path via `output`)	GitHub Copilot
`"claude"`	`CLAUDE.md` (appends below marker)	Claude Code
`"cursor"`	`.cursorrules`	Cursor
`"windsurf"`	`.windsurfrules`	Windsurf

The output config key sets the primary output file path. It is used by the copilot adapter when enabled. Other adapters always write to their fixed paths.

Example:

{
  "output": ".context/ai-context.md",
  "outputs": ["copilot"]
}

This writes to .context/ai-context.md instead of .github/copilot-instructions.md.

If output is omitted, the default .github/copilot-instructions.md is used.

📊 Observability

Coverage score

Every run now prints a coverage line alongside token reduction:

───────────────────────────────────────────
 SigMap v5.6.0
 Files scanned  : 76
 Symbols found  : 332
 Token reduction: 94%  (65,227 → 4,103)
 Coverage       : A (97%)  — 76 of 78 source files included  [budget: 4000 auto-scaled]
 Output         : .github/copilot-instructions.md
───────────────────────────────────────────

The coverage score answers how much of your codebase is represented in context after the token budget is applied. Grade scale: A ≥ 90% · B ≥ 75% · C ≥ 50% · D < 50%.

Module heatmap in `--report`

sigmap --report

[sigmap] report:
  version         : 5.6.0
  files processed : 76
  reduction       : 93.7%
  coverage        : A (97%)  — 76 of 78 source files included
  confidence      : HIGH

  Module Coverage:
    src                ████████████████ 100% (64/64 files)
    packages           ██████████████░░  86% (12/14 files)

Machine-readable JSON (suitable for CI dashboards):

sigmap --report --json
# { "version": "4.0.0", "finalTokens": 4103, "reductionPct": 93.7,
#   "coverage": { "score": 97, "grade": "A", "confidence": "HIGH", ... } }

Composite health score

sigmap --health

[sigmap] health:
  score    : 80/100 (grade B)
  coverage : A (97%)  — 76 of 78 source files
  strategy : full
  ...

sigmap --health --json
# { "score": 80, "grade": "B", "coverage": 97, "coverageGrade": "A",
#   "tokens": 4103, "reduction": 93.7, ... }

Confidence indicators in generated files

Every output file now carries a metadata line so you can inspect freshness at a glance:

<!-- sigmap: version=5.6.0 confidence=HIGH coverage=97% dropped=2 commit=8540612 -->

Diff risk score

sigmap --diff HEAD~3

[sigmap] Risk: Changed files (4):
  src/auth/service.ts         [HIGH]    — exports public API, 5 downstream dependents
  src/config/database.ts      [MEDIUM]  — config file
  src/utils/format.ts         [LOW]     — no dependents, internal utility

Self-healing CI

Copy examples/self-healing-github-action.yml to .github/workflows/ to auto-regenerate context when:

Context file is more than 7 days old (always active)
Copilot acceptance rate drops below 30% (requires COPILOT_API_TOKEN — GitHub Enterprise)

- name: SigMap health check
  run: sigmap --health --json
- name: Regenerate context
  run: sigmap

📖 Full guide: docs/readmes/ENTERPRISE_SETUP.md

Prompt caching — 60% API cost reduction

sigmap --format cache
# Writes: .github/copilot-instructions.cache.json
# Format: { type: 'text', text: '...', cache_control: { type: 'ephemeral' } }

📖 Full guide: docs/readmes/REPOMIX_CACHE.md

📦 Programmatic API

Use SigMap as a library — no CLI subprocess needed:

const { extract, rank, buildSigIndex, scan, score } = require('sigmap');

// Extract signatures from source code
const sigs = extract('function hello() {}', 'javascript');

// Build an index and rank files by query
const index = buildSigIndex('/path/to/project');
const results = rank('authentication middleware', index);

// Scan signatures for secrets before storing
const { safe, redacted } = scan(sigs, 'src/config.ts');

// Get a composite health score for a project
const health = score('/path/to/project');

📖 Full API reference: packages/core/README.md

🧪 Testing

# All 21 language extractors
node test/run.js

# Single language
node test/run.js typescript

# Regenerate expected outputs after extractor changes
node test/run.js --update

# Full integration suite
node test/integration/all.js

Validation gates

# Gate 1 — all tests pass
node test/run.js
# Expected: 21/21 PASS

# Gate 2 — zero external dependencies
grep "require(" gen-context.js | grep -v "^.*//.*require"
# Expected: only fs, path, assert, os, crypto, child_process, readline

# Gate 3 — MCP server responds correctly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node gen-context.js --mcp
# Expected: valid JSON with 8 tools

# Gate 4 — npm artifact is clean
npm pack --dry-run
# Expected: no test/, docs/, vscode-extension/ in output

📁 Project structure

sigmap/
│
├── gen-context.js               ← PRIMARY ENTRY POINT — single file, zero deps
├── gen-project-map.js           ← import graph, class hierarchy, route table
│
├── packages/
│   ├── core/                    ← programmatic API — require('sigmap') (v2.4)
│   │   └── index.js             ← extract, rank, buildSigIndex, scan, score
│   └── cli/                     ← thin CLI wrapper / v3 compat shim (v2.4)
│
├── src/
│   ├── extractors/              ← 21 language extractors (one file per language)
│   ├── retrieval/               ← query-aware ranker + tokenizer (v2.3)
│   ├── eval/                    ← benchmark runner + scorer (v2.1), analyzer (v2.2)
│   ├── mcp/                     ← MCP stdio server — 8 tools
│   ├── security/                ← secret scanner — 10 patterns
│   ├── routing/                 ← model routing hints
│   ├── tracking/                ← NDJSON usage logger
│   ├── health/                  ← composite health scorer
│   ├── format/                  ← Anthropic prompt-cache formatter
│   └── config/                  ← config loader + defaults
│
├── vscode-extension/            ← VS Code extension (v1.5)
│   ├── package.json             ← manifest — commands, settings, activation
│   └── src/extension.js         ← status bar, stale notification, commands
│
├── neovim-plugin/               ← Neovim plugin — sigmap.nvim (v5.4)
│   ├── lua/sigmap/init.lua      ← M.setup(), M.run(), M.query(), M.statusline()
│   ├── lua/sigmap/health.lua    ← :checkhealth sigmap
│   └── plugin/sigmap.lua        ← :SigMap and :SigMapQuery user commands
│
├── test/
│   ├── fixtures/                ← one source file per language
│   ├── expected/                ← expected extractor output
│   ├── run.js                   ← zero-dep test runner
│   └── integration/             ← 20 integration test files (304 tests)
│
├── docs/                        ← documentation site (GitHub Pages)
│   ├── index.html               ← homepage
│   ├── quick-start.html
│   ├── strategies.html
│   ├── languages.html
│   ├── roadmap.html
│   └── repomix.html
│
├── scripts/
│   ├── ci-update.sh             ← CI pipeline helper
│   └── release.sh               ← version bump + npm publish helper
│
├── examples/
│   ├── self-healing-github-action.yml
│   ├── github-action.yml            ← ready-to-use CI workflow
│   └── claude-code-settings.json    ← MCP server config example
│
├── .npmignore                   ← excludes docs/, test/, vscode-extension/ from publish
├── .contextignore.example       ← exclusion template
└── gen-context.config.json.example ← annotated config reference

🏗 Principles

Principle	Implementation
Zero npm dependencies	`npx sigmap` on any machine — no install required. Or use the standalone binary for zero Node.js dependency.
Never throw	All extractors return `[]` on any error — the run always completes
Deterministic	No AI or LLM involved in extraction — only regex + Node built-ins
Repomix is a companion	Use both tools; SigMap never replaces Repomix
No telemetry	Never phones home; all state is files in your repo
Local-first	No cloud service, no database, no accounts

🤝 Contributing

See CONTRIBUTING.md for how to add a language extractor or new feature.

Every extractor follows the same contract:

module.exports = { extract };
function extract(src) {   // src: string → string[]
  if (!src || typeof src !== 'string') return [];
  // ... regex extraction only — no external dependencies ...
  return sigs.slice(0, 25);  // never more than 25 signatures per file
}

⭐ Support

If SigMap saves you context or API spend, a ⭐ on GitHub helps others find it.

📄 License

If SigMap saves you time — a ⭐ on GitHub helps others find it.

Docs · Changelog · Roadmap · Repomix

Name		Name	Last commit message	Last commit date
Latest commit History 297 Commits
.claude/commands		.claude/commands
.context		.context
.github		.github
.vscode		.vscode
assets		assets
benchmarks		benchmarks
docs-vp		docs-vp
docs		docs
examples		examples
jetbrains-plugin		jetbrains-plugin
packages		packages
scripts		scripts
src		src
test		test
vscode-extension		vscode-extension
.contextignore		.contextignore
.contextignore.example		.contextignore.example
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PRERELEASE_GUIDE.md		PRERELEASE_GUIDE.md
README.md		README.md
RELEASE.md		RELEASE.md
TEST_RESULTS.md		TEST_RESULTS.md
demo.gif		demo.gif
gen-context.config.json		gen-context.config.json
gen-context.config.json.example		gen-context.config.json.example
gen-context.js		gen-context.js
gen-project-map.js		gen-project-map.js
intelij.gif		intelij.gif
package.json		package.json
vscode.gif		vscode.gif

Folders and files

Latest commit

History

Repository files navigation

⚡ SigMap

Table of contents

🔍 What it does

Token reduction at every stage

Benchmark: real-world repos

⚡ Installation

🚀 Features

Multi-adapter output

Programmatic API

Custom output path

Query-aware retrieval

Diagnostic and evaluation tools

⚡ Quick start

Install

Generate context

Companion tool: Repomix

🧩 VS Code extension

🔧 JetBrains plugin

🖥️ Neovim plugin

🌐 Languages supported

🗂 Context strategies

full — default, works everywhere

per-module — 70% fewer injected tokens, zero context loss

hot-cold — 90% fewer injected tokens, requires MCP

🔌 MCP server

Available tools

⚙️ CLI reference

Task classification — --suggest-tool

🔒 Security scanning

⚙️ Configuration

Output targets

📊 Observability

Coverage score

Module heatmap in --report

Composite health score

Confidence indicators in generated files

Diff risk score

Self-healing CI

Prompt caching — 60% API cost reduction

📦 Programmatic API

🧪 Testing

Validation gates

📁 Project structure

🏗 Principles

🤝 Contributing

⭐ Support

📄 License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 45

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`full` — default, works everywhere

`per-module` — 70% fewer injected tokens, zero context loss

`hot-cold` — 90% fewer injected tokens, requires MCP

Task classification — `--suggest-tool`

Module heatmap in `--report`

Packages