@stupidloud/codegraph 0.7.20 → 0.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/README.md +127 -106
  2. package/dist/bin/codegraph.d.ts +4 -0
  3. package/dist/bin/codegraph.d.ts.map +1 -1
  4. package/dist/bin/codegraph.js +327 -8
  5. package/dist/bin/codegraph.js.map +1 -1
  6. package/dist/bin/node-version-check.d.ts +17 -0
  7. package/dist/bin/node-version-check.d.ts.map +1 -1
  8. package/dist/bin/node-version-check.js +37 -0
  9. package/dist/bin/node-version-check.js.map +1 -1
  10. package/dist/config.d.ts.map +1 -1
  11. package/dist/config.js +1 -11
  12. package/dist/config.js.map +1 -1
  13. package/dist/db/index.d.ts +30 -1
  14. package/dist/db/index.d.ts.map +1 -1
  15. package/dist/db/index.js +75 -25
  16. package/dist/db/index.js.map +1 -1
  17. package/dist/db/queries.d.ts +16 -0
  18. package/dist/db/queries.d.ts.map +1 -1
  19. package/dist/db/queries.js +80 -27
  20. package/dist/db/queries.js.map +1 -1
  21. package/dist/db/sqlite-adapter.d.ts +17 -23
  22. package/dist/db/sqlite-adapter.d.ts.map +1 -1
  23. package/dist/db/sqlite-adapter.js +51 -174
  24. package/dist/db/sqlite-adapter.js.map +1 -1
  25. package/dist/extraction/grammars.d.ts +7 -1
  26. package/dist/extraction/grammars.d.ts.map +1 -1
  27. package/dist/extraction/grammars.js +42 -2
  28. package/dist/extraction/grammars.js.map +1 -1
  29. package/dist/extraction/index.d.ts +9 -14
  30. package/dist/extraction/index.d.ts.map +1 -1
  31. package/dist/extraction/index.js +131 -124
  32. package/dist/extraction/index.js.map +1 -1
  33. package/dist/extraction/languages/index.d.ts.map +1 -1
  34. package/dist/extraction/languages/index.js +4 -0
  35. package/dist/extraction/languages/index.js.map +1 -1
  36. package/dist/extraction/languages/lua.d.ts +3 -0
  37. package/dist/extraction/languages/lua.d.ts.map +1 -0
  38. package/dist/extraction/languages/lua.js +150 -0
  39. package/dist/extraction/languages/lua.js.map +1 -0
  40. package/dist/extraction/languages/luau.d.ts +3 -0
  41. package/dist/extraction/languages/luau.d.ts.map +1 -0
  42. package/dist/extraction/languages/luau.js +37 -0
  43. package/dist/extraction/languages/luau.js.map +1 -0
  44. package/dist/extraction/tree-sitter.d.ts.map +1 -1
  45. package/dist/extraction/tree-sitter.js +38 -0
  46. package/dist/extraction/tree-sitter.js.map +1 -1
  47. package/dist/extraction/wasm/tree-sitter-lua.wasm +0 -0
  48. package/dist/extraction/wasm/tree-sitter-luau.wasm +0 -0
  49. package/dist/extraction/wasm-runtime-flags.d.ts +38 -0
  50. package/dist/extraction/wasm-runtime-flags.d.ts.map +1 -0
  51. package/dist/extraction/wasm-runtime-flags.js +105 -0
  52. package/dist/extraction/wasm-runtime-flags.js.map +1 -0
  53. package/dist/graph/traversal.d.ts.map +1 -1
  54. package/dist/graph/traversal.js +71 -36
  55. package/dist/graph/traversal.js.map +1 -1
  56. package/dist/index.d.ts +11 -5
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +28 -18
  59. package/dist/index.js.map +1 -1
  60. package/dist/installer/config-writer.d.ts.map +1 -1
  61. package/dist/installer/config-writer.js +3 -1
  62. package/dist/installer/config-writer.js.map +1 -1
  63. package/dist/installer/index.d.ts +66 -2
  64. package/dist/installer/index.d.ts.map +1 -1
  65. package/dist/installer/index.js +195 -5
  66. package/dist/installer/index.js.map +1 -1
  67. package/dist/installer/instructions-template.d.ts +2 -2
  68. package/dist/installer/instructions-template.d.ts.map +1 -1
  69. package/dist/installer/instructions-template.js +4 -2
  70. package/dist/installer/instructions-template.js.map +1 -1
  71. package/dist/installer/targets/claude.d.ts +26 -6
  72. package/dist/installer/targets/claude.d.ts.map +1 -1
  73. package/dist/installer/targets/claude.js +165 -10
  74. package/dist/installer/targets/claude.js.map +1 -1
  75. package/dist/installer/targets/cursor.d.ts.map +1 -1
  76. package/dist/installer/targets/cursor.js +57 -3
  77. package/dist/installer/targets/cursor.js.map +1 -1
  78. package/dist/installer/targets/hermes.d.ts +18 -0
  79. package/dist/installer/targets/hermes.d.ts.map +1 -0
  80. package/dist/installer/targets/hermes.js +305 -0
  81. package/dist/installer/targets/hermes.js.map +1 -0
  82. package/dist/installer/targets/registry.d.ts.map +1 -1
  83. package/dist/installer/targets/registry.js +2 -0
  84. package/dist/installer/targets/registry.js.map +1 -1
  85. package/dist/installer/targets/types.d.ts +1 -1
  86. package/dist/installer/targets/types.d.ts.map +1 -1
  87. package/dist/mcp/index.d.ts +12 -0
  88. package/dist/mcp/index.d.ts.map +1 -1
  89. package/dist/mcp/index.js +213 -18
  90. package/dist/mcp/index.js.map +1 -1
  91. package/dist/mcp/server-instructions.d.ts +1 -1
  92. package/dist/mcp/server-instructions.d.ts.map +1 -1
  93. package/dist/mcp/server-instructions.js +15 -0
  94. package/dist/mcp/server-instructions.js.map +1 -1
  95. package/dist/mcp/tools.d.ts +25 -1
  96. package/dist/mcp/tools.d.ts.map +1 -1
  97. package/dist/mcp/tools.js +221 -30
  98. package/dist/mcp/tools.js.map +1 -1
  99. package/dist/mcp/transport.d.ts +17 -0
  100. package/dist/mcp/transport.d.ts.map +1 -1
  101. package/dist/mcp/transport.js +63 -0
  102. package/dist/mcp/transport.js.map +1 -1
  103. package/dist/resolution/frameworks/drupal.d.ts +51 -0
  104. package/dist/resolution/frameworks/drupal.d.ts.map +1 -0
  105. package/dist/resolution/frameworks/drupal.js +335 -0
  106. package/dist/resolution/frameworks/drupal.js.map +1 -0
  107. package/dist/resolution/frameworks/index.d.ts +2 -0
  108. package/dist/resolution/frameworks/index.d.ts.map +1 -1
  109. package/dist/resolution/frameworks/index.js +9 -1
  110. package/dist/resolution/frameworks/index.js.map +1 -1
  111. package/dist/resolution/frameworks/nestjs.d.ts +26 -0
  112. package/dist/resolution/frameworks/nestjs.d.ts.map +1 -0
  113. package/dist/resolution/frameworks/nestjs.js +374 -0
  114. package/dist/resolution/frameworks/nestjs.js.map +1 -0
  115. package/dist/resolution/index.d.ts.map +1 -1
  116. package/dist/resolution/index.js +40 -7
  117. package/dist/resolution/index.js.map +1 -1
  118. package/dist/resolution/lru-cache.d.ts +24 -0
  119. package/dist/resolution/lru-cache.d.ts.map +1 -0
  120. package/dist/resolution/lru-cache.js +62 -0
  121. package/dist/resolution/lru-cache.js.map +1 -0
  122. package/dist/sync/git-hooks.d.ts +45 -0
  123. package/dist/sync/git-hooks.d.ts.map +1 -0
  124. package/dist/sync/git-hooks.js +223 -0
  125. package/dist/sync/git-hooks.js.map +1 -0
  126. package/dist/sync/index.d.ts +4 -0
  127. package/dist/sync/index.d.ts.map +1 -1
  128. package/dist/sync/index.js +12 -1
  129. package/dist/sync/index.js.map +1 -1
  130. package/dist/sync/watch-policy.d.ts +48 -0
  131. package/dist/sync/watch-policy.d.ts.map +1 -0
  132. package/dist/sync/watch-policy.js +124 -0
  133. package/dist/sync/watch-policy.js.map +1 -0
  134. package/dist/sync/watcher.d.ts +2 -4
  135. package/dist/sync/watcher.d.ts.map +1 -1
  136. package/dist/sync/watcher.js +14 -6
  137. package/dist/sync/watcher.js.map +1 -1
  138. package/dist/types.d.ts +1 -1
  139. package/dist/types.d.ts.map +1 -1
  140. package/dist/types.js +11 -0
  141. package/dist/types.js.map +1 -1
  142. package/dist/utils.js +1 -1
  143. package/package.json +4 -4
  144. package/scripts/add-lang/bench.sh +60 -0
  145. package/scripts/add-lang/check-grammar.mjs +75 -0
  146. package/scripts/add-lang/dump-ast.mjs +103 -0
  147. package/scripts/add-lang/verify-extraction.mjs +70 -0
  148. package/scripts/agent-eval/audit.sh +68 -0
  149. package/scripts/agent-eval/itrun.sh +1 -1
  150. package/scripts/agent-eval/run-all.sh +67 -0
  151. package/scripts/build-bundle.sh +118 -0
  152. package/scripts/npm-shim.js +246 -0
  153. package/scripts/pack-npm.sh +95 -0
  154. package/scripts/patch-tree-sitter-dart.js +0 -112
  155. package/scripts/release.sh +0 -68
package/README.md CHANGED
@@ -2,45 +2,68 @@
2
2
 
3
3
  # CodeGraph
4
4
 
5
- ### Supercharge Claude Code, Cursor, Codex, and OpenCode with Semantic Code Intelligence
5
+ ### Supercharge Claude Code, Cursor, Codex, OpenCode, and Hermes Agent with Semantic Code Intelligence
6
6
 
7
- **94% fewer tool calls · 77% faster exploration · 100% local**
7
+ **~35% cheaper · ~70% fewer tool calls · 100% local**
8
8
 
9
9
  [![npm version](https://img.shields.io/npm/v/@stupidloud/codegraph.svg)](https://www.npmjs.com/package/@stupidloud/codegraph)
10
10
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11
- [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
11
+ [![Self-contained](https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen.svg)](https://nodejs.org/)
12
12
 
13
- [![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#)
14
- [![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#)
15
- [![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#)
16
- [![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#)
17
- [![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#)
18
- [![Codex CLI](https://img.shields.io/badge/Codex_CLI-supported-blueviolet.svg)](#)
19
- [![opencode](https://img.shields.io/badge/opencode-supported-blueviolet.svg)](#)
13
+ [![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#supported-platforms)
14
+ [![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#supported-platforms)
15
+ [![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#supported-platforms)
16
+
17
+ [![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#supported-agents)
18
+ [![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#supported-agents)
19
+ [![Codex CLI](https://img.shields.io/badge/Codex_CLI-supported-blueviolet.svg)](#supported-agents)
20
+ [![opencode](https://img.shields.io/badge/opencode-supported-blueviolet.svg)](#supported-agents)
21
+ [![Hermes Agent](https://img.shields.io/badge/Hermes_Agent-supported-blueviolet.svg)](#supported-agents)
20
22
 
21
23
  [English](./README.md) · [简体中文](./README.zh-CN.md)
22
24
 
23
- <br />
25
+ </div>
26
+
27
+ ## Get Started
24
28
 
25
- ### Get Started
29
+ **No Node.js required** — one command grabs the right build for your OS:
26
30
 
27
31
  ```bash
28
32
  npx @stupidloud/codegraph
29
33
  ```
30
34
 
31
- <sub>Interactive installer auto-configures your agent(s) Claude Code, Cursor, Codex CLI, opencode</sub>
35
+ Already have Node? Use npm instead (works on any version):
32
36
 
33
- #### Initialize Projects
37
+ ```bash
38
+ npx @stupidloud/codegraph # zero-install, or:
39
+ npm i -g @stupidloud/codegraph
40
+ ```
41
+
42
+ <sub>CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent.</sub>
43
+
44
+ ### Initialize Projects
34
45
 
35
46
  ```bash
36
47
  cd your-project
37
48
  codegraph init -i
38
49
  ```
39
50
 
51
+ <div align="center">
52
+
40
53
  ![1_C_VYnhpys0UHrOuOgpgoyw](https://github.com/user-attachments/assets/f168182f-4d9a-44e0-94d7-08d018cc8a3a)
41
54
 
42
55
  </div>
43
56
 
57
+ ### Uninstall
58
+
59
+ Changed your mind? One command removes CodeGraph from every agent it configured:
60
+
61
+ ```bash
62
+ codegraph uninstall
63
+ ```
64
+
65
+ <sub>Reverses the installer — strips CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.</sub>
66
+
44
67
  ---
45
68
 
46
69
  ## Why CodeGraph?
@@ -51,61 +74,50 @@ When Claude Code explores a codebase, it spawns **Explore agents** that scan fil
51
74
 
52
75
  ### Benchmark Results
53
76
 
54
- Tested across 6 real-world codebases comparing Claude Code's Explore agent **with** and **without** CodeGraph:
77
+ Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**.
78
+
79
+ > **Average: 35% cheaper · 59% fewer tokens · 49% faster · 70% fewer tool calls**
55
80
 
56
- > **Average: 92% fewer tool calls · 71% faster**
81
+ | Codebase | Language | Cost | Tokens | Time | Tool calls |
82
+ |----------|----------|------|--------|------|------------|
83
+ | **VS Code** | TypeScript · ~10k files | 35% cheaper | 73% fewer | 41% faster | 72% fewer |
84
+ | **Excalidraw** | TypeScript · ~600 | 47% cheaper | 73% fewer | 60% faster | 86% fewer |
85
+ | **Django** | Python · ~2.7k | 34% cheaper | 64% fewer | 59% faster | 81% fewer |
86
+ | **Tokio** | Rust · ~700 | 52% cheaper | 81% fewer | 63% faster | 89% fewer |
87
+ | **OkHttp** | Java · ~640 | 17% cheaper | 41% fewer | 36% faster | 64% fewer |
88
+ | **Gin** | Go · ~150 | 22% cheaper | 23% fewer | 34% faster | 19% fewer |
89
+ | **Alamofire** | Swift · ~100 | 38% cheaper | 59% fewer | 51% faster | 77% fewer |
57
90
 
58
- | Codebase | With CG | Without CG | Improvement |
59
- |----------|---------|------------|-------------|
60
- | **VS Code** · TypeScript | 3 calls, 17s | 52 calls, 1m 37s | **94% fewer · 82% faster** |
61
- | **Excalidraw** · TypeScript | 3 calls, 29s | 47 calls, 1m 45s | **94% fewer · 72% faster** |
62
- | **Claude Code** · Python + Rust | 3 calls, 39s | 40 calls, 1m 8s | **93% fewer · 43% faster** |
63
- | **Claude Code** · Java | 1 call, 19s | 26 calls, 1m 22s | **96% fewer · 77% faster** |
64
- | **Alamofire** · Swift | 3 calls, 22s | 32 calls, 1m 39s | **91% fewer · 78% faster** |
65
- | **Swift Compiler** · Swift/C++ | 6 calls, 35s | 37 calls, 2m 8s | **84% fewer · 73% faster** |
91
+ The gains scale with codebase size: on large repos the agent answers from the index in a handful of calls with **zero file reads**, while the no-CodeGraph agent fans out across grep/find/Read (and the sub-agents it spawns). On a small repo like Gin (~150 files) native search is already cheap, so the margin narrows.
66
92
 
67
93
  <details>
68
94
  <summary><strong>Full benchmark details</strong></summary>
69
95
 
70
- All tests used Claude Opus 4.6 (1M context) with Claude Code v2.1.91. Each test spawned a single Explore agent with the same question.
96
+ **Methodology.** Each arm is `claude -p` (Claude Opus 4.7, Claude Code v2.1.145) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them.
71
97
 
72
- **Queries used:**
98
+ **Queries:**
73
99
  | Codebase | Query |
74
100
  |----------|-------|
75
101
  | VS Code | "How does the extension host communicate with the main process?" |
76
- | Excalidraw | "How does collaborative editing and real-time sync work?" |
77
- | Claude Code (Python+Rust) | "How does tool execution work end to end?" |
78
- | Claude Code (Java) | "How does tool execution work end to end?" |
79
- | Alamofire | "Trace how a request flows from Session.request() through to the URLSession layer" |
80
- | Swift Compiler | "How does the Swift compiler handle error diagnostics?" |
81
-
82
- **With CodeGraph — the agent uses `codegraph_explore` and stops:**
83
- | Codebase | Files Indexed | Nodes | Tool Uses | Tokens | Time | File Reads |
84
- |----------|--------------|-------|-----------|--------|------|------------|
85
- | VS Code (TypeScript) | 4,002 | 59,377 | 3 | 56.6k | 17s | 0 |
86
- | Excalidraw (TypeScript) | 626 | 9,859 | 3 | 57.1k | 29s | 0 |
87
- | Claude Code (Python+Rust) | 115 | 3,080 | 3 | 67.1k | 39s | 0 |
88
- | Claude Code (Java) | | | 1 | 40.8k | 19s | 0 |
89
- | Alamofire (Swift) | 102 | 2,624 | 3 | 57.3k | 22s | 0 |
90
- | Swift Compiler (Swift/C++) | 25,874 | 272,898 | 6 | 77.4k | 35s | 0 |
91
-
92
- **Without CodeGraph the agent uses grep, find, ls, and Read extensively:**
93
- | Codebase | Tool Uses | Tokens | Time | File Reads |
94
- |----------|-----------|--------|------|------------|
95
- | VS Code (TypeScript) | 52 | 89.4k | 1m 37s | ~15 |
96
- | Excalidraw (TypeScript) | 47 | 77.9k | 1m 45s | ~20 |
97
- | Claude Code (Python+Rust) | 40 | 69.3k | 1m 8s | ~15 |
98
- | Claude Code (Java) | 26 | 73.3k | 1m 22s | ~15 |
99
- | Alamofire (Swift) | 32 | 52.4k | 1m 39s | ~10 |
100
- | Swift Compiler (Swift/C++) | 37 | 99.1k | 2m 8s | ~20 |
101
-
102
- **Key observations:**
103
- - With CodeGraph, the agent **never fell back to reading files** — it trusted the codegraph_explore results completely
104
- - Without CodeGraph, agents spent most of their time on discovery (find, ls, grep) before they could even start reading relevant code
105
- - The Java codebase needed only **1 codegraph_explore call** to answer the entire question
106
- - Cross-language queries (Python+Rust) worked seamlessly — CodeGraph's graph traversal found connections across language boundaries
107
- - The Swift benchmark (Alamofire) traced a **9-step call chain** from `Session.request()` to `URLSession.dataTask()` — CodeGraph's graph traversal at depth 3 captured the full chain in one explore call
108
- - The **Swift Compiler** benchmark is the largest codebase tested (**25,874 files, 272,898 nodes**) — CodeGraph indexed it in under 4 minutes and the agent answered a complex cross-cutting question with **6 explore calls and zero file reads** in 35 seconds
102
+ | Excalidraw | "How does Excalidraw render and update canvas elements?" |
103
+ | Django | "How does Django's ORM build and execute a query from a QuerySet?" |
104
+ | Tokio | "How does tokio schedule and run async tasks on its runtime?" |
105
+ | OkHttp | "How does OkHttp process a request through its interceptor chain?" |
106
+ | Gin | "How does gin route requests through its middleware chain?" |
107
+ | Alamofire | "How does Alamofire build, send, and validate a request?" |
108
+
109
+ **Raw medians WITH WITHOUT:**
110
+ | Codebase | Cost | Tokens | Time | Tool calls |
111
+ |----------|------|--------|------|------------|
112
+ | VS Code | $0.42 $0.64 | 393k 1.4M | 1m 0s → 1m 43s | 7 → 23 |
113
+ | Excalidraw | $0.54 $1.02 | 851k 3.2M | 1m 17s 3m 14s | 12 → 83 |
114
+ | Django | $0.41 $0.62 | 499k 1.4M | 1m 0s 2m 25s | 9 → 48 |
115
+ | Tokio | $0.50 $1.04 | 657k 3.4M | 1m 5s → 2m 56s | 9 → 75 |
116
+ | OkHttp | $0.36 $0.44 | 352k 596k | 45s 1m 11s | 5 → 14 |
117
+ | Gin | $0.36 → $0.46 | 431k → 562k | 47s → 1m 11s | 7 → 8 |
118
+ | Alamofire | $0.61 $0.99 | 1.1M 2.6M | 1m 19s → 2m 41s | 15 → 64 |
119
+
120
+ **Why CodeGraph wins:** with the index available, the agent answers directly — `codegraph_context` to map the area, then one `codegraph_explore` for the relevant source — and stops, usually with zero file reads. Without it, the agent (and the Explore sub-agents it spawns) spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when queried *directly*, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.
109
121
 
110
122
  </details>
111
123
 
@@ -119,8 +131,8 @@ All tests used Claude Opus 4.6 (1M context) with Claude Code v2.1.91. Each test
119
131
  | **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 |
120
132
  | **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes |
121
133
  | **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |
122
- | **19+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi |
123
- | **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 13 frameworks |
134
+ | **19+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi |
135
+ | **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 14 frameworks |
124
136
  | **100% Local** | No data leaves your machine. No API keys. No external services. SQLite database only |
125
137
 
126
138
  ---
@@ -135,7 +147,9 @@ CodeGraph detects web-framework routing files and emits `route` nodes linked by
135
147
  | **Flask** | `@app.route('/path', methods=[...])`, blueprint routes |
136
148
  | **FastAPI** | `@app.get(...)`, `@router.post(...)`, all standard methods |
137
149
  | **Express** | `app.get(...)`, `router.post(...)` with middleware chains |
150
+ | **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` |
138
151
  | **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |
152
+ | **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |
139
153
  | **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=>` syntax |
140
154
  | **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
141
155
  | **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` |
@@ -155,7 +169,7 @@ npx @stupidloud/codegraph
155
169
  ```
156
170
 
157
171
  The installer will:
158
- - Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**
172
+ - Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**
159
173
  - Prompt to install `codegraph` on your PATH (so agents can launch the MCP server)
160
174
  - Ask whether configs apply to all your projects or just this one
161
175
  - Write each chosen agent's MCP server config + an instructions file (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`)
@@ -181,7 +195,7 @@ codegraph install --print-config codex # print snippet, no file wr
181
195
 
182
196
  ### 2. Restart Your Agent
183
197
 
184
- Restart your agent (Claude Code / Cursor / Codex CLI / opencode) for the MCP server to load.
198
+ Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent) for the MCP server to load.
185
199
 
186
200
  ### 3. Initialize Projects
187
201
 
@@ -327,6 +341,7 @@ At the start of a session, ask the user if they'd like to initialize CodeGraph:
327
341
  ```bash
328
342
  codegraph # Run interactive installer
329
343
  codegraph install # Run installer (explicit)
344
+ codegraph uninstall # Remove CodeGraph from your agents (inverse of install)
330
345
  codegraph init [path] # Initialize in a project (--index to also index)
331
346
  codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt)
332
347
  codegraph index [path] # Full index (--force to re-index, --quiet for less output)
@@ -335,6 +350,9 @@ codegraph status [path] # Show statistics
335
350
  codegraph query <search> # Search symbols (--kind, --limit, --json)
336
351
  codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json)
337
352
  codegraph context <task> # Build context for AI (--format, --max-nodes)
353
+ codegraph callers <symbol> # Find what calls a function/method (--limit, --json)
354
+ codegraph callees <symbol> # Find what a function/method calls (--limit, --json)
355
+ codegraph impact <symbol> # Analyze what code is affected by changing a symbol (--depth, --json)
338
356
  codegraph affected [files...] # Find test files affected by changes (see below)
339
357
  codegraph serve --mcp # Start MCP server
340
358
  ```
@@ -381,6 +399,7 @@ When running as an MCP server, CodeGraph exposes these tools to Claude Code:
381
399
  | `codegraph_callees` | Find what a function calls |
382
400
  | `codegraph_impact` | Analyze what code is affected by changing a symbol |
383
401
  | `codegraph_node` | Get details about a specific symbol (optionally with source code) |
402
+ | `codegraph_explore` | Return source for several related symbols grouped by file, plus a relationship map, in one call |
384
403
  | `codegraph_files` | Get indexed file structure (faster than filesystem scanning) |
385
404
  | `codegraph_status` | Check index health and statistics |
386
405
 
@@ -412,28 +431,47 @@ cg.close();
412
431
 
413
432
  ## Configuration
414
433
 
415
- The `.codegraph/config.json` file controls indexing:
434
+ There isn't any — CodeGraph is zero-config. It indexes every file whose
435
+ extension maps to a [supported language](#supported-languages) and **respects
436
+ your `.gitignore`**: in git repos via git itself, and in non-git projects by
437
+ reading `.gitignore` files directly (root and nested, the same way git would).
416
438
 
417
- ```json
418
- {
419
- "version": 1,
420
- "languages": ["typescript", "javascript"],
421
- "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
422
- "frameworks": [],
423
- "maxFileSize": 1048576,
424
- "extractDocstrings": true,
425
- "trackCallSites": true
426
- }
427
- ```
439
+ What that means in practice:
428
440
 
429
- | Option | Description | Default |
430
- |--------|-------------|---------|
431
- | `languages` | Languages to index (auto-detected if empty) | `[]` |
432
- | `exclude` | Glob patterns to ignore | `["node_modules/**", ...]` |
433
- | `frameworks` | Framework hints for better resolution | `[]` |
434
- | `maxFileSize` | Skip files larger than this (bytes) | `1048576` (1MB) |
435
- | `extractDocstrings` | Extract docstrings from code | `true` |
436
- | `trackCallSites` | Track call site locations | `true` |
441
+ - Anything git ignores `node_modules`, build output, secrets in `.env` — is
442
+ never indexed. **To keep something out of the graph, add it to `.gitignore`.**
443
+ - There's no config file to write or keep in sync, and nothing to wire up per
444
+ language: support is automatic from the file extension.
445
+ - Files larger than 1 MB are skipped (generated bundles, minified JS, vendored
446
+ blobs) they cost parse budget for no useful symbols.
447
+
448
+ > Committed files that aren't gitignored *are* indexed, even under `vendor/` or a
449
+ > committed `dist/`. If you commit a dependency or build directory you don't want
450
+ > in the graph, add it to `.gitignore`.
451
+
452
+ ## Supported Platforms
453
+
454
+ Every release ships a self-contained build (bundled Node runtime — nothing to
455
+ compile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):
456
+
457
+ | Platform | Architectures | Install |
458
+ |----------|---------------|---------|
459
+ | Windows | x64, arm64 | PowerShell installer or npm |
460
+ | macOS | x64, arm64 | shell installer or npm |
461
+ | Linux | x64, arm64 | shell installer or npm |
462
+
463
+ See [Get Started](#get-started) for the one-line install commands.
464
+
465
+ ## Supported Agents
466
+
467
+ The interactive installer auto-detects and configures each of these — wiring up
468
+ the MCP server and writing its instructions file:
469
+
470
+ - **Claude Code**
471
+ - **Cursor**
472
+ - **Codex CLI**
473
+ - **opencode**
474
+ - **Hermes Agent**
437
475
 
438
476
  ## Supported Languages
439
477
 
@@ -458,6 +496,8 @@ The `.codegraph/config.json` file controls indexing:
458
496
  | Vue | `.vue` | Full support (script + script-setup extraction, Nuxt page/API/middleware routes) |
459
497
  | Liquid | `.liquid` | Full support |
460
498
  | Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX form files) |
499
+ | Lua | `.lua` | Full support (functions, methods with receivers, local variables, `require` imports, call edges) |
500
+ | Luau | `.luau` | Full support (everything in Lua, plus `type`/`export type` aliases, typed signatures, and Roblox instance-path `require`) |
461
501
 
462
502
  ## Troubleshooting
463
503
 
@@ -465,29 +505,10 @@ The `.codegraph/config.json` file controls indexing:
465
505
 
466
506
  **Indexing is slow** — Check that `node_modules` and other large directories are excluded. Use `--quiet` to reduce output overhead.
467
507
 
468
- **Indexing is slow / MCP `database is locked` / WASM fallback active** `codegraph` ships with a WASM SQLite fallback for environments where `better-sqlite3` (a native module, declared as `optionalDependencies`) can't install. The fallback is 5-10x slower than the native backend and uses a journal mode that lets writers block readers, so MCP queries can also hit `database is locked` while indexing runs. Run `codegraph status` and look at the `Backend:` line:
469
-
470
- - `Backend: native` — you're on the fast path, nothing to do.
471
- - `Backend: wasm` — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix:
472
-
473
- ```bash
474
- # macOS
475
- xcode-select --install # installs the C compiler
476
-
477
- # Linux (Debian / Ubuntu)
478
- sudo apt install build-essential python3 make
479
-
480
- # Linux (RHEL / Fedora)
481
- sudo yum groupinstall "Development Tools"
482
-
483
- # Then rebuild on any platform:
484
- npm rebuild better-sqlite3
485
-
486
- # Or force-include as a hard dep:
487
- npm install better-sqlite3 --save
488
- ```
508
+ **MCP hits `database is locked`**current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
489
509
 
490
- After the fix, `codegraph status` should show `Backend: native`.
510
+ - **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.
511
+ - **`codegraph status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.
491
512
 
492
513
  **MCP server not connecting** — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `codegraph serve --mcp` works from the command line.
493
514
 
@@ -511,7 +532,7 @@ MIT
511
532
 
512
533
  <div align="center">
513
534
 
514
- **Made for the Claude Code community**
535
+ **Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent**
515
536
 
516
537
  [Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues)
517
538
 
@@ -7,6 +7,7 @@
7
7
  * Usage:
8
8
  * codegraph Run interactive installer (when no args)
9
9
  * codegraph install Run interactive installer
10
+ * codegraph uninstall Remove CodeGraph from your agents
10
11
  * codegraph init [path] Initialize CodeGraph in a project
11
12
  * codegraph uninit [path] Remove CodeGraph from a project
12
13
  * codegraph index [path] Index all files in the project
@@ -15,6 +16,9 @@
15
16
  * codegraph query <search> Search for symbols
16
17
  * codegraph files [options] Show project file structure
17
18
  * codegraph context <task> Build context for a task
19
+ * codegraph callers <symbol> Find what calls a function/method
20
+ * codegraph callees <symbol> Find what a function/method calls
21
+ * codegraph impact <symbol> Analyze what code is affected by changing a symbol
18
22
  * codegraph affected [files] Find test files affected by changes
19
23
  */
20
24
  export {};
@@ -1 +1 @@
1
- {"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}
1
+ {"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;GAqBG"}