@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.
- package/README.md +127 -106
- package/dist/bin/codegraph.d.ts +4 -0
- package/dist/bin/codegraph.d.ts.map +1 -1
- package/dist/bin/codegraph.js +327 -8
- package/dist/bin/codegraph.js.map +1 -1
- package/dist/bin/node-version-check.d.ts +17 -0
- package/dist/bin/node-version-check.d.ts.map +1 -1
- package/dist/bin/node-version-check.js +37 -0
- package/dist/bin/node-version-check.js.map +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +1 -11
- package/dist/config.js.map +1 -1
- package/dist/db/index.d.ts +30 -1
- package/dist/db/index.d.ts.map +1 -1
- package/dist/db/index.js +75 -25
- package/dist/db/index.js.map +1 -1
- package/dist/db/queries.d.ts +16 -0
- package/dist/db/queries.d.ts.map +1 -1
- package/dist/db/queries.js +80 -27
- package/dist/db/queries.js.map +1 -1
- package/dist/db/sqlite-adapter.d.ts +17 -23
- package/dist/db/sqlite-adapter.d.ts.map +1 -1
- package/dist/db/sqlite-adapter.js +51 -174
- package/dist/db/sqlite-adapter.js.map +1 -1
- package/dist/extraction/grammars.d.ts +7 -1
- package/dist/extraction/grammars.d.ts.map +1 -1
- package/dist/extraction/grammars.js +42 -2
- package/dist/extraction/grammars.js.map +1 -1
- package/dist/extraction/index.d.ts +9 -14
- package/dist/extraction/index.d.ts.map +1 -1
- package/dist/extraction/index.js +131 -124
- package/dist/extraction/index.js.map +1 -1
- package/dist/extraction/languages/index.d.ts.map +1 -1
- package/dist/extraction/languages/index.js +4 -0
- package/dist/extraction/languages/index.js.map +1 -1
- package/dist/extraction/languages/lua.d.ts +3 -0
- package/dist/extraction/languages/lua.d.ts.map +1 -0
- package/dist/extraction/languages/lua.js +150 -0
- package/dist/extraction/languages/lua.js.map +1 -0
- package/dist/extraction/languages/luau.d.ts +3 -0
- package/dist/extraction/languages/luau.d.ts.map +1 -0
- package/dist/extraction/languages/luau.js +37 -0
- package/dist/extraction/languages/luau.js.map +1 -0
- package/dist/extraction/tree-sitter.d.ts.map +1 -1
- package/dist/extraction/tree-sitter.js +38 -0
- package/dist/extraction/tree-sitter.js.map +1 -1
- package/dist/extraction/wasm/tree-sitter-lua.wasm +0 -0
- package/dist/extraction/wasm/tree-sitter-luau.wasm +0 -0
- package/dist/extraction/wasm-runtime-flags.d.ts +38 -0
- package/dist/extraction/wasm-runtime-flags.d.ts.map +1 -0
- package/dist/extraction/wasm-runtime-flags.js +105 -0
- package/dist/extraction/wasm-runtime-flags.js.map +1 -0
- package/dist/graph/traversal.d.ts.map +1 -1
- package/dist/graph/traversal.js +71 -36
- package/dist/graph/traversal.js.map +1 -1
- package/dist/index.d.ts +11 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +28 -18
- package/dist/index.js.map +1 -1
- package/dist/installer/config-writer.d.ts.map +1 -1
- package/dist/installer/config-writer.js +3 -1
- package/dist/installer/config-writer.js.map +1 -1
- package/dist/installer/index.d.ts +66 -2
- package/dist/installer/index.d.ts.map +1 -1
- package/dist/installer/index.js +195 -5
- package/dist/installer/index.js.map +1 -1
- package/dist/installer/instructions-template.d.ts +2 -2
- package/dist/installer/instructions-template.d.ts.map +1 -1
- package/dist/installer/instructions-template.js +4 -2
- package/dist/installer/instructions-template.js.map +1 -1
- package/dist/installer/targets/claude.d.ts +26 -6
- package/dist/installer/targets/claude.d.ts.map +1 -1
- package/dist/installer/targets/claude.js +165 -10
- package/dist/installer/targets/claude.js.map +1 -1
- package/dist/installer/targets/cursor.d.ts.map +1 -1
- package/dist/installer/targets/cursor.js +57 -3
- package/dist/installer/targets/cursor.js.map +1 -1
- package/dist/installer/targets/hermes.d.ts +18 -0
- package/dist/installer/targets/hermes.d.ts.map +1 -0
- package/dist/installer/targets/hermes.js +305 -0
- package/dist/installer/targets/hermes.js.map +1 -0
- package/dist/installer/targets/registry.d.ts.map +1 -1
- package/dist/installer/targets/registry.js +2 -0
- package/dist/installer/targets/registry.js.map +1 -1
- package/dist/installer/targets/types.d.ts +1 -1
- package/dist/installer/targets/types.d.ts.map +1 -1
- package/dist/mcp/index.d.ts +12 -0
- package/dist/mcp/index.d.ts.map +1 -1
- package/dist/mcp/index.js +213 -18
- package/dist/mcp/index.js.map +1 -1
- package/dist/mcp/server-instructions.d.ts +1 -1
- package/dist/mcp/server-instructions.d.ts.map +1 -1
- package/dist/mcp/server-instructions.js +15 -0
- package/dist/mcp/server-instructions.js.map +1 -1
- package/dist/mcp/tools.d.ts +25 -1
- package/dist/mcp/tools.d.ts.map +1 -1
- package/dist/mcp/tools.js +221 -30
- package/dist/mcp/tools.js.map +1 -1
- package/dist/mcp/transport.d.ts +17 -0
- package/dist/mcp/transport.d.ts.map +1 -1
- package/dist/mcp/transport.js +63 -0
- package/dist/mcp/transport.js.map +1 -1
- package/dist/resolution/frameworks/drupal.d.ts +51 -0
- package/dist/resolution/frameworks/drupal.d.ts.map +1 -0
- package/dist/resolution/frameworks/drupal.js +335 -0
- package/dist/resolution/frameworks/drupal.js.map +1 -0
- package/dist/resolution/frameworks/index.d.ts +2 -0
- package/dist/resolution/frameworks/index.d.ts.map +1 -1
- package/dist/resolution/frameworks/index.js +9 -1
- package/dist/resolution/frameworks/index.js.map +1 -1
- package/dist/resolution/frameworks/nestjs.d.ts +26 -0
- package/dist/resolution/frameworks/nestjs.d.ts.map +1 -0
- package/dist/resolution/frameworks/nestjs.js +374 -0
- package/dist/resolution/frameworks/nestjs.js.map +1 -0
- package/dist/resolution/index.d.ts.map +1 -1
- package/dist/resolution/index.js +40 -7
- package/dist/resolution/index.js.map +1 -1
- package/dist/resolution/lru-cache.d.ts +24 -0
- package/dist/resolution/lru-cache.d.ts.map +1 -0
- package/dist/resolution/lru-cache.js +62 -0
- package/dist/resolution/lru-cache.js.map +1 -0
- package/dist/sync/git-hooks.d.ts +45 -0
- package/dist/sync/git-hooks.d.ts.map +1 -0
- package/dist/sync/git-hooks.js +223 -0
- package/dist/sync/git-hooks.js.map +1 -0
- package/dist/sync/index.d.ts +4 -0
- package/dist/sync/index.d.ts.map +1 -1
- package/dist/sync/index.js +12 -1
- package/dist/sync/index.js.map +1 -1
- package/dist/sync/watch-policy.d.ts +48 -0
- package/dist/sync/watch-policy.d.ts.map +1 -0
- package/dist/sync/watch-policy.js +124 -0
- package/dist/sync/watch-policy.js.map +1 -0
- package/dist/sync/watcher.d.ts +2 -4
- package/dist/sync/watcher.d.ts.map +1 -1
- package/dist/sync/watcher.js +14 -6
- package/dist/sync/watcher.js.map +1 -1
- package/dist/types.d.ts +1 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +11 -0
- package/dist/types.js.map +1 -1
- package/dist/utils.js +1 -1
- package/package.json +4 -4
- package/scripts/add-lang/bench.sh +60 -0
- package/scripts/add-lang/check-grammar.mjs +75 -0
- package/scripts/add-lang/dump-ast.mjs +103 -0
- package/scripts/add-lang/verify-extraction.mjs +70 -0
- package/scripts/agent-eval/audit.sh +68 -0
- package/scripts/agent-eval/itrun.sh +1 -1
- package/scripts/agent-eval/run-all.sh +67 -0
- package/scripts/build-bundle.sh +118 -0
- package/scripts/npm-shim.js +246 -0
- package/scripts/pack-npm.sh +95 -0
- package/scripts/patch-tree-sitter-dart.js +0 -112
- 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
|
|
5
|
+
### Supercharge Claude Code, Cursor, Codex, OpenCode, and Hermes Agent with Semantic Code Intelligence
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**~35% cheaper · ~70% fewer tool calls · 100% local**
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/@stupidloud/codegraph)
|
|
10
10
|
[](https://opensource.org/licenses/MIT)
|
|
11
|
-
[](https://nodejs.org/)
|
|
12
12
|
|
|
13
|
-
[](#)
|
|
14
|
-
[](#)
|
|
15
|
-
[](#)
|
|
16
|
-
|
|
17
|
-
[](#supported-platforms)
|
|
14
|
+
[](#supported-platforms)
|
|
15
|
+
[](#supported-platforms)
|
|
16
|
+
|
|
17
|
+
[](#supported-agents)
|
|
18
|
+
[](#supported-agents)
|
|
19
|
+
[](#supported-agents)
|
|
20
|
+
[](#supported-agents)
|
|
21
|
+
[](#supported-agents)
|
|
20
22
|
|
|
21
23
|
[English](./README.md) · [简体中文](./README.zh-CN.md)
|
|
22
24
|
|
|
23
|
-
|
|
25
|
+
</div>
|
|
26
|
+
|
|
27
|
+
## Get Started
|
|
24
28
|
|
|
25
|
-
|
|
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
|
-
|
|
35
|
+
Already have Node? Use npm instead (works on any version):
|
|
32
36
|
|
|
33
|
-
|
|
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
|

|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
|
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
|
|
package/dist/bin/codegraph.d.ts
CHANGED
|
@@ -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
|
|
1
|
+
{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;GAqBG"}
|