homegraph 0.9.9 → 0.9.10
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 +102 -618
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,709 +1,193 @@
|
|
|
1
|
-
|
|
1
|
+
# HomeGraph
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
基于 [CodeGraph](https://github.com/colbymchenry/codegraph) 开发的本地代码知识图谱工具，面向 AI 编程助手（Claude Code、Cursor、Codex 等）提供 MCP 服务。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
在 CodeGraph 原有能力之上，**HomeGraph 新增了对 ArkTS（HarmonyOS）的支持**，通过 [arkanalyzer](https://www.npmjs.com/package/arkanalyzer) 解析 `.ets` / `.ts` 工程中的符号、调用关系与模块结构。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
数据全部保存在本机 `.homegraph/` 目录，不上传云端。
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
[](https://www.npmjs.com/package/@colbymchenry/codegraph)
|
|
9
|
+
[](https://www.npmjs.com/package/homegraph)
|
|
12
10
|
[](https://opensource.org/licenses/MIT)
|
|
13
|
-
[](https://nodejs.org/)
|
|
14
|
-
|
|
15
|
-
[](#supported-platforms)
|
|
16
|
-
[](#supported-platforms)
|
|
17
|
-
[](#supported-platforms)
|
|
18
|
-
|
|
19
|
-
[](#supported-agents)
|
|
20
|
-
[](#supported-agents)
|
|
21
|
-
[](#supported-agents)
|
|
22
|
-
[](#supported-agents)
|
|
23
|
-
[](#supported-agents)
|
|
24
|
-
[](#supported-agents)
|
|
25
|
-
[](#supported-agents)
|
|
26
|
-
[](#supported-agents)
|
|
27
11
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
**The CodeGraph platform is coming** — for every PR, know exactly what to test, what could break, which flows are affected, and whether business logic is compromised.
|
|
31
|
-
|
|
32
|
-
<a href="https://getcodegraph.com"><img alt="Join the waitlist for early beta access" src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/waitlist.svg?v=2" height="52"></a>
|
|
12
|
+
---
|
|
33
13
|
|
|
34
|
-
|
|
14
|
+
## 快速开始
|
|
35
15
|
|
|
36
|
-
|
|
16
|
+
### 1. 安装 CLI
|
|
37
17
|
|
|
38
|
-
|
|
18
|
+
需要 **Node.js 20–24**。
|
|
39
19
|
|
|
40
|
-
|
|
20
|
+
```bash
|
|
21
|
+
npm install -g homegraph
|
|
22
|
+
```
|
|
41
23
|
|
|
42
|
-
|
|
24
|
+
若在 Linux/WSL 遇到 `EACCES` 权限错误，可任选其一：
|
|
43
25
|
|
|
44
26
|
```bash
|
|
45
|
-
#
|
|
46
|
-
|
|
27
|
+
# 临时
|
|
28
|
+
sudo npm install -g homegraph
|
|
47
29
|
|
|
48
|
-
#
|
|
49
|
-
|
|
30
|
+
# 或把全局目录改到用户家目录（推荐）
|
|
31
|
+
mkdir -p ~/.npm-global
|
|
32
|
+
npm config set prefix ~/.npm-global
|
|
33
|
+
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
|
|
34
|
+
source ~/.bashrc
|
|
35
|
+
npm install -g homegraph
|
|
50
36
|
```
|
|
51
37
|
|
|
52
|
-
|
|
38
|
+
验证：
|
|
53
39
|
|
|
54
40
|
```bash
|
|
55
|
-
|
|
41
|
+
homegraph --version
|
|
56
42
|
```
|
|
57
43
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
<sub>**Upgrade any time** with `codegraph upgrade` — it detects how you installed (bundle, npm, or npx) and updates in place. Add `--check` to see if an update is available, or `codegraph upgrade <version>` to pin one.</sub>
|
|
44
|
+
### 2. 接入 AI 助手
|
|
61
45
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
In a **new terminal**, run the installer to connect CodeGraph to the agents you use:
|
|
46
|
+
在新终端中运行交互式安装器，自动写入各 Agent 的 MCP 配置：
|
|
65
47
|
|
|
66
48
|
```bash
|
|
67
|
-
|
|
49
|
+
homegraph install
|
|
68
50
|
```
|
|
69
51
|
|
|
70
|
-
|
|
52
|
+
支持的 Agent：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro。
|
|
71
53
|
|
|
72
|
-
|
|
54
|
+
非交互式示例：
|
|
73
55
|
|
|
74
56
|
```bash
|
|
75
|
-
|
|
76
|
-
|
|
57
|
+
homegraph install --yes
|
|
58
|
+
homegraph install --target=cursor,claude --location=global --yes
|
|
77
59
|
```
|
|
78
60
|
|
|
79
|
-
|
|
61
|
+
安装完成后**重启对应 Agent**，使 MCP 配置生效。
|
|
80
62
|
|
|
81
|
-
|
|
63
|
+
### 3. 初始化项目
|
|
82
64
|
|
|
83
|
-
|
|
65
|
+
```bash
|
|
66
|
+
cd your-project
|
|
67
|
+
homegraph init -i
|
|
68
|
+
```
|
|
84
69
|
|
|
85
|
-
|
|
70
|
+
- `homegraph init`：仅创建 `.homegraph/` 索引目录
|
|
71
|
+
- `homegraph init -i`：创建目录并立即建立索引（推荐）
|
|
86
72
|
|
|
87
|
-
|
|
73
|
+
索引建立后，Agent 可通过 MCP 工具查询符号、调用链、影响范围等。
|
|
88
74
|
|
|
89
|
-
|
|
75
|
+
### 卸载
|
|
90
76
|
|
|
91
77
|
```bash
|
|
92
|
-
|
|
78
|
+
homegraph uninstall # 从各 Agent 移除 MCP 配置
|
|
79
|
+
homegraph uninit # 删除当前项目的 .homegraph/ 索引
|
|
93
80
|
```
|
|
94
81
|
|
|
95
|
-
<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>
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## Why CodeGraph?
|
|
100
|
-
|
|
101
|
-
When Claude Code explores a codebase, it spawns **Explore agents** that scan files with grep, glob, and Read — consuming tokens on every tool call.
|
|
102
|
-
|
|
103
|
-
**CodeGraph gives those agents a pre-indexed knowledge graph** — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.
|
|
104
|
-
|
|
105
|
-
### Benchmark Results
|
|
106
|
-
|
|
107
|
-
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**. _Re-validated on Opus 4.8 (2026-06-02), on the current build (`codegraph_explore` as the primary tool)._
|
|
108
|
-
|
|
109
|
-
> **Average: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls**
|
|
110
|
-
|
|
111
|
-
| Codebase | Language | Cost | Tokens | Time | Tool calls |
|
|
112
|
-
|----------|----------|------|--------|------|------------|
|
|
113
|
-
| **VS Code** | TypeScript · ~10k files | 18% cheaper | 64% fewer | 11% faster | 81% fewer |
|
|
114
|
-
| **Excalidraw** | TypeScript · ~640 | even | 25% fewer | 27% faster | 40% fewer |
|
|
115
|
-
| **Django** | Python · ~3k | 8% cheaper | 60% fewer | 13% faster | 77% fewer |
|
|
116
|
-
| **Tokio** | Rust · ~790 | even | 38% fewer | 18% faster | 57% fewer |
|
|
117
|
-
| **OkHttp** | Java · ~645 | 25% cheaper | 54% fewer | 31% faster | 50% fewer |
|
|
118
|
-
| **Gin** | Go · ~110 | 19% cheaper | 23% fewer | 24% faster | 44% fewer |
|
|
119
|
-
| **Alamofire** | Swift · ~110 | 40% cheaper | 64% fewer | 33% faster | 58% fewer |
|
|
120
|
-
|
|
121
|
-
CodeGraph cuts **tokens, tool calls, and wall-clock time on every repo** — across small, medium, and large codebases — and answers them with **near-zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. `codegraph_explore` shows the answer in full — the mechanism plus the exact methods you asked about, even when they're buried in a multi-thousand-line file — while collapsing redundant interchangeable implementations to signatures, so the response is sized to the *answer* rather than the file count. **Cost stays flat-to-cheaper everywhere** — largest on the small repos (Alamofire, OkHttp), roughly break-even on the most response-heavy ones (Excalidraw, Tokio), where CodeGraph trades the no-CodeGraph agent's many small grep/read round-trips for a few large, cache-heavy tool responses.
|
|
122
|
-
|
|
123
|
-
<details>
|
|
124
|
-
<summary><strong>Per-repo breakdown — WITH vs WITHOUT (median of 4)</strong></summary>
|
|
125
|
-
|
|
126
|
-
**VS Code** · ~10k files
|
|
127
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
128
|
-
|---|---|---|---|
|
|
129
|
-
| Time | 1m 59s | 2m 13s | 11% faster |
|
|
130
|
-
| File Reads | 0 | 9 | −9 |
|
|
131
|
-
| Grep/Bash | 0 | 11 | −11 |
|
|
132
|
-
| Tool calls | 4 | 21 | 81% fewer |
|
|
133
|
-
| Total tokens | 640k | 1.79M | 64% fewer |
|
|
134
|
-
| Cost | $0.68 | $0.83 | 18% cheaper |
|
|
135
|
-
|
|
136
|
-
**Excalidraw** · ~640 files
|
|
137
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
138
|
-
|---|---|---|---|
|
|
139
|
-
| Time | 1m 32s | 2m 6s | 27% faster |
|
|
140
|
-
| File Reads | 0 | 7 | −7 |
|
|
141
|
-
| Grep/Bash | 1 | 8 | −7 |
|
|
142
|
-
| Tool calls | 9 | 15 | 40% fewer |
|
|
143
|
-
| Total tokens | 1.27M | 1.69M | 25% fewer |
|
|
144
|
-
| Cost | $0.78 | $0.78 | even |
|
|
145
|
-
|
|
146
|
-
**Django** · ~3k files
|
|
147
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
148
|
-
|---|---|---|---|
|
|
149
|
-
| Time | 1m 43s | 1m 58s | 13% faster |
|
|
150
|
-
| File Reads | 0 | 9 | −9 |
|
|
151
|
-
| Grep/Bash | 0 | 5 | −5 |
|
|
152
|
-
| Tool calls | 3 | 13 | 77% fewer |
|
|
153
|
-
| Total tokens | 559k | 1.41M | 60% fewer |
|
|
154
|
-
| Cost | $0.57 | $0.62 | 8% cheaper |
|
|
155
|
-
|
|
156
|
-
**Tokio** · ~790 files
|
|
157
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
158
|
-
|---|---|---|---|
|
|
159
|
-
| Time | 1m 55s | 2m 20s | 18% faster |
|
|
160
|
-
| File Reads | 0 | 8 | −8 |
|
|
161
|
-
| Grep/Bash | 0 | 6 | −6 |
|
|
162
|
-
| Tool calls | 6 | 14 | 57% fewer |
|
|
163
|
-
| Total tokens | 1.08M | 1.73M | 38% fewer |
|
|
164
|
-
| Cost | $0.82 | $0.82 | even |
|
|
165
|
-
|
|
166
|
-
**OkHttp** · ~645 files
|
|
167
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
168
|
-
|---|---|---|---|
|
|
169
|
-
| Time | 1m 1s | 1m 29s | 31% faster |
|
|
170
|
-
| File Reads | 0 | 4 | −4 |
|
|
171
|
-
| Grep/Bash | 2 | 6 | −4 |
|
|
172
|
-
| Tool calls | 5 | 10 | 50% fewer |
|
|
173
|
-
| Total tokens | 502k | 1.10M | 54% fewer |
|
|
174
|
-
| Cost | $0.41 | $0.55 | 25% cheaper |
|
|
175
|
-
|
|
176
|
-
**Gin** · ~110 files
|
|
177
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
178
|
-
|---|---|---|---|
|
|
179
|
-
| Time | 1m 14s | 1m 37s | 24% faster |
|
|
180
|
-
| File Reads | 1 | 6 | −5 |
|
|
181
|
-
| Grep/Bash | 1 | 2 | −1 |
|
|
182
|
-
| Tool calls | 5 | 9 | 44% fewer |
|
|
183
|
-
| Total tokens | 651k | 847k | 23% fewer |
|
|
184
|
-
| Cost | $0.46 | $0.57 | 19% cheaper |
|
|
185
|
-
|
|
186
|
-
**Alamofire** · ~110 files
|
|
187
|
-
| Metric | WITH cg | WITHOUT cg | Δ |
|
|
188
|
-
|---|---|---|---|
|
|
189
|
-
| Time | 1m 35s | 2m 21s | 33% faster |
|
|
190
|
-
| File Reads | 0 | 9 | −9 |
|
|
191
|
-
| Grep/Bash | 0 | 4 | −4 |
|
|
192
|
-
| Tool calls | 5 | 12 | 58% fewer |
|
|
193
|
-
| Total tokens | 766k | 2.10M | 64% fewer |
|
|
194
|
-
| Cost | $0.57 | $0.95 | 40% cheaper |
|
|
195
|
-
|
|
196
|
-
</details>
|
|
197
|
-
|
|
198
|
-
<details>
|
|
199
|
-
<summary><strong>Full benchmark details</strong></summary>
|
|
200
|
-
|
|
201
|
-
**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) 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. Re-validated 2026-06-02 on the current build. These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).
|
|
202
|
-
|
|
203
|
-
**Queries:**
|
|
204
|
-
| Codebase | Query |
|
|
205
|
-
|----------|-------|
|
|
206
|
-
| VS Code | "How does the extension host communicate with the main process?" |
|
|
207
|
-
| Excalidraw | "How does Excalidraw render and update canvas elements?" |
|
|
208
|
-
| Django | "How does Django's ORM build and execute a query from a QuerySet?" |
|
|
209
|
-
| Tokio | "How does tokio schedule and run async tasks on its runtime?" |
|
|
210
|
-
| OkHttp | "How does OkHttp process a request through its interceptor chain?" |
|
|
211
|
-
| Gin | "How does gin route requests through its middleware chain?" |
|
|
212
|
-
| Alamofire | "How does Alamofire build, send, and validate a request?" |
|
|
213
|
-
|
|
214
|
-
**Why CodeGraph wins:** with the index available, the agent answers directly — usually one `codegraph_explore` returns the relevant source — and stops, usually with zero file reads. Without it, the agent 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.
|
|
215
|
-
|
|
216
|
-
</details>
|
|
217
|
-
|
|
218
82
|
---
|
|
219
83
|
|
|
220
|
-
##
|
|
221
|
-
|
|
222
|
-
| | |
|
|
223
|
-
|---|---|
|
|
224
|
-
| **Smart Context Building** | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents |
|
|
225
|
-
| **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 |
|
|
226
|
-
| **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes |
|
|
227
|
-
| **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |
|
|
228
|
-
| **20+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Objective-C, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi |
|
|
229
|
-
| **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 14 frameworks |
|
|
230
|
-
| **Mixed iOS / React Native / Expo** | Closes cross-language flows that static parsing misses: Swift ↔ ObjC bridging, React Native legacy bridge + TurboModules + Fabric view components, native → JS event emitters, Expo Modules |
|
|
231
|
-
| **100% Local** | No data leaves your machine. No API keys. No external services. SQLite database only |
|
|
232
|
-
|
|
233
|
-
<details>
|
|
234
|
-
<summary><strong>How auto-syncing works — and why you don't need to run <code>codegraph sync</code> manually</strong></summary>
|
|
235
|
-
|
|
236
|
-
When your agent (Claude Code, Cursor, Codex, opencode) launches `codegraph serve --mcp`, three layers keep the index in step with your code — and make sure the agent never gets a silent wrong answer in the brief window between an edit and the next sync:
|
|
237
|
-
|
|
238
|
-
1. **File watcher with debounced auto-sync.** A native FSEvents / inotify / ReadDirectoryChangesW watcher captures every source-file create / modify / delete and triggers a re-index after a debounce window (default `2000ms`, tunable via `CODEGRAPH_WATCH_DEBOUNCE_MS`, clamped to `[100ms, 60s]`). Bursts of edits collapse into a single sync.
|
|
239
|
-
|
|
240
|
-
2. **Per-file staleness banner.** During the brief debounce window, MCP tool responses that would reference a still-pending file prepend a `⚠️` banner naming it and telling the agent to `Read` it directly. Pending files NOT referenced by the response surface as a small footer instead. Either way, the agent gets an explicit signal — validated with Claude Code, where the agent literally says "Reading the file directly for the live content" before opening it.
|
|
241
|
-
|
|
242
|
-
3. **Connect-time catch-up.** When the MCP server (re)connects, codegraph runs a fast `(size, mtime)` + content-hash reconciliation against the working tree before answering the first query — so edits made while no MCP server was running (a `git pull` from the terminal, edits from another editor, a previous agent session that exited) get absorbed on the next session's first tool call.
|
|
84
|
+
## 常用命令
|
|
243
85
|
|
|
86
|
+
```bash
|
|
87
|
+
homegraph install # 配置 AI 助手
|
|
88
|
+
homegraph init -i [path] # 初始化并索引项目
|
|
89
|
+
homegraph index [path] # 全量索引（--force 强制重建）
|
|
90
|
+
homegraph sync [path] # 增量同步变更
|
|
91
|
+
homegraph status [path] # 查看索引状态
|
|
92
|
+
homegraph query <关键词> # 搜索符号
|
|
93
|
+
homegraph callers <符号> # 谁调用了它
|
|
94
|
+
homegraph callees <符号> # 它调用了谁
|
|
95
|
+
homegraph impact <符号> # 修改该符号的影响范围
|
|
96
|
+
homegraph serve --mcp # 启动 MCP 服务（一般由 Agent 自动拉起）
|
|
244
97
|
```
|
|
245
|
-
agent writes src/Widget.ts
|
|
246
|
-
→ watcher fires (<100ms)
|
|
247
|
-
→ debounce (default 2s)
|
|
248
|
-
→ sync; Widget.ts is in the index
|
|
249
|
-
→ next agent query sees it
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
**Verify any time** with `codegraph_status` (via MCP) or `codegraph status` (CLI). If anything is pending, you'll see a `### Pending sync:` section naming the files and their edit age.
|
|
253
98
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
→ Full deep-dive in [Guides → Indexing a Project](https://colbymchenry.github.io/codegraph/guides/indexing/#stay-fresh-automatically).
|
|
99
|
+
---
|
|
257
100
|
|
|
258
|
-
|
|
101
|
+
## MCP 工具
|
|
259
102
|
|
|
260
|
-
|
|
103
|
+
Agent 侧工具名前缀为 `homegraph_`：
|
|
261
104
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
|
267
|
-
|
|
268
|
-
|
|
|
269
|
-
|
|
|
270
|
-
|
|
|
271
|
-
| **Express** | `app.get(...)`, `router.post(...)` with middleware chains |
|
|
272
|
-
| **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` |
|
|
273
|
-
| **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |
|
|
274
|
-
| **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |
|
|
275
|
-
| **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=>` syntax |
|
|
276
|
-
| **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
|
|
277
|
-
| **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` |
|
|
278
|
-
| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
|
|
279
|
-
| **ASP.NET** | `[HttpGet("/x")]` attributes on action methods |
|
|
280
|
-
| **Vapor** | `app.get("x", use: handler)` |
|
|
281
|
-
| **React Router** / **SvelteKit** | Route component nodes |
|
|
105
|
+
| 工具 | 用途 |
|
|
106
|
+
|------|------|
|
|
107
|
+
| `homegraph_explore` | 主要工具：一次返回相关符号源码与调用关系 |
|
|
108
|
+
| `homegraph_search` | 按名称快速定位符号 |
|
|
109
|
+
| `homegraph_callers` / `homegraph_callees` | 查看调用方 / 被调用方 |
|
|
110
|
+
| `homegraph_impact` | 变更影响分析 |
|
|
111
|
+
| `homegraph_node` | 单个符号的完整源码与上下文 |
|
|
112
|
+
| `homegraph_files` | 已索引的文件结构 |
|
|
113
|
+
| `homegraph_status` | 索引健康状态 |
|
|
282
114
|
|
|
283
115
|
---
|
|
284
116
|
|
|
285
|
-
##
|
|
117
|
+
## 支持的语言
|
|
286
118
|
|
|
287
|
-
|
|
119
|
+
继承 CodeGraph 的多语言 tree-sitter 解析，包括但不限于：
|
|
288
120
|
|
|
289
|
-
|
|
290
|
-
|---|---|---|---|
|
|
291
|
-
| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC selector `-fooWithBar:` | `@objc` auto-bridging rules (including init/property/protocol forms) + Cocoa preposition prefixes (`With`/`For`/`By`/`In`/`On`/`At`/…) |
|
|
292
|
-
| **ObjC → Swift** | ObjC `[obj fooWithBar:]` | Swift `@objc func foo(bar:)` | Reverse-bridge name candidates; verifies `@objc` exposure from source |
|
|
293
|
-
| **React Native legacy bridge** | JS `NativeModules.X.fn(...)` | ObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` | Parses macro/annotation declarations to build a JS-name → native-method map |
|
|
294
|
-
| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | Native impl matching the Codegen spec | Treats the `Native<X>.ts` spec interface as ground truth |
|
|
295
|
-
| **RN native → JS events** | JS `new NativeEventEmitter(...).addListener('e', cb)` | ObjC `[self sendEventWithName:@"e" body:...]` · Swift `sendEvent(withName: "e", ...)` · Java/Kotlin `.emit("e", ...)` | Synthesized cross-language event channel keyed by literal event name |
|
|
296
|
-
| **Expo Modules** | JS `requireNativeModule('X').fn(...)` | Swift / Kotlin `Module { Name("X"); AsyncFunction("fn") { ... } }` | Parses the Expo DSL literals; synthetic method nodes resolve via existing name-match |
|
|
297
|
-
| **Fabric view components** | JSX `<MyView prop={v}/>` | TS Codegen spec + native impl class | Spec → `component` node; convention-based name+suffix lookup (`View`/`ComponentView`/`Manager`/`ViewManager`) bridges to native |
|
|
298
|
-
| **Legacy Paper view managers** | JSX `<MyView prop={v}/>` | ObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` | Same as Fabric — Paper-era declarations also produce `component` + `property` nodes |
|
|
121
|
+
TypeScript / JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C / C++、Objective-C、Swift、Kotlin、Scala、Dart、Lua、Luau、Svelte、Vue、Liquid、Pascal / Delphi 等。
|
|
299
122
|
|
|
300
|
-
**
|
|
123
|
+
**HomeGraph 新增：**
|
|
301
124
|
|
|
302
|
-
|
|
|
303
|
-
|
|
304
|
-
|
|
|
305
|
-
| RN legacy bridge | [AsyncStorage](https://github.com/react-native-async-storage/async-storage) | [react-native-svg](https://github.com/software-mansion/react-native-svg) | [react-native-firebase](https://github.com/invertase/react-native-firebase) |
|
|
306
|
-
| RN native → JS events | [RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service) | — | react-native-firebase |
|
|
307
|
-
| Expo Modules | expo-haptics | expo-camera | expo SDK sweep (7 packages) |
|
|
308
|
-
| Fabric / Paper views | [react-native-segmented-control](https://github.com/react-native-segmented-control/segmented-control) | [react-native-screens](https://github.com/software-mansion/react-native-screens) | [react-native-skia](https://github.com/Shopify/react-native-skia) |
|
|
309
|
-
|
|
310
|
-
Each bridge emits edges tagged `provenance:'heuristic'` with `metadata.synthesizedBy:` set to a stable channel name (e.g. `swift-objc-bridge`, `rn-event-channel`, `fabric-native-impl`, `expo-module-extract`), so the agent can tell at a glance how a hop got into the graph.
|
|
125
|
+
| 语言 | 扩展名 | 说明 |
|
|
126
|
+
|------|--------|------|
|
|
127
|
+
| **ArkTS** | `.ets` 等 | 基于 arkanalyzer，支持 HarmonyOS 工程的类、方法、导入与调用关系提取 |
|
|
311
128
|
|
|
312
129
|
---
|
|
313
130
|
|
|
314
|
-
##
|
|
315
|
-
|
|
316
|
-
### 1. Run the Installer
|
|
317
|
-
|
|
318
|
-
```bash
|
|
319
|
-
npx @colbymchenry/codegraph
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
The installer will:
|
|
323
|
-
- Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, **Kiro**
|
|
324
|
-
- Prompt to install `codegraph` on your PATH (so agents can launch the MCP server)
|
|
325
|
-
- Ask whether configs apply to all your projects or just this one
|
|
326
|
-
- Write each chosen agent's MCP server config (the codegraph usage guide is delivered by the MCP server itself, so no instructions file is added to `CLAUDE.md` / `AGENTS.md` / etc.)
|
|
327
|
-
- Set up auto-allow permissions when Claude Code is one of the targets
|
|
328
|
-
- Initialize your current project (local installs only)
|
|
131
|
+
## 从源码构建
|
|
329
132
|
|
|
330
|
-
|
|
133
|
+
适用于开发或二次修改：
|
|
331
134
|
|
|
332
135
|
```bash
|
|
333
|
-
|
|
334
|
-
codegraph
|
|
335
|
-
|
|
336
|
-
|
|
136
|
+
git clone <your-repo-url>
|
|
137
|
+
cd codegraph # 仓库目录名可仍为 codegraph
|
|
138
|
+
npm install
|
|
139
|
+
npm run build
|
|
140
|
+
npm run cli -- --help # 或直接：node dist/bin/homegraph.js --help
|
|
141
|
+
npm test # 运行测试
|
|
337
142
|
```
|
|
338
143
|
|
|
339
|
-
|
|
340
|
-
|---|---|---|
|
|
341
|
-
| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,...`) | prompt |
|
|
342
|
-
| `--location` | `global`, `local` | prompt |
|
|
343
|
-
| `--yes` | (boolean) | prompt every step |
|
|
344
|
-
| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
|
|
345
|
-
| `--print-config <id>` | dump snippet for one agent and exit | — |
|
|
346
|
-
|
|
347
|
-
### 2. Restart Your Agent
|
|
348
|
-
|
|
349
|
-
Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.
|
|
350
|
-
|
|
351
|
-
### 3. Initialize Projects
|
|
144
|
+
本地调试 CLI：
|
|
352
145
|
|
|
353
146
|
```bash
|
|
354
|
-
|
|
355
|
-
|
|
147
|
+
npm run cli
|
|
148
|
+
# 等价于 npm run build && node dist/bin/homegraph.js
|
|
356
149
|
```
|
|
357
150
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
|
|
151
|
+
---
|
|
361
152
|
|
|
362
|
-
|
|
363
|
-
<summary><strong>Manual Setup (Alternative)</strong></summary>
|
|
153
|
+
## 手动配置 MCP（可选）
|
|
364
154
|
|
|
365
|
-
|
|
366
|
-
```bash
|
|
367
|
-
npm install -g @colbymchenry/codegraph
|
|
368
|
-
```
|
|
155
|
+
以 Claude Code 为例，在 `~/.claude.json` 中添加：
|
|
369
156
|
|
|
370
|
-
**Add to `~/.claude.json`:**
|
|
371
157
|
```json
|
|
372
158
|
{
|
|
373
159
|
"mcpServers": {
|
|
374
|
-
"
|
|
160
|
+
"homegraph": {
|
|
375
161
|
"type": "stdio",
|
|
376
|
-
"command": "
|
|
162
|
+
"command": "homegraph",
|
|
377
163
|
"args": ["serve", "--mcp"]
|
|
378
164
|
}
|
|
379
165
|
}
|
|
380
166
|
}
|
|
381
167
|
```
|
|
382
168
|
|
|
383
|
-
|
|
384
|
-
```json
|
|
385
|
-
{
|
|
386
|
-
"permissions": {
|
|
387
|
-
"allow": [
|
|
388
|
-
"mcp__codegraph__codegraph_search",
|
|
389
|
-
"mcp__codegraph__codegraph_explore",
|
|
390
|
-
"mcp__codegraph__codegraph_callers",
|
|
391
|
-
"mcp__codegraph__codegraph_callees",
|
|
392
|
-
"mcp__codegraph__codegraph_impact",
|
|
393
|
-
"mcp__codegraph__codegraph_node",
|
|
394
|
-
"mcp__codegraph__codegraph_status",
|
|
395
|
-
"mcp__codegraph__codegraph_files"
|
|
396
|
-
]
|
|
397
|
-
}
|
|
398
|
-
}
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
</details>
|
|
402
|
-
|
|
403
|
-
<details>
|
|
404
|
-
<summary><strong>Agent Tool Guidance</strong></summary>
|
|
405
|
-
|
|
406
|
-
CodeGraph's MCP server delivers its usage guidance to your agent **automatically**, in the MCP `initialize` response — there's no instructions file to manage and nothing is added to your `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`. In short, it tells the agent to:
|
|
407
|
-
|
|
408
|
-
- **Answer structural questions directly with CodeGraph** — it *is* the pre-built index, so a grep/read loop just repeats work it already did. Treat the returned source as already read.
|
|
409
|
-
- **Pick the tool by intent:** `codegraph_explore` for almost anything — "how does X work", a flow/"how does X reach Y", or surveying an area (one call returns the relevant symbols' source grouped by file); `codegraph_search` to just locate a symbol; `codegraph_callers`/`codegraph_callees` to walk call flow; `codegraph_impact` before editing; `codegraph_node` for one specific symbol's full source (it returns every overload for an ambiguous name).
|
|
410
|
-
- **Trust the results — don't re-verify with grep**, and check the staleness banner after edits.
|
|
411
|
-
- If `.codegraph/` doesn't exist yet, offer to run `codegraph init -i`.
|
|
412
|
-
|
|
413
|
-
The exact text is `src/mcp/server-instructions.ts` — the single source of truth.
|
|
414
|
-
|
|
415
|
-
</details>
|
|
416
|
-
|
|
417
|
-
---
|
|
418
|
-
|
|
419
|
-
## How It Works
|
|
420
|
-
|
|
421
|
-
```
|
|
422
|
-
┌───────────────────────────────────────────────────────────────────┐
|
|
423
|
-
│ Claude Code │
|
|
424
|
-
│ │
|
|
425
|
-
│ "How does a request reach the database?" │
|
|
426
|
-
│ calls CodeGraph tools directly — no Explore sub-agent │
|
|
427
|
-
│ │ │
|
|
428
|
-
└─────────────────────────────────┬─────────────────────────────────┘
|
|
429
|
-
│
|
|
430
|
-
▼
|
|
431
|
-
┌───────────────────────────────────────────────────────────────────┐
|
|
432
|
-
│ CodeGraph MCP Server │
|
|
433
|
-
│ │
|
|
434
|
-
│ explore · search · callers · callees · impact · node │
|
|
435
|
-
│ │ │
|
|
436
|
-
│ ▼ │
|
|
437
|
-
│ SQLite knowledge graph │
|
|
438
|
-
│ symbols · edges · files · FTS5 full-text search │
|
|
439
|
-
└───────────────────────────────────────────────────────────────────┘
|
|
440
|
-
```
|
|
441
|
-
|
|
442
|
-
1. **Extraction** — [tree-sitter](https://tree-sitter.github.io/) parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).
|
|
443
|
-
|
|
444
|
-
2. **Storage** — Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search.
|
|
445
|
-
|
|
446
|
-
3. **Resolution** — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.
|
|
447
|
-
|
|
448
|
-
4. **Auto-Sync** — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed.
|
|
449
|
-
|
|
450
|
-
---
|
|
451
|
-
|
|
452
|
-
## CLI Reference
|
|
453
|
-
|
|
454
|
-
```bash
|
|
455
|
-
codegraph # Run interactive installer
|
|
456
|
-
codegraph install # Run installer (explicit)
|
|
457
|
-
codegraph uninstall # Remove CodeGraph from your agents (inverse of install)
|
|
458
|
-
codegraph init [path] # Initialize in a project (--index to also index)
|
|
459
|
-
codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt)
|
|
460
|
-
codegraph index [path] # Full index (--force to re-index, --quiet for less output)
|
|
461
|
-
codegraph sync [path] # Incremental update
|
|
462
|
-
codegraph status [path] # Show statistics
|
|
463
|
-
codegraph query <search> # Search symbols (--kind, --limit, --json)
|
|
464
|
-
codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json)
|
|
465
|
-
codegraph callers <symbol> # Find what calls a function/method (--limit, --json)
|
|
466
|
-
codegraph callees <symbol> # Find what a function/method calls (--limit, --json)
|
|
467
|
-
codegraph impact <symbol> # Analyze what code is affected by changing a symbol (--depth, --json)
|
|
468
|
-
codegraph affected [files...] # Find test files affected by changes (see below)
|
|
469
|
-
codegraph serve --mcp # Start MCP server
|
|
470
|
-
codegraph upgrade [version] # Update to the latest release (--check, --force)
|
|
471
|
-
```
|
|
472
|
-
|
|
473
|
-
### `codegraph affected`
|
|
474
|
-
|
|
475
|
-
Traces import dependencies transitively to find which test files are affected by changed source files.
|
|
476
|
-
|
|
477
|
-
```bash
|
|
478
|
-
codegraph affected src/utils.ts src/api.ts # Pass files as arguments
|
|
479
|
-
git diff --name-only | codegraph affected --stdin # Pipe from git diff
|
|
480
|
-
codegraph affected src/auth.ts --filter "e2e/*" # Custom test file pattern
|
|
481
|
-
```
|
|
482
|
-
|
|
483
|
-
| Option | Description | Default |
|
|
484
|
-
|--------|-------------|---------|
|
|
485
|
-
| `--stdin` | Read file list from stdin | `false` |
|
|
486
|
-
| `-d, --depth <n>` | Max dependency traversal depth | `5` |
|
|
487
|
-
| `-f, --filter <glob>` | Custom glob to identify test files | auto-detect |
|
|
488
|
-
| `-j, --json` | Output as JSON | `false` |
|
|
489
|
-
| `-q, --quiet` | Output file paths only | `false` |
|
|
490
|
-
|
|
491
|
-
**CI/hook example:**
|
|
492
|
-
|
|
493
|
-
```bash
|
|
494
|
-
#!/usr/bin/env bash
|
|
495
|
-
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
|
|
496
|
-
if [ -n "$AFFECTED" ]; then
|
|
497
|
-
npx vitest run $AFFECTED
|
|
498
|
-
fi
|
|
499
|
-
```
|
|
169
|
+
Cursor 等项目级配置写入 `./.cursor/mcp.json`，格式相同。推荐使用 `homegraph install` 自动完成。
|
|
500
170
|
|
|
501
171
|
---
|
|
502
172
|
|
|
503
|
-
##
|
|
173
|
+
## 与 CodeGraph 的关系
|
|
504
174
|
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
|
508
|
-
|
|
509
|
-
|
|
|
510
|
-
|
|
|
511
|
-
| `codegraph_callers` | Find what calls a function |
|
|
512
|
-
| `codegraph_callees` | Find what a function calls |
|
|
513
|
-
| `codegraph_impact` | Analyze what code is affected by changing a symbol |
|
|
514
|
-
| `codegraph_node` | Get one specific symbol's details + full source (returns every overload for an ambiguous name) |
|
|
515
|
-
| `codegraph_files` | Get indexed file structure (faster than filesystem scanning) |
|
|
516
|
-
| `codegraph_status` | Check index health and statistics |
|
|
175
|
+
| 项目 | 说明 |
|
|
176
|
+
|------|------|
|
|
177
|
+
| 上游 | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) |
|
|
178
|
+
| 包名 / CLI | `homegraph`（npm：`npm install -g homegraph`） |
|
|
179
|
+
| 数据目录 | `.homegraph/`（与上游 `.codegraph/` 独立，可并存） |
|
|
180
|
+
| 主要差异 | 新增 **ArkTS** 语言支持与相关索引逻辑 |
|
|
517
181
|
|
|
518
182
|
---
|
|
519
183
|
|
|
520
|
-
##
|
|
521
|
-
|
|
522
|
-
CodeGraph can be embedded directly. The npm package re-exports its programmatic
|
|
523
|
-
API, so both `import` and `require` resolve the `CodeGraph` class in your own
|
|
524
|
-
process — handy for embedding it in an app (e.g. an Electron main process).
|
|
525
|
-
|
|
526
|
-
```typescript
|
|
527
|
-
import CodeGraph from '@colbymchenry/codegraph';
|
|
528
|
-
// CommonJS works too:
|
|
529
|
-
// const { CodeGraph } = require('@colbymchenry/codegraph');
|
|
184
|
+
## 环境要求
|
|
530
185
|
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
await cg.indexAll({
|
|
535
|
-
onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
|
|
536
|
-
});
|
|
537
|
-
|
|
538
|
-
const results = cg.searchNodes('UserService');
|
|
539
|
-
const callers = cg.getCallers(results[0].node.id);
|
|
540
|
-
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
|
|
541
|
-
const impact = cg.getImpactRadius(results[0].node.id, 2);
|
|
542
|
-
|
|
543
|
-
cg.watch(); // auto-sync on file changes
|
|
544
|
-
cg.unwatch(); // stop watching
|
|
545
|
-
cg.close();
|
|
546
|
-
```
|
|
547
|
-
|
|
548
|
-
Lower-level building blocks are exported from the same entry point for callers
|
|
549
|
-
that drive the graph directly: `DatabaseConnection`, `QueryBuilder`,
|
|
550
|
-
`getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, and `FileLock`.
|
|
551
|
-
|
|
552
|
-
**Embedding requirements**
|
|
553
|
-
|
|
554
|
-
- Install from npm (`npm i @colbymchenry/codegraph`) so the matching
|
|
555
|
-
per-platform package — which carries the compiled library and its
|
|
556
|
-
dependencies — is fetched alongside the shim.
|
|
557
|
-
- The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in
|
|
558
|
-
`node:sqlite` (Electron qualifies when its bundled Node is 22.5+). The CLI and
|
|
559
|
-
MCP server are unaffected — they run on the self-contained bundled runtime.
|
|
560
|
-
- TypeScript types ship with the package. As with any Node-targeting library,
|
|
561
|
-
keep `@types/node` available and `skipLibCheck: true` (the common default).
|
|
562
|
-
|
|
563
|
-
---
|
|
564
|
-
|
|
565
|
-
## Configuration
|
|
566
|
-
|
|
567
|
-
There isn't any — CodeGraph is zero-config, with **no config file** to write or
|
|
568
|
-
keep in sync. Language support is automatic from the file extension; there's
|
|
569
|
-
nothing to wire up per language.
|
|
570
|
-
|
|
571
|
-
What it skips out of the box:
|
|
572
|
-
|
|
573
|
-
- **Dependency, build, and cache directories** — `node_modules`, `vendor`,
|
|
574
|
-
`dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every
|
|
575
|
-
[supported stack](#supported-languages) — so the graph is your code, not
|
|
576
|
-
third-party noise. This holds even with no `.gitignore`.
|
|
577
|
-
- **Anything in your `.gitignore`** — honored in git repos via git, and in
|
|
578
|
-
non-git projects by reading `.gitignore` directly (root and nested).
|
|
579
|
-
- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.
|
|
580
|
-
|
|
581
|
-
To keep something else out, add it to `.gitignore`. To pull a default-excluded
|
|
582
|
-
directory back **in** (say you really do want a vendored dependency indexed),
|
|
583
|
-
add a negation — `!vendor/`. The defaults apply uniformly, so committing a
|
|
584
|
-
dependency or build directory doesn't force it into the graph; the `.gitignore`
|
|
585
|
-
negation is the explicit opt-in.
|
|
586
|
-
|
|
587
|
-
## Supported Platforms
|
|
588
|
-
|
|
589
|
-
Every release ships a self-contained build (bundled Node runtime — nothing to
|
|
590
|
-
compile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):
|
|
591
|
-
|
|
592
|
-
| Platform | Architectures | Install |
|
|
593
|
-
|----------|---------------|---------|
|
|
594
|
-
| Windows | x64, arm64 | PowerShell installer or npm |
|
|
595
|
-
| macOS | x64, arm64 | shell installer or npm |
|
|
596
|
-
| Linux | x64, arm64 | shell installer or npm |
|
|
597
|
-
|
|
598
|
-
See [Get Started](#get-started) for the one-line install commands.
|
|
599
|
-
|
|
600
|
-
## Supported Agents
|
|
601
|
-
|
|
602
|
-
The interactive installer auto-detects and configures each of these — wiring up
|
|
603
|
-
the MCP server (which delivers its own usage guidance, so no instructions file
|
|
604
|
-
is written):
|
|
605
|
-
|
|
606
|
-
- **Claude Code**
|
|
607
|
-
- **Cursor**
|
|
608
|
-
- **Codex CLI**
|
|
609
|
-
- **opencode**
|
|
610
|
-
- **Hermes Agent**
|
|
611
|
-
- **Gemini CLI**
|
|
612
|
-
- **Antigravity IDE**
|
|
613
|
-
- **Kiro**
|
|
614
|
-
|
|
615
|
-
## Supported Languages
|
|
616
|
-
|
|
617
|
-
| Language | Extension | Status |
|
|
618
|
-
|----------|-----------|--------|
|
|
619
|
-
| TypeScript | `.ts`, `.tsx` | Full support |
|
|
620
|
-
| JavaScript | `.js`, `.jsx`, `.mjs` | Full support |
|
|
621
|
-
| Python | `.py` | Full support |
|
|
622
|
-
| Go | `.go` | Full support |
|
|
623
|
-
| Rust | `.rs` | Full support |
|
|
624
|
-
| Java | `.java` | Full support |
|
|
625
|
-
| C# | `.cs` | Full support |
|
|
626
|
-
| PHP | `.php` | Full support |
|
|
627
|
-
| Ruby | `.rb` | Full support |
|
|
628
|
-
| C | `.c`, `.h` | Full support |
|
|
629
|
-
| C++ | `.cpp`, `.hpp`, `.cc` | Full support |
|
|
630
|
-
| Objective-C | `.m`, `.mm`, `.h` | Partial support (classes, protocols, methods, `@property`, `#import`, message sends; `.mm` ObjC++ may parse incompletely) |
|
|
631
|
-
| Swift | `.swift` | Full support |
|
|
632
|
-
| Kotlin | `.kt`, `.kts` | Full support |
|
|
633
|
-
| Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) |
|
|
634
|
-
| Dart | `.dart` | Full support |
|
|
635
|
-
| Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |
|
|
636
|
-
| Vue | `.vue` | Full support (script + script-setup extraction, Nuxt page/API/middleware routes) |
|
|
637
|
-
| Liquid | `.liquid` | Full support |
|
|
638
|
-
| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX form files) |
|
|
639
|
-
| Lua | `.lua` | Full support (functions, methods with receivers, local variables, `require` imports, call edges) |
|
|
640
|
-
| Luau | `.luau` | Full support (everything in Lua, plus `type`/`export type` aliases, typed signatures, and Roblox instance-path `require`) |
|
|
641
|
-
|
|
642
|
-
## Measured cross-file coverage
|
|
643
|
-
|
|
644
|
-
Impact and blast-radius queries are only as good as the dependency graph behind them, so coverage is measured rather than asserted. **Fair coverage** = the share of symbol-bearing source files that have at least one *resolved cross-file dependent* — something that imports, calls, references, or (through a framework convention) routes to them — on a real-world benchmark repo per language. The residual is always a genuine static-analysis frontier (runtime dynamic dispatch, reflection / DI containers, framework-convention entry points, vendored third-party code), never hidden by gaming the denominator.
|
|
645
|
-
|
|
646
|
-
| Language | Benchmark repo | Coverage |
|
|
647
|
-
|---|---|---|
|
|
648
|
-
| TypeScript / JavaScript | this repo | 95.8% |
|
|
649
|
-
| Python | psf/requests | 100% |
|
|
650
|
-
| Go | gin-gonic/gin | 96.6% |
|
|
651
|
-
| Rust | BurntSushi/ripgrep | 86.7% |
|
|
652
|
-
| Java | google/gson | 93.3% |
|
|
653
|
-
| C# | jbogard/MediatR | 85.2% |
|
|
654
|
-
| PHP | guzzle/guzzle | 100% |
|
|
655
|
-
| Ruby | sidekiq/sidekiq | 100% |
|
|
656
|
-
| C | redis/redis | 92.2% |
|
|
657
|
-
| C++ | google/leveldb | 94.8% |
|
|
658
|
-
| Objective-C | SDWebImage | 91.6% |
|
|
659
|
-
| Swift | Alamofire | 95.3% |
|
|
660
|
-
| Kotlin | square/okhttp | 96.2% |
|
|
661
|
-
| Scala | gatling/gatling | 91.2% |
|
|
662
|
-
| Dart | flutter/packages | 92.4% |
|
|
663
|
-
| Svelte / SvelteKit | sveltejs/realworld | 100% |
|
|
664
|
-
| Vue / Nuxt | nuxt/movies | 93.5% |
|
|
665
|
-
| Lua | nvim-telescope/telescope.nvim | 84.2% |
|
|
666
|
-
| Luau | dphfox/Fusion | 92.2% |
|
|
667
|
-
| Liquid | Shopify/dawn | 73.8% |
|
|
668
|
-
| Pascal / Delphi | PascalCoin | 75.7% |
|
|
669
|
-
|
|
670
|
-
Framework routing is validated the same way, on a canonical app per framework: Express 100%, FastAPI 98%, Flask 100%, NestJS 96.8%, Gin 96.5%, Axum 100%, Rocket 93.8%, Vapor 100%, Laravel 92%, Rails 89.6%, React Router 100% — and the convention/reflection-heavy ones at their honest static-analysis ceiling: ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Django 74.1%.
|
|
671
|
-
|
|
672
|
-
## Troubleshooting
|
|
673
|
-
|
|
674
|
-
**"CodeGraph not initialized"** — Run `codegraph init` in your project directory first.
|
|
675
|
-
|
|
676
|
-
**Indexing is slow** — Check that `node_modules` and other large directories are excluded. Use `--quiet` to reduce output overhead.
|
|
677
|
-
|
|
678
|
-
**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:
|
|
679
|
-
|
|
680
|
-
- **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`.
|
|
681
|
-
- **`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.
|
|
682
|
-
|
|
683
|
-
**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.
|
|
684
|
-
|
|
685
|
-
**Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph sync` manually if needed. Check that the file's language is supported and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`).
|
|
686
|
-
|
|
687
|
-
## Star History
|
|
688
|
-
|
|
689
|
-
<a href="https://www.star-history.com/?repos=colbymchenry%2Fcodegraph&type=date&legend=top-left">
|
|
690
|
-
<picture>
|
|
691
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&theme=dark&legend=top-left" />
|
|
692
|
-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&legend=top-left" />
|
|
693
|
-
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&legend=top-left" />
|
|
694
|
-
</picture>
|
|
695
|
-
</a>
|
|
696
|
-
|
|
697
|
-
## License
|
|
698
|
-
|
|
699
|
-
MIT
|
|
186
|
+
- Node.js **20.x – 24.x**（见 `package.json` 的 `engines`）
|
|
187
|
+
- 首次索引时会对项目源码做 AST 解析，大型仓库首次 `init -i` 可能需要数分钟
|
|
700
188
|
|
|
701
189
|
---
|
|
702
190
|
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro**
|
|
706
|
-
|
|
707
|
-
[Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues)
|
|
191
|
+
## 许可证
|
|
708
192
|
|
|
709
|
-
|
|
193
|
+
MIT — 基于 CodeGraph（MIT）二次开发。
|
package/package.json
CHANGED