Table of contents

📖 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
    │
    ▼
gen-context.js ──► extracts signatures from 21 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

97% fewer tokens. The same codebase understanding.

⚡ Installation

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

npx sigmap

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

npm install -g sigmap
sigmap

Available from any directory on your machine.

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)

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

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/binaries.md

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 install sigmap
sigmap

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

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.

Note: When using the single-file download, replace sigmap with node gen-context.js in all commands below.

🚀 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

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.

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

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:

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

See docs/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

Download the single-file CLI and generate context immediately:

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:

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 vscode-extension/ directory contains a first-party VS Code extension that keeps you informed without any manual commands.

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

Install: VS Code Marketplace | Open VSX Registry

🔧 JetBrains plugin

The jetbrains-plugin/ directory contains a Kotlin-based plugin for JetBrains IDEs with the same core features as the VS Code extension.

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

🌐 Languages supported

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

🗂 Context strategies

Reduce always-injected tokens by 70–90%.

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

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/CONTEXT_STRATEGIES.md — decision tree, scenario comparisons, migration steps.

🔌 MCP server

Start the MCP server on stdio:

node gen-context.js --mcp

Available tools

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

📖 Setup guide: docs/MCP_SETUP.md

⚙️ CLI reference

See CHANGELOG.md for the full history.

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

node gen-context.js --query "<text>"          Rank files by relevance to a query
node gen-context.js --query "<text>" --json   Ranked results as JSON
node gen-context.js --query "<text>" --top <n> Limit results to top N files (default 10)

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

node gen-context.js --benchmark               Run retrieval quality benchmark (hit@5 / MRR)
node gen-context.js --benchmark --json        Benchmark results as JSON
node gen-context.js --eval                    Alias for --benchmark

node gen-context.js --report                  Token reduction stats
node gen-context.js --report --json           Structured JSON report (exits 1 if over budget)
node gen-context.js --report --history        Usage log summary
node gen-context.js --report --history --json Usage history as JSON

node gen-context.js --health                  Composite health score (0–100, grade A–D)
node gen-context.js --health --json           Machine-readable health JSON

node gen-context.js --suggest-tool "<task>"   Recommend model tier for a task
node gen-context.js --suggest-tool "<task>" --json  Machine-readable tier recommendation

node gen-context.js --monorepo                Per-package context for monorepos
node gen-context.js --routing                 Include model routing hints in output
node gen-context.js --format cache            Write Anthropic prompt-cache JSON
node gen-context.js --track                   Append run metrics to .context/usage.ndjson

node gen-context.js --init                    Write config + .contextignore scaffold
node gen-context.js --version                 Version string
node gen-context.js --help                    Usage information

Task classification — --suggest-tool

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

node gen-context.js --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:

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"],
  "maxTokens": 6000,
  "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)
• maxTokens — max tokens in final output before budget enforcement
• secretScan — redact secrets (AWS keys, tokens, etc.) from output
• strategy — output mode: full (default) | per-module | hot-cold

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

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

Run node gen-context.js --init to scaffold both files in one step.

Output targets

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

# Append run metrics to .context/usage.ndjson
node gen-context.js --track

# Structured JSON report for CI (exits 1 if over budget)
node gen-context.js --report --json
# { "version": "2.0.0", "finalTokens": 3200, "reductionPct": 92.4, "overBudget": false }

# Composite health score
node gen-context.js --health
# score: 95/100 (grade A) | reduction: 91.2% | 1 day since regen | 47 runs

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: node gen-context.js --health --json
- name: Regenerate context
  run: node gen-context.js

📖 Full guide: docs/ENTERPRISE_SETUP.md

Prompt caching — 60% API cost reduction

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

📖 Full guide: docs/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
│
├── 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

🤝 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

MIT © 2026 Manoj Mallick · Made in Amsterdam 🇳🇱