@sdsrs/code-graph 0.5.14 → 0.5.16

package/README.md

@@ -43,6 +43,46 @@ Single binary, embedded SQLite, bundled sqlite-vec extension, optional local emb
 
 Every design decision — from token-aware compression to node_id-based snippet expansion — is optimized for LLM context windows. Works out of the box with Claude Code, Cursor, Windsurf, and any MCP-compatible client.
 
+## Efficiency: code-graph vs Traditional Tools
+
+Real-world benchmarks comparing code-graph-mcp tools against traditional approaches (Grep + Read + Glob) on a 33-file Rust project (~537 AST nodes).
+
+### Tool Call Reduction
+
+| Scenario | Traditional | code-graph | Savings |
+|----------|:-----------:|:----------:|:-------:|
+| Project architecture overview | 5-8 calls | 1 call (`project_map`) | **~85%** |
+| Find function by concept | 3-5 calls | 1 call (`semantic_code_search`) | **~75%** |
+| Trace 2-level call chain | 8-15 calls | 1 call (`get_call_graph`) | **~90%** |
+| Pre-change impact analysis | 10-20+ calls | 1 call (`impact_analysis`) | **~95%** |
+| Module structure & exports | 5+ calls | 1 call (`module_overview`) | **~80%** |
+| File dependency mapping | 3-5 calls | 1 call (`dependency_graph`) | **~75%** |
+| Similar code detection | N/A | 1 call (`find_similar_code`) | **unique** |
+
+### Overall Session Efficiency
+
+| Metric | Without code-graph | With code-graph | Improvement |
+|--------|:------------------:|:---------------:|:-----------:|
+| Tool calls per navigation task | ~6 | ~1.2 | **~80% fewer** |
+| Source lines read into context | ~8,000 lines | ~400 lines (structured) | **~95% less** |
+| Navigation token cost | ~36K tokens | ~7K tokens | **~80% saved** |
+| Full session token savings | — | — | **40-60%** |
+
+### What code-graph Uniquely Enables
+
+- **Impact analysis** — "Changing `conn` affects 33 functions across 4 files, 78 tests at HIGH risk" — impossible to derive manually with Grep
+- **Transitive call tracing** — Follow `main` → `run_serve` → `handle_message` → `handle_tools_call` → `conn` in one query
+- **Semantic search** — Find `authenticate_session` when searching "handle user login"
+- **Dependency strength** — Not just "file A imports file B", but "file A uses 38 symbols from file B"
+
+### When Traditional Tools Are Still Better
+
+| Use Case | Best Tool |
+|----------|-----------|
+| Exact string / constant search | Grep |
+| Reading a file to edit it | Read |
+| Finding files by name pattern | Glob |
+
 ## Architecture
 
 ```

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,6 +4,6 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.5.14",
+  "version": "0.5.15",
   "keywords": ["code-graph", "ast", "navigation", "mcp", "knowledge-graph"]
 }

package/claude-plugin/agents/code-explorer.md

@@ -1,7 +1,7 @@
 ---
 name: code-explorer
 description: Deep code understanding expert using AST knowledge graph. Use when exploring unfamiliar code, tracing complex relationships, or understanding module architecture.
-tools: ["Read", "Grep", "Glob", "Bash", "mcp__code-graph__semantic_code_search", "mcp__code-graph__get_call_graph", "mcp__code-graph__get_ast_node", "mcp__code-graph__read_snippet", "mcp__code-graph__trace_http_chain"]
+tools: ["Read", "Grep", "Glob", "Bash", "mcp__code-graph__semantic_code_search", "mcp__code-graph__get_call_graph", "mcp__code-graph__get_ast_node", "mcp__code-graph__trace_http_chain"]
 model: sonnet
 ---
 
@@ -11,10 +11,9 @@ You are a code exploration specialist with access to an AST knowledge graph.
 
 1. **Start with semantic_code_search** to locate relevant code by meaning
 2. **Use get_call_graph** to understand function relationships and call chains
-3. **Use get_ast_node** to get symbol metadata (signature, type, doc comment)
-4. **Use read_snippet** to examine specific code implementations
-5. **Use trace_http_chain** for HTTP request flow analysis
-6. **Fall back to Grep/Read** only when code-graph tools lack coverage (e.g., config files, non-code assets)
+3. **Use get_ast_node** to get symbol metadata, code, and callers/callees (use `context_lines` for surrounding source)
+4. **Use trace_http_chain** for HTTP request flow analysis
+5. **Fall back to Grep/Read** only when code-graph tools lack coverage (e.g., config files, non-code assets)
 
 ## Rules
 

package/claude-plugin/commands/trace.md

@@ -10,6 +10,6 @@ Trace the complete execution path of an HTTP request.
 ## Steps
 
 1. Call `trace_http_chain(route, depth=5)` to get the full chain
-2. For each key node in the chain, call `read_snippet` to show the implementation
+2. For each key node in the chain, call `get_ast_node` (by node_id, with `context_lines`) to show the implementation
 3. Map the flow: route → middleware → validation → business logic → data access → response
 4. Highlight any error handling, authentication checks, or database operations

package/claude-plugin/commands/understand.md

@@ -9,9 +9,9 @@ Understand what a module does, its public API, and how it connects to the rest o
 
 ## Steps
 
-1. Call `get_index_status` to verify the code graph index is current
-2. Call `semantic_code_search` with the module name to find its key symbols
-3. For each important export, call `get_call_graph` to map caller/callee relationships
+1. Call `module_overview(path)` to get exports, hot paths, and file structure in one call
+2. Call `dependency_graph(file_path)` for the main file to map imports and dependents
+3. For key functions that need deeper understanding, call `get_call_graph` to trace call chains
 4. Summarize:
    - **Purpose**: what this module does
    - **Public API**: exported functions/classes with signatures

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.5.14",
-    "@sdsrs/code-graph-linux-arm64": "0.5.14",
-    "@sdsrs/code-graph-darwin-x64": "0.5.14",
-    "@sdsrs/code-graph-darwin-arm64": "0.5.14",
-    "@sdsrs/code-graph-win32-x64": "0.5.14"
+    "@sdsrs/code-graph-linux-x64": "0.5.16",
+    "@sdsrs/code-graph-linux-arm64": "0.5.16",
+    "@sdsrs/code-graph-darwin-x64": "0.5.16",
+    "@sdsrs/code-graph-darwin-arm64": "0.5.16",
+    "@sdsrs/code-graph-win32-x64": "0.5.16"
   }
 }