v3.5.0 released

# v0.0 → v3.5

Twenty-five versions shipped/planned. Reporting charts and advanced metrics are now the active milestone. MIT open source from day one.

97%Token reduction
340 Tests passing
21 Languages
0 npm deps

Token impact

## Reduction by version

Every version reduced the token footprint further. From 8K at baseline to under 4K — and the full pipeline at under 2K for active files.

Tokens per session — lower is better
v0.0
80,000
v0.1
4,000
v0.2
3,000
v0.3
200–2K
v0.6
−40% conv.
v0.8
−60% cost
v1.0
97% total
v1.1
~200 always-on
v1.3
50 diff-mode
v2.1
+benchmark
v2.2
+diagnostics
v2.3
+query retrieval
v2.4
+programmatic API
v2.5
+impact layer
v2.6
+research mode
v2.7
+ranking optimization
v2.8
+snippet retrieval
v2.9
+JetBrains plugin

Complete timeline

## Every version, every feature

Built in public. Tagged in git. MIT from the start.

v0.0
v0.0 Repomix baseline Baseline
Measure the problem. Install Repomix, create .repomixignore, measure token consumption before any optimisation. This is the number we spend every version beating.
repomix --compress .repomixignore token baseline
Starting point: ~80,000 tokens per session
v0.1
v0.1 Core extractor ✓ Complete
The first version that matters. A single file — gen-context.js — with all 21 language extractors inline. Zero npm dependencies. Runs on any machine with Node.js 18+. Writes .github/copilot-instructions.md. Installs a post-commit git hook via --setup.
gen-context.js 21 extractors --setup hook --watch zero deps
80,000 → 4,000 tokens — first 95% reduction
v0.2
v0.2 Enterprise hardening ✓ Complete
Secret scanning blocks AWS keys, GitHub tokens, database connection strings, and 10 other credential patterns from ever appearing in the output. The .contextignore file (gitignore syntax) lets teams exclude generated code, test fixtures, and vendor directories. Token budget enforcement with a defined drop order.
secret scan (10 patterns) .contextignore token budget drop order config file
4,000 → 3,000 tokens — smarter filtering
v0.3
v0.3 MCP server ✓ Complete
A JSON-RPC stdio server implementing the Model Context Protocol. Three tools: read_context (pull signatures for any module on demand), search_signatures (keyword search across all signatures), get_map (structural sections). The MCP server reads files on every call — no stale state, no restart needed.
stdio JSON-RPC read_context search_signatures get_map --mcp flag
200–2,000 tokens — pull only what the task needs
v0.4
v0.4 Project map ✓ Complete
gen-project-map.js produces PROJECT_MAP.md with three structural views: an import graph showing every file dependency, a class hierarchy showing extends/implements relationships, and a route table extracting HTTP routes from Express, FastAPI, Rails, and similar frameworks.
import graph class hierarchy route table cycle detection gen-project-map.js
Structural context — where things are, not just what they are
v0.5
v0.5 Monorepo + CI ✓ Complete
Monorepo mode generates a separate context file per package — agents working on one service don't receive signatures from all others. The GitHub Action runs on every push and PR, fails CI if token budget is exceeded, and posts a reduction report as a PR comment.
monorepo mode GitHub Action PR comments CI budget gate per-package output
Scales to any repo size — monorepo-safe
v0.6
v0.6 Session discipline ✓ Complete
A session compression guide (SESSION_DISCIPLINE.md) that codifies how agents should summarise conversations, checkpoint progress, and restart from a minimal state. The --track flag logs every run to .sigmap/runs.jsonl for monitoring. Reduces per-conversation token cost by 40%.
SESSION_DISCIPLINE.md conversation checkpoints --track flag runs.jsonl
−40% tokens per conversation
v0.7
v0.7 Model routing ✓ Complete
A file complexity scorer classifies every file as fast (simple CRUD, 0.33× cost), balanced (business logic, 1× cost), or powerful (architecture decisions, 3× cost). The routing table is appended to the context file. Agents use the fast-tier model for 70% of tasks — the ones that don't need powerful reasoning.
complexity scorer 3-tier routing haiku / sonnet / opus MODEL_ROUTING.md --routing flag
Up to 70% reduction in model API cost
v0.8
v0.8 Prompt cache ✓ Complete
The --format cache flag wraps context in Anthropic's cache_control breakpoints. The stable codebase signatures become a cached prefix — the most expensive tokens are computed once and reused across every request in a session. The 60% API cost reduction compounds with the model routing savings from v0.7.
cache_control breakpoints --format cache stable prefix Anthropic API
−60% API cost on repeated context loads
v0.9
v0.9 Observability ✓ Complete
The --report --json flag emits a machine-readable token reduction JSON suitable for CI dashboards and custom monitoring. An ENTERPRISE_SETUP.md consolidates all enterprise configuration. 23 new integration tests bring total coverage to 177 passing tests.
--report --json --track ENTERPRISE_SETUP.md 23 new tests CI dashboard
Full observability stack — see every token saved
v1.0
v1.0 Full system ✓ Complete — tagged v1.0.0
The complete SigMap system. Self-healing CI auto-regenerates the context file when it drifts. The --health flag gives a composite 0–100 score for context freshness, reduction quality, and over-budget run rate. The --suggest-tool flag classifies any task description into fast / balanced / powerful model tiers. All 177 tests pass.
self-healing CI --health --suggest-tool 177 tests MIT v1.0.0
97% total token reduction — 80,000 → under 4,000
v1.1
v1.1 Context strategies ✓ Complete — tagged v1.1.0
Three output strategies for different workflows. full (default) — one file, all signatures, always injected. per-module — one file per source directory plus a tiny always-on overview (~100–300 tokens); ~70% fewer injected tokens with zero context loss. hot-cold — recently committed files auto-injected (~200–800 tokens); everything else written to a cold file for MCP on-demand retrieval; ~90% fewer always-on tokens when using Claude Code or Cursor with MCP enabled.
strategy: full strategy: per-module strategy: hot-cold hotCommits config MIT v1.1.0
hot-cold + MCP: ~200 tokens always-on — 99.75% reduction from baseline
v1.2
v1.2 npm alias + test hardening ✓ Complete — tagged v1.2.0
Added `sigmap` npm binary alias alongside `gen-context` so `npx sigmap` works from any machine without cloning the repo. Improved `--init` to scaffold both `gen-context.config.json` and `.contextignore` in one step. Added 9 integration tests covering per-module and hot-cold strategy edge cases.
npx sigmap --init .contextignore strategy tests 9 new tests MIT v1.2.0
npm discoverability — works without cloning the repo
v1.3
v1.3 --diff flag + watch debounce ✓ Complete — tagged v1.3.0
The `--diff` flag generates context only for files changed in the current git working tree — ideal for PR reviews and CI. `--diff --staged` restricts to staged files only, making it a perfect pre-commit check. Both modes auto-fall-back to full generate when outside a git repository or when no files have changed. Watch mode debounce is now configurable via `watchDebounce` in config.
--diff --diff --staged watchDebounce config 6 new tests MIT v1.3.0
Active PR work: ~50–200 tokens instead of ~4,000 — 95%+ reduction for diffs
v1.4
v1.4 MCP tools + strategy health ✓ Complete — tagged v1.4.0
Two new MCP tools: explain_file returns signatures, resolved imports, and reverse callers for any file in a single call — agents get full file context without guessing paths. list_modules returns a token-count table of all top-level module directories so agents know where to look before calling `read_context`. Strategy-aware health scorer no longer penalises hot-cold or per-module runs for low reduction — intentionally small outputs score correctly. MCP server now exposes 7 tools total.
explain_file list_modules 7 MCP tools strategy health 25 new tests MIT v1.4.0
Precision context — agents ask for exactly the file context they need
v1.5
v1.5 VS Code extension + npm publish ✓ Complete — tagged v1.5.0
A zero-dependency VS Code extension shows a status bar item displaying the health grade and time since last regeneration (refreshes every 60 s). It warns when context is stale (>24 h), adds Regenerate Context and Open Context File commands, and supports a configurable script path. All six HTML documentation pages gained client-side keyword search (press `/` to open). A proper `.npmignore` prepares the package for npm publish — `npx sigmap` resolves to the runtime-only artifact.
VS Code extension status bar stale notification docs search .npmignore 58 new tests MIT v1.5.0
10× adoption surface — VS Code extension + npm discoverability
v2.0
v2.0 v2 pipeline — TODOs, changes, coverage, diff ✓ Complete — tagged v2.0.0
Major pipeline overhaul adds four new context sections: TODOs (inline TODO/FIXME/HACK extraction), Recent changes (git log summary), Coverage gaps (files lacking tests), and PR diff context (changed-file signatures). New dependency extractors for Python (`import`/`from`) and TypeScript (`import`/`require`). Three extractor bug fixes: Python BaseModel field bleed, TypeScript union type truncation, and TypeScript function-style hook detection. 262 tests passing across 21 languages and 17 integration suites.
v2 pipeline TODOs coverage gaps PR diff context dependency extractors 262 tests MIT v2.0.0
Full project awareness — agents see TODOs, recent changes, coverage gaps, and PR context
v2.1
v2.1 Benchmark & evaluation system ✓ Complete — tagged v2.1.0
Zero-dependency evaluation pipeline: hit@5, MRR, and precision@5 metrics against a JSONL task file. `--benchmark` CLI flag runs retrieval tasks and prints a scored results table. `--eval` alias. New `src/eval/runner.js` and `src/eval/scorer.js` modules. 12 new integration tests.
--benchmark hit@5 / MRR JSONL tasks src/eval/ 12 new tests MIT v2.1.0
Measurable retrieval quality — hit@5 ≥ 0.70 on SigMap repo
v2.2
v2.2 Diagnostics & per-file analysis ✓ Complete — tagged v2.2.0
`--analyze` prints a per-file breakdown of signatures, tokens, extractor language, and test coverage status. `--analyze --slow` re-times each extractor and flags files taking over 50ms. `--diagnose-extractors` self-tests all 21 extractors against their fixture files and reports any mismatch. Helps teams identify extraction blind spots and performance bottlenecks.
--analyze --diagnose-extractors per-file breakdown extractor self-test MIT v2.2.0
Operator visibility — know exactly what every file contributes to context
v2.3
v2.3 Query-aware retrieval ✓ Complete — tagged v2.3.0
Zero-dependency TF-IDF retrieval ranks all files by relevance to a free-text query. `--query "<text>"` prints a scored file table plus the top-3 signature blocks. `--query --json` returns machine-readable `{ query, results[], totalResults }`. New 8th MCP tool query_context exposes the same ranking live in any MCP session. Config keys `retrieval.topK` (default 10) and `retrieval.recencyBoost` (default 1.5×). New modules: `src/retrieval/tokenizer.js` and `src/retrieval/ranker.js`. 325 tests passing across 21 languages and 20 integration suites.
--query query_context MCP TF-IDF src/retrieval/ 8 MCP tools 325 tests MIT v2.3.0
Agents find relevant files instantly — no guessing, no path memorisation
v2.4
v2.4 packages/core — programmatic API ✓ Complete — tagged v2.4.0
Splits `gen-context.js` into a proper package structure. `packages/core/index.js` (`sigmap-core`) exposes a stable programmatic API: extract, rank, buildSigIndex, scan, score. Third-party tools can now `require('sigmap')` without spawning a CLI process. `packages/cli/index.js` (`sigmap-cli`) is a thin forward-compat shim for the v3.0 adapter architecture. Root `gen-context.js` entry and all CLI flags unchanged — full backward compat. New `exports` field in root `package.json`. 15 new integration tests.
packages/core packages/cli require('sigmap') programmatic API backward compat 340 tests MIT v2.4.0
Third-party tools can now use SigMap as a library — no CLI subprocess required
v2.5
v2.5 Impact layer — dependency graph + --impact ✓ Complete
Adds a reverse-dependency graph to SigMap. `--impact <file>` traces every file that transitively imports the given file — giving agents instant blast-radius awareness when a change is made. `src/map/dep-graph.js` builds the reverse index; `src/map/impact.js` runs BFS/DFS traversal with optional depth limit. New `get_impact` MCP tool (9th tool) returns impacted files with signatures. Circular deps handled safely — no infinite loops. `--impact --json` for CI integration.
dep-graph --impact get_impact MCP blast radius BFS traversal 9th MCP tool issue #14
Agents instantly know what breaks when you change a file — without running tests
v2.6
v2.6 Research Mode — Real Benchmarks + Paper Export ✓ Complete
Generate publishable evaluation results. Run against real open-source repos (express, flask, gin, spring-petclinic, rails) and output paper-ready metrics. `--benchmark --repo <path>` runs benchmarks on external repos. `--report --paper` generates markdown + LaTeX tables ready for academic papers: token reduction table, hit@5/MRR per repo, latency (p50/p95/p99), all copy-paste ready. 50 real evaluation tasks across 5 repos. Zero-dependency paper formatting in `src/eval/paper.js`.
benchmarks --benchmark --repo --report --paper LaTeX export 50 eval tasks 5 real repos issue #16
Publishable research-grade metrics — hit@5 ≥ 0.75 target across all real-world repos
v2.7
v2.7 Ranking Optimization — Precision Tuning ✓ Complete
Fine-tuned ranking algorithm weights for better precision. Benchmark-driven optimization of `exactToken`, `symbolMatch`, `prefixMatch`, `pathMatch`, and `recencyBoost` weights. TF-IDF scoring option for semantic relevance. Configurable weight presets (`precision`, `balanced`, `recall`) via `retrieval.preset`. Performance optimization for large codebases — `--query` completes in <100ms on 1000-file repos. Precision@5 improved by ≥5% while maintaining hit@5 ≥ 0.80.
ranking weights TF-IDF weight presets performance precision@5 issue #19
Better query results — 5% precision boost for targeted retrieval tasks
v2.8
v2.8 Hybrid Depth — Snippet Retrieval ✓ Complete
Returns not just relevant files, but the exact code snippets within those files that match the query. Hybrid approach combining file-level and snippet-level retrieval. `--query --snippets` CLI flag returns top-k snippets with line numbers and smart context (2-3 lines before/after). MCP `query_context` tool enhanced with `snippets: true` option — response includes snippet text + line ranges. `src/retrieval/snippets.js` extracts relevant code blocks; hybrid scoring combines file score + snippet-local score. Performance <150ms for 1000-file repos.
snippet extraction hybrid scoring --query --snippets MCP enhancement smart context issue #21
Precision boost — 10%+ improvement in precision@3 over full-file retrieval
v2.9
v2.9 IDE Expansion — JetBrains Plugin ✓ Complete
Expands SigMap beyond VS Code to JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, GoLand, RubyMine). Native plugin with toolbar actions ("Regenerate Context", "Open Context File", "View Roadmap"), settings panel (configure srcDirs, exclude patterns, maxTokens, routing presets), and file watcher integration (auto-regenerate on changes, opt-in). `jetbrains-plugin/` with Gradle build + plugin.xml manifest. Automated JetBrains Marketplace publishing via GitHub Actions. `docs/JETBRAINS_SETUP.md` installation guide. Plugin passes JetBrains Plugin Verifier.
JetBrains plugin IntelliJ IDEA toolbar actions settings panel file watcher issue #23
Multi-IDE support — SigMap now available in both VS Code and JetBrains ecosystems
v2.10
v2.10 Reporting — Charts + Advanced Metrics ✓ Complete — tagged v2.10.0
Adds chart-ready reporting for token reduction and signature coverage, plus advanced benchmark metrics such as precision@K, recall@K, and MRR trends. Includes richer CLI report output and CI-friendly JSON artifacts for release quality gates.
report charts advanced metrics precision@K recall@K MRR trend issue #25
Release confidence — measurable quality gates for retrieval and token efficiency
v3.0
v3.0 Platform — Multi-Adapter Architecture ✓ Complete — tagged v3.0.0 (2026-04-06)
SigMap becomes an adapter platform. Six output adapters ship: `copilot`, `claude`, `cursor`, `windsurf`, `openai`, and `gemini`. New `--adapter <name>` CLI flag generates output for a specific adapter. `packages/core` gains `adapt(context, adapterName)` for programmatic use. Old `outputs` config key silently maps to `adapters` — full backward compatibility. API stability guarantee: breaking changes require v4.0.
6 adapters openai gemini adapt() API backward compat semver-stable core
Platform milestone — SigMap works with any AI assistant, not just Copilot
v3.1
v3.1 Global Command & VS Code Prerelease Fix ✓ Complete — tagged v3.1.0 (2026-04-07)
Detects whether SigMap is installed globally (`npm install -g sigmap`) and automatically switches the invocation from `node gen-context.js` to the global `sigmap` command. VS Code extension prerelease channel bug fixed — extensions no longer fail to activate when installed from the prerelease channel. Improved first-run experience: clearer console messages, better error recovery on missing config.
global command detection VS Code prerelease fix first-run UX v3.1.0
Seamless upgrade path from local file to global npm install
v3.2
v3.2 Standalone Binaries + Monorepo & Quality Fixes ✓ v3.2.1
Standalone binaries built with Node.js SEA (Single Executable Application) for macOS arm64/x64, Linux x64, and Windows x64 — no Node.js runtime required. Four pipeline quality fixes: `applyTokenBudget` loop direction, CSS utility heuristic, `coverage.js` Python test patterns, and `isTested` token splitting. New `--each [dirs]` flag runs context generation independently per sub-directory. Bug fix: `--monorepo` no longer hardcodes the `claude` output adapter.
standalone binaries Node.js SEA --each flag monorepo fix token budget fix 360 tests v3.2.1
Zero-dependency distribution — deploy sigmap anywhere without installing Node.js
v3.3
v3.3 Context-Aware CLI & Command Switcher ✓ Complete — v3.3.1
The `--help` output now adapts to how you invoke SigMap — running `npx sigmap --help`, `sigmap --help`, `gen-context --help`, or `node gen-context.js --help` each shows the matching command in every usage example. The CLI reference docs page gains a four-tab command picker ("How you run it:") that rewrites all terminal blocks on the page to the selected invocation style, persisted in `localStorage`. Includes SEO improvements across all docs pages and new Gemini adapter context generation.
context-aware --help command switcher UI npx / global / local detection Gemini adapter SEO v3.3.1
Every user sees the exact command that works for their install method — no more copy-paste errors
v3.5
v3.5 Phase C/D Intelligence Expansion ✓ Current — v3.5.0
Phase C ships framework-specialized extraction for React TSX, Vue SFC, and Python dataclass/model code paths. Phase D adds architectural pattern inference for dependency injection, service and repository layers, controller boundaries, type linkage, and high-risk unsafe code signals.
typescript_react vue_sfc python_dataclass patterns extractor cross-module inference v3.5.0
Better file routing and higher-signal context let agents answer architecture-level questions with fewer prompts.

Final numbers

## v3.5.0 — Current milestone

97%
Token reduction
360
Tests passing
21
Languages
0
npm deps
Get started in 90 seconds ★ Star on GitHub