Table of contents

| | | |---|---| | 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 | | Languages supported | 21 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
    │
    ▼
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

| 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% |

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

| Adapter | Output file | AI assistant | |---|---|---| | copilot | .github/copilot-instructions.md | 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 | Google Gemini |

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:

| 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/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:

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

| 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 node gen-context.js in the integrated terminal | | Open context command | SigMap: Open Context File — opens .github/copilot-instructions.md | | Script path setting | sigmap.scriptPath — override when gen-context.js is not at the project root |

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.

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

🌐 Languages supported

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

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

🔌 MCP server

Start the MCP server on stdio:

node gen-context.js --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/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 (packages/, apps/, services/)
node gen-context.js --each                    Process each sub-repo under a parent directory
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:

| 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"],
  "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

| 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

# 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

| Principle | Implementation | |---|---| | Zero npm dependencies | node gen-context.js on a blank machine with Node 18+ — nothing else required | | 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

MIT © 2026 Manoj Mallick · Made in Amsterdam 🇳🇱

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

Docs · Changelog · Roadmap · Repomix