Closes the visibility gap behind issues #138 (WASM-on-macOS) and #139
(MCP "database is locked"). `better-sqlite3` is in optionalDependencies,
so when the native build fails npm install still succeeds and the
runtime silently falls back to node-sqlite3-wasm — 5-10x slower and
without WAL, so writers block readers (which is what makes the MCP
server appear to "lock the DB" in #139). The only existing signal was
a one-line `console.warn` to stderr that MCP transports typically
swallow.
This patch does NOT change install behavior — better-sqlite3 stays in
optionalDependencies so cross-platform installs keep working. It just
makes the substitution observable + recoverable.
## Visibility (4 surfaces)
- CLI `codegraph status`: new `Backend:` line under Index Statistics.
`native` rendered green; `wasm` rendered yellow with an inline
`npm rebuild better-sqlite3` nudge. Also exposed in `--json` as
`backend: 'native' | 'wasm'`.
- MCP `codegraph_status`: new `**Backend:**` line. Native form reads
`native (better-sqlite3)`; wasm form prepends a warning glyph and
includes the full fix recipe.
- Stderr banner on fallback (`buildWasmFallbackBanner`): replaces the
bare one-line `console.warn` with a multi-line bordered banner
covering macOS + Linux fix steps and optionally appending the
native load error.
- README troubleshooting: new "Indexing is slow / MCP database is
locked / WASM fallback active" entry that walks users to the
`Backend:` line and the fix.
## Per-instance backend tracking
`createDatabase` previously set a module-level `activeBackend` global.
MCP can open multiple project DBs in one process via the
`getCodeGraph()` cache, so the global would race / overwrite. Refactor:
`createDatabase` now returns `{db, backend}`, `DatabaseConnection`
carries `private backend` and exposes `getBackend()`, and
`CodeGraph.getBackend()` is the public surface. The CLI and MCP both
call `cg.getBackend()`.
## What this does NOT fix
The root cause of users landing on WASM is environment-specific (Mac
without Xcode CLT, Node version mismatch, etc.) and not fixable in
code without changing the optionalDependencies design. The README
entry tells users what to run; `Backend: native` after rebuild is the
confirmation signal.
## Tests
New `__tests__/sqlite-backend.test.ts` (6 tests) pins the banner
recipe content (so future edits can't strip the recovery commands),
the `WASM_FALLBACK_FIX_RECIPE` constant, and per-instance
`DatabaseConnection.getBackend()` / `CodeGraph.getBackend()` reporting.
Suite: 503 → 509, all passing.
Credit to @andreinknv whose analysis on #138 (and patches on his fork
at 6d0e7a2 + 69f7001) framed the visibility approach.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Reorder Get Started so the per-project init code block sits between
the npx install and the GIF — visually contiguous code blocks read
better than code → image → code.
- Add Scala (`.scala`, `.sc`) to the Supported Languages table now
that #91 has landed.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The top-level Get Started section showed the install command but not
the per-project init step. Adding the same `cd your-project /
codegraph init -i` block that lives in Quick Start so users see the
full happy path before scrolling.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Followup to #66 — Vue support shipped but the README languages table
was never updated.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: add framework extract wiring plan
* feat(resolution): replace extractNodes with extract() returning nodes and references
* feat(resolution): add getApplicableFrameworks helper for per-language dispatch
* feat(django): emit route nodes and route->view references in extract()
* feat(flask,fastapi): emit route nodes and route->handler references
* feat(express): emit route nodes and route->handler references
* feat(laravel): emit route nodes and route->handler references
* feat(rails): emit route nodes and route->handler references
* feat(spring): emit route nodes and route->handler references
* feat(go): emit route nodes and route->handler references
* feat(rust): emit route nodes and route->handler references
* feat(aspnet): emit route nodes and route->handler references
* feat(swift,vapor): emit route nodes and route->handler references
* chore(react,svelte): migrate resolvers to extract() interface
* feat(extraction): run framework extractors after tree-sitter parse
* docs: document framework route extraction
* feat(strip-comments): add per-language comment stripper for framework extractors
Replaces comment characters and string-literal contents with spaces (not
removal) so source offsets stay valid for downstream regex match index ->
line number conversion. Handles Python triple-quoted docstrings, Ruby
=begin/=end, Rust nested block comments, and the standard //, #, /* */
forms across the supported languages.
This is consumed by framework extract() methods in a follow-up commit so
that commented-out / docstring routing examples don't surface as phantom
route nodes in the graph.
* feat(frameworks): strip comments before regex extraction (prevents phantom routes)
Pipes the per-language stripCommentsForRegex helper into every framework
extract() that scans raw source: django/flask/fastapi (python.ts),
express, laravel, rails, spring, go, rust, aspnet, vapor, plus
swiftui/uikit struct extraction in swift.ts.
Without this, examples like:
# path('/admin/', AdminPanel.as_view())
""" path('/users/', UserListView.as_view()) """
urlpatterns = [path('/real/', RealView.as_view())]
produced 3 phantom route nodes. Now only the real one is extracted.
Each framework gets a regression test in __tests__/frameworks.test.ts
asserting that line-, block-, docstring- and (where relevant)
heredoc-style commented-out routes do not surface as nodes.
---------
Co-authored-by: Colby McHenry <me@colbymchenry.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Updates Swift and Kotlin language support from basic to full in documentation and reduces explore budget thresholds to optimize performance for smaller codebases.
Removes crystal ball emoji and bullet formatting inconsistencies from README headers. Eliminates mark-dirty and sync-if-dirty CLI commands and related hook configuration code, simplifying the codebase after transitioning to file watcher-based auto-sync.
Addresses the need for automatic graph synchronization on file changes. Implements FileWatcher using native OS file events (FSEvents/inotify/ReadDirectoryChangesW) with 2-second debouncing to prevent thrashing on rapid saves. Filters changes against include/exclude patterns and ignores .codegraph directory modifications. Integrates with CodeGraph API (watch/unwatch/isWatching methods) and MCP server for automatic activation. Updates documentation to reflect shift from semantic to full-text search and removal of manual hook installation requirements.
Restructures the benchmark table for better readability by separating queries into a details section and highlighting the overall 92% fewer tool calls and 71% faster performance. Makes the compelling efficiency gains more prominent while maintaining all detailed information in an expandable section.
Updates benchmark results with the largest tested codebase (25,874 files, 272,898 nodes) demonstrating CodeGraph's scalability. Increases the recommended call limit from 3 to 6 to accommodate more complex cross-cutting queries while maintaining efficiency gains over traditional file-reading approaches.
Two fixes discovered while benchmarking Swift (Alamofire):
1. codegraph_explore traversalDepth 2→3: Deep call chains (e.g., Alamofire's
9-step Session.request()→URLSession flow) couldn't be followed in a single
explore call, forcing agents to fall back to file reads.
2. findSymbol/findAllSymbols now support "Parent.child" notation (e.g.,
"Session.request") by matching against qualified names (::Parent::child).
Previously only checked node.name === symbol, which never matched qualified
queries since node names are unqualified.
Also adds Alamofire Swift benchmark data to README (91% fewer tool calls,
78% faster with CodeGraph).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replaces limited 3-test benchmark with results from 4 real-world codebases (VS Code, Excalidraw, Claude Code) showing 94% fewer tool calls and 77% faster exploration. Updates performance claims and adds detailed breakdown of tool usage patterns with and without CodeGraph.
Testing showed semantic search produces significantly better results for
natural language queries that Claude writes. FTS alone often ranks
properties above their parent classes and misses conceptual matches.
Embeddings are now always on — the vector manager is created eagerly,
with model download and embedding generation still happening lazily.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Eliminates anonymous error reporting functionality that was collecting stack traces and error context via Sentry. Removes all telemetry-related code, configuration options, and documentation references.
Sentry error reporting can now be disabled by:
1. Declining during the interactive installer (sets CODEGRAPH_TELEMETRY=off
in the MCP server config env)
2. Setting CODEGRAPH_TELEMETRY=off in your shell environment
README updated with a Telemetry section documenting what is collected
and how to opt out.
Closes#68
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The installer previously ran `npm install -g` silently without user
consent. Now it asks for confirmation first, explains why the global
install is needed (hooks & MCP server), and gracefully skips if declined.
README updated to document this step.
Closes#69
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Traverses dependency graph to identify which test files depend on changed source files. Supports stdin input for git integration, custom test file patterns, and configurable traversal depth. Useful for targeted test execution in CI/CD pipelines.
Integrate main branch changes (WASM grammar architecture, centralized
resolution caches, SQLite adapter) with delphi-support branch. Pascal
grammar is now built as WASM and shipped in src/extraction/wasm/ for
consistency with the WASM-based grammar loading approach.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update language count (17+ → 18+), add Pascal/Delphi row to the
supported languages table, and include Pascal in CLAUDE.md language list.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add 'svelte' to Language type, DEFAULT_CONFIG includes, grammars, and config validation
- Add SvelteExtractor that extracts <script> blocks and delegates to TS/JS TreeSitterExtractor
- Add Svelte framework resolver for runes ($state, $derived, $effect, etc.), store auto-subscriptions, SvelteKit module aliases ($app/*, $env/*, $lib/*), and SvelteKit route detection
- Update README to list Svelte and Dart in supported languages
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add note that installer updates ~/.claude/CLAUDE.md in Quick Start
- Rename "Recommended: Add Global Instructions" to "Global Instructions Reference"
- Clarify that instructions are added automatically, shown for reference
- Bump version to 0.2.7
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The hybrid approach (Claude's native Explore agents using codegraph tools)
is more effective than a custom explore tool because Explore agents already
know what format the main session needs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The installer runs `npm install -g @colbymchenry/codegraph` so users
can simply run `codegraph init -i` instead of the full npx command.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Users running via npx don't have the codegraph command installed
globally. Update installer message and README to use
npx @colbymchenry/codegraph init -i instead.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace placeholder metrics with actual benchmark results (29% fewer tokens, 25% fewer tool calls)
- Add full benchmark data table in collapsible section
- Add ASCII architecture diagram showing how CodeGraph integrates with Explore agents
- Explain the hybrid approach: agents query the graph instead of scanning files
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add centered npx command in hero section (Next.js style)
- Simplify Quick Start to 3 steps using interactive installer
- Move manual setup and global instructions to collapsible details
- Add install command to CLI usage and commands sections
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated documentation to recommend instructing Explore agents to use
CodeGraph tools (search, callers, callees, context) for faster code
exploration instead of file scanning.
Benchmark results show ~30% fewer tokens and ~25% fewer tool calls
when Explore agents leverage CodeGraph for graph-based lookups.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add codegraph_explore MCP tool for deep exploration with condensed output
- Expand default exclude patterns for framework build outputs (.next, .nuxt, .expo, etc.)
- Increase node ID hash length from 16 to 32 chars to prevent collisions
- Add feature request detection with UX clarification reminders
- Update README with MCP tools reference and best practices
- Update CLAUDE.md with context usage guidelines
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add centered hero with key metrics (2x faster, 40% fewer tokens, zero API costs)
- Add side-by-side comparison table showing before/after CodeGraph
- Add real-world benchmark results from Sign in with Apple test
- Add 6-feature grid highlighting key capabilities
- Update all section headers with emojis
- Add badges for npm, license, and Node.js version
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Olaf MonienandClaude Opus 4.6