v2.6.0

# CLI Reference

Every flag, with examples. Run `sigmap --help` to see the full list.

Quick reference

## All flags at a glance

Every command SigMap accepts, one per line.

How you run it:
node gen-context.js --help
SigMap v3.5.0
Usage: node gen-context.js [flag]
(no flags) Generate context and exit
--watch Watch for file changes, regenerate automatically
--setup Generate + install git pre-commit hook + start watcher
--diff Context for git-changed files only
--diff --staged Context for staged files only (pre-commit)
--mcp Start MCP server on stdio
--query "<text>" Rank files by relevance to a query
--query "<text>" --json Ranked results as JSON
--query "<text>" --top N Limit to top N files (default 10)
--analyze Per-file breakdown: sigs / tokens / extractor / coverage
--analyze --json Analysis as JSON
--analyze --slow Include extraction timing per file
--diagnose-extractors Self-test all 21 extractors against fixtures
--benchmark Run retrieval quality benchmark (hit@5 / MRR)
--benchmark --json Benchmark results as JSON
--eval Alias for --benchmark
--adapter <name> Generate for one adapter: copilot|claude|cursor|windsurf|openai|gemini (v3.0+)
--adapter <name> --json Show adapter output path as JSON
--report Token reduction stats
--report --json Token report as JSON (CI-compatible, exits 1 if over budget)
--report --history Historical usage trends
--health Composite health score (grade A–D)
--health --json Health score as JSON
--suggest-tool Recommend model tier for a task
--monorepo Per-package context for monorepos
--each [<dirs>] Run generation separately per sub-directory (v3.2+)
--routing Include HTTP route extraction
--format cache Write Anthropic prompt-cache JSON
--track Log run metrics to .context/usage.ndjson
--init Scaffold config + .contextignore
--version Print version
--help Show help

Core commands

## Every flag explained

Detailed reference for each flag with runnable examples.

### sigmap (no flags)

The default run mode. Scans all configured source directories, extracts signatures from every supported file, applies the token budget, and writes the output file(s). Use this in CI, as a pre-push check, or any time you want a one-shot refresh. Exits with code 0 on success.

terminal
$ node gen-context.js
[sigmap] scanning 247 files across src/ app/ lib/
[sigmap] extracted 1,842 signatures from 89 files
[sigmap] secret scan: clean (0 findings)
[sigmap] budget: 6,000 tokens target, using 3,847
[sigmap] ✓ wrote .github/copilot-instructions.md
[sigmap] reduction: 82,400 → 3,847 tokens (95.3%)

### --watch

Starts the file watcher and keeps the process running. Every time a file inside a configured `srcDir` changes, SigMap regenerates the context after the `watchDebounce` delay (default 300 ms). Ideal during active development when you want your AI agent to always have the freshest context. Press Ctrl+C to stop.

terminal
$ node gen-context.js --watch
[sigmap] initial generation complete (3,847 tokens)
[sigmap] watching src/ app/ lib/ for changes... (Ctrl+C to stop)
[sigmap] change detected: src/api/users.ts
[sigmap] ✓ regenerated in 0.42s

### --setup

The recommended one-time setup command. It generates the context file, installs a git pre-commit hook so every commit triggers a regen, and starts the file watcher in the foreground. Running this once means you never have to think about keeping context up to date again.

terminal
$ node gen-context.js --setup
[sigmap] ✓ generated context (3,847 tokens)
[sigmap] ✓ installed .git/hooks/pre-commit
[sigmap] ✓ watcher started on src/ app/ lib/
[sigmap] watching for changes... (Ctrl+C to stop)

### --diff and --diff --staged

`--diff` limits the scan to files that have changed since the last git commit (unstaged + staged). `--diff --staged` further narrows to only staged files, making it ideal as a pre-commit hook check. Both variants run significantly faster on large codebases since they skip unchanged files entirely.

terminal
$ node gen-context.js --diff
[sigmap] diff mode: 4 changed files
[sigmap] ✓ wrote diff context (412 tokens)
$ node gen-context.js --diff --staged
[sigmap] staged mode: 2 staged files
[sigmap] ✓ wrote staged context (188 tokens)

### --report, --report --json, --report --history

Prints a human-readable token reduction breakdown to stdout. Add `--json` for machine-readable output suitable for CI pipelines — the command exits with code 1 if the output exceeds `maxTokens`. The `--history` flag shows trends across past runs stored in `.context/usage.ndjson`.

node gen-context.js --report
╔══════════════════════════════════╗
║ SigMap Token Report ║
╚══════════════════════════════════╝
Input 82,400 tokens (full source)
Output 3,847 tokens (signatures only)
Saved 78,553 tokens (95.3% reduction)
Files scanned 247
Files included 89 (dropped 158 under budget)
Secrets found 0 (clean)
node gen-context.js --report --json
{
"inputTokens": 82400,
"outputTokens": 3847,
"reductionPct": 95.3,
"overBudget": false,
"secretsFound": 0
}

### --health and --health --json

Computes a composite health score (0–100, graded A through D) by combining token efficiency, secret-scan results, dependency freshness, and test coverage signals. Use it as a quick sanity check before a big session or in your CI dashboard. The `--json` variant emits structured output for programmatic consumption.

node gen-context.js --health
Health Score: 87 / 100 [A]
✓ Token efficiency 95.3% reduction
✓ Secret scan clean
✓ Dependency map present
✗ Test coverage disabled

### --suggest-tool "<task>"

Analyses the codebase complexity and the provided task description, then recommends the appropriate model tier: fast (Haiku-class), balanced (Sonnet-class), or powerful (Opus-class). Useful when you want to keep costs down by routing simple tasks to cheaper models and only reaching for the powerful tier when it is truly needed.

terminal
$ node gen-context.js --suggest-tool "refactor auth middleware"
Recommended tier: balanced
Reason: mid-complexity cross-cutting change, 3 affected modules
Suggested models: Claude Sonnet, GPT-4o, Gemini 1.5 Pro

### --mcp

Starts the Model Context Protocol server on stdio, exposing SigMap's context generation capabilities as MCP tools that any compatible client (Claude Desktop, Cursor, Windsurf) can call. The server stays alive until the parent process closes the pipe. See the MCP setup page for full integration instructions.

terminal
$ node gen-context.js --mcp
[sigmap/mcp] server ready on stdio
[sigmap/mcp] tools: generate_context, get_report, get_health
📡
MCP setup guide
For Claude Desktop, Cursor, and Windsurf integration instructions, see the MCP setup page. The server exposes `generate_context`, `get_report`, and `get_health` as callable tools.

### --monorepo

Activates monorepo mode, which generates a separate context file per package instead of a single project-wide file. SigMap detects packages by looking for `package.json`, `pyproject.toml`, or `go.mod` files. Each package gets its own context file scoped to only its own source tree, keeping token budgets lean per workspace.

terminal
$ node gen-context.js --monorepo
[sigmap] monorepo: detected 4 packages
[sigmap] ✓ packages/api → .github/copilot-api.md (1,204 tokens)
[sigmap] ✓ packages/web → .github/copilot-web.md (2,108 tokens)
[sigmap] ✓ packages/shared → .github/copilot-shared.md (688 tokens)
[sigmap] ✓ packages/cli → .github/copilot-cli.md (392 tokens)

### --each [<dirs>]

Runs context generation independently for each sub-directory, producing a separate output file per directory. Unlike `--monorepo` (which detects packages via manifest files), `--each` treats each top-level directory as an independent workspace. Pass an optional comma-separated list of dirs to limit which ones to process. Useful for polyglot repos or workspaces where each directory is a completely separate project.

terminal
# all top-level sub-directories
$ node gen-context.js --each
[sigmap] ✓ frontend/ → frontend/.github/copilot-instructions.md (1,842 tokens)
[sigmap] ✓ backend/ → backend/.github/copilot-instructions.md (2,314 tokens)
[sigmap] ✓ shared/ → shared/.github/copilot-instructions.md (601 tokens)
# specific directories only
$ node gen-context.js --each frontend,backend

### --routing

Appends an HTTP route extraction section to the output file. SigMap scans for route definitions in Express, Fastify, Flask, FastAPI, Spring, Rails, and other common frameworks. The resulting section gives your AI agent a complete picture of your API surface without it having to read controller files.

terminal
$ node gen-context.js --routing
[sigmap] routing: extracted 42 routes across 6 files
[sigmap] ✓ wrote .github/copilot-instructions.md (4,211 tokens)

### --format cache

In addition to the standard markdown output, writes a companion `.json` file structured for the Anthropic prompt-cache API. Feed the JSON directly to the API's `system` parameter with `cache_control` set to save up to 90% on repeated context costs when calling the API directly.

terminal
$ node gen-context.js --format cache
[sigmap] ✓ wrote .github/copilot-instructions.md
[sigmap] ✓ wrote .github/copilot-instructions.cache.json

### --track

Appends a newline-delimited JSON record to `.context/usage.ndjson` on every run. Each record includes timestamp, token counts, file counts, and reduction percentage. Use this to track usage trends over time or pipe into your observability stack. The file is safe to commit alongside your project.

terminal
$ node gen-context.js --track
[sigmap] ✓ run metrics appended to .context/usage.ndjson
$ cat .context/usage.ndjson | tail -1
{"ts":"2026-04-04T09:12:33Z","output":3847,"input":82400,"pct":95.3,"files":89}

### --init

Scaffolds a `gen-context.config.json` with every available option pre-filled with its default value and a comment explaining each key. Also creates a starter `.contextignore` with common exclusion patterns. Neither file overwrites an existing one, so it is safe to run repeatedly.

terminal
$ node gen-context.js --init
[sigmap] ✓ wrote gen-context.config.json
[sigmap] ✓ wrote .contextignore

### --query "<text>"

Ranks every file in the project by relevance to a free-text query using a zero-dependency TF-IDF approach. Prints a scored table of the top-K files, then the full signature blocks for the top 3. Add `--json` for machine-readable output or `--top N` to limit results. The MCP `query_context` tool exposes the same ranking live in any agent session.

terminal
$ node gen-context.js --query "authentication middleware"
Ranking 89 files for: "authentication middleware"
Rank Score File
1 0.94 src/middleware/auth.ts
2 0.81 src/api/users.ts
3 0.74 src/config/jwt.ts
4 0.62 src/services/session.ts
5 0.45 test/integration/auth.test.ts
[sigmap] top 3 signature blocks ↓

### --version

Prints the current SigMap version string and exits. Useful in scripts to verify you have the expected version installed before running a pipeline.

terminal
$ node gen-context.js --version
sigmap/3.2.1

What's next

## Explore further

21 keys
Configuration
Every gen-context.config.json option documented with types, defaults, and examples.
v1.1
Context strategies
Full vs per-module vs hot-cold. Pick the right strategy for your team and codebase size.
MCP
MCP setup
Integrate SigMap as a Model Context Protocol server with Claude Desktop, Cursor, and Windsurf.