## CodeGraph ArkTS Fork
This repository publishes the ArkTS / HarmonyOS / ArkUI fork of CodeGraph as:
```bash
@agentllm/codegraph-arkts
```
The CLI name stays:
```bash
codegraph
```
Use this package if you want first-class ArkTS `.ets` support, HarmonyOS / ArkUI-aware retrieval, MCP-ready semantic code intelligence, and a low-noise CodeGraph surface for LLM agents working on declarative UI codebases. Do not install the upstream `@colbymchenry/codegraph` package if your target is this fork's ArkTS behavior.
Search terms this fork is meant to satisfy:
- ArkTS code intelligence
- HarmonyOS code graph
- ArkUI semantic retrieval
- declarative UI agent retrieval
- MCP code intelligence for Claude Code / Codex CLI / Cursor
- code navigation for ArkTS, HarmonyOS, and mixed ArkTS -> TS -> Rust / C++ projects
What this fork is:
- an upstream-first CodeGraph fork for ArkTS / HarmonyOS repositories, maintained as a narrow replayable patch stack where possible
- an ArkTS-first extraction path backed by `ArkAnalyzer`
- an ArkUI / HarmonyOS semantic layer that raises the quality of retrieval on declarative UI projects
- an LLM-first retrieval surface tuned for planner, coder, reviewer, architect, and diagnose workflows
Why this fork exists:
- Declarative UI is hard for LLMs in general, not just in ArkUI: Compose and SwiftUI have the same pattern of state-driven recomposition, hidden ownership, and indirect navigation
- In declarative UI systems, one feature is often split across UI builders, state updates, navigation, lifecycle hooks, and bridge layers
- Common failure modes are simple: the model finds the page shell but not the handler, finds the click handler but not the state object, finds the state write but not the reader, or finds the UI code but not the bridge target
- Without framework-aware retrieval, an LLM often has to do many rounds of grep/read and can still miss the page, component, state object, or handler that is actually responsible for the feature
- In ArkUI, these problems show up often around `@Builder`, state decorators, navigation, lifecycle hooks, and mixed-language bridge paths
- This fork makes those app-level signals easier to recover from the same shared CodeGraph surfaces instead of requiring a separate ArkUI-only tool family
What this fork adds:
- Language layer
- first-class ArkTS `.ets` extraction
- `ArkAnalyzer` as the ArkTS fact source
- Framework and app layer
- HarmonyOS Stage model support for abilities, extensions, forms/cards, builders, decorators, and `module.json5` linkage
- ArkUI synthesized execution-edge recovery for `trace` and navigation
- ArkTS -> TS -> Rust / C++ bridge visibility
- Agent and release layer
- LLM-first `codegraph_context(mode='task')`
- pack/install/MCP hardening and release-grade verifier coverage
What different roles usually need:
- planner: find the page, component, state object, or handler that actually owns the feature, plus the main flow and navigation boundary
- coder: find the edit entry, downstream consumer, and bridge target
- reviewer: show the impact boundary, V1/V2 mixing risk, and deprecated API replacement
- architect: see the real app boundary, bridge shape, and layering hotspots
- diagnose: show the source of truth, stale state path, and lifecycle gap
What `codegraph_context(mode='task')` is for:
- It is the fork's low-noise first-hop context surface for implementation work
- It gives an LLM a useful starting slice before broader exploration or explicit `trace`
- It is meant to cut wasted rounds when the first question is "which page, component, state object, or handler actually owns this feature?"
Recommended agent defaults:
- Use `codegraph_context(mode='task')` as the default first hop for implementation, debugging, and change tasks where the agent needs the real owner, edit entry, state object, or bridge target
- Use plain `codegraph_context` for broader orientation, architecture, or subsystem understanding where a wider structural picture matters more than a narrow first hop
- After the first hop, ask only one structural follow-up for the remaining uncertainty: `trace` for path questions, `node` for symbol/source questions, `callers` / `callees` / `impact` for seam and blast-radius questions
- Use `rg`, grep, or direct file reads only for exact literals, resource keys, visible strings, or after the structural path is already narrowed
- Stop retrieval when the agent has enough evidence for target, owner, chain, and boundary; do not keep expanding context "just in case"
- Do not use CodeGraph like a keyword grep loop. Use it to narrow the decision space first, then confirm precise facts
Role defaults:
- planner: start with `codegraph_context(mode='task')`, recover the real owner and boundary, then use at most one structural follow-up before writing the plan
- coder: consume the plan anchors first, use `node` / `trace` only to confirm the local seam, and avoid reopening broad exploration unless the plan is contradicted
Copy-paste protocol for agent instructions:
```md
## CodeGraph Retrieval Default
- implementation / debugging / change tasks: start with `codegraph_context(mode='task')`
- broad architecture / subsystem orientation: start with plain `codegraph_context`
- after the first hop, allow only one structural follow-up for the main remaining uncertainty:
- `trace` for path / flow uncertainty
- `node` for symbol / source uncertainty
- `callers` / `callees` / `impact` for seam / blast-radius uncertainty
- use `rg` / grep / direct file reads only for exact literals, resource keys, visible strings, or after the structural path is already narrowed
- stop when target, owner, chain, and boundary are sufficient
- do not use CodeGraph as a keyword grep loop; use it to narrow the decision space first
```
Short prompt form:
```text
Use CodeGraph structurally, not as grep.
For implementation, debugging, or change tasks:
1. Start with codegraph_context(mode="task")
2. Ask at most one structural follow-up:
- trace for path
- node for symbol/source
- callers/callees/impact for seam or blast radius
3. Use rg/read only for exact literals or after structural narrowing
4. Stop when target, owner, chain, and boundary are sufficient
```
Boundaries and non-goals:
- this fork improves project understanding for ArkTS / ArkUI / HarmonyOS codebases, but it is not a full runtime execution model
- `Want` / IPC visibility is structure-aware retrieval support, not a full cross-process propagation graph
- it is not a second planner: the goal is to make shared `context`, `trace`, and `impact` materially more useful to an agent
- the long-term direction remains upstream-first maintenance, with ArkTS / ArkUI additions isolated where possible behind shared CodeGraph surfaces
**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.
Get early beta access to the hosted product · getcodegraph.com
**Upgrade any time** with `codegraph upgrade` — it detects how you installed (bundle, npm, or npx) and updates in place. npm installs stay on this fork package; bundle installs follow the installer release channel. Add `--check` to see if an update is available, or `codegraph upgrade ` to pin one.
### 2. Wire up your agent(s)
- adds ArkTS and HarmonyOS structure as first-class indexable facts
- adds ArkUI-aware navigation and synthesized execution edges where plain calls are not enough
- makes mixed-language bridge paths visible across ArkTS, TS, Rust, and C++
- hardens packaging, install, and MCP usage so the ArkTS toolchain is usable out of the box
Current and future backend plan:
- today the ArkTS backend is still powered by `ArkAnalyzer`
- if upstream lands `tree-sitter-arkts`, this fork is intended to move the language backend toward that base while keeping the ArkUI/HarmonyOS semantic layer
- the long-term goal is upstream-first maintenance: keep the fork as a patch stack where possible, and isolate framework-specific additions behind adapters
Chinese quickstart:
- [README.zh-CN.md](./README.zh-CN.md)
## Get Started
Install with npm:
```bash
npx @agentllm/codegraph-arkts
# or
npm i -g @agentllm/codegraph-arkts
```
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.
### Initialize Projects
```bash
cd your-project
codegraph init -i
```
### Uninstall
Changed your mind? One command removes CodeGraph from every agent it configured:
```bash
codegraph uninstall
```
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.
---
## Why CodeGraph?
When Claude Code explores a codebase, it spawns **Explore agents** that scan files with grep, glob, and Read — consuming tokens on every tool call.
**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.
### Benchmark Results
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 **v0.9.4** (2026-05-24)._
> **Average: 35% cheaper · 57% fewer tokens · 46% faster · 71% fewer tool calls**
| Codebase | Language | Cost | Tokens | Time | Tool calls |
|----------|----------|------|--------|------|------------|
| **VS Code** | TypeScript · ~10k files | 26% cheaper | 78% fewer | 52% faster | 85% fewer |
| **Excalidraw** | TypeScript · ~640 | 52% cheaper | 90% fewer | 73% faster | 96% fewer |
| **Django** | Python · ~3k | 12% cheaper | 36% fewer | 19% faster | 53% fewer |
| **Tokio** | Rust · ~790 | 82% cheaper | 86% fewer | 71% faster | 92% fewer |
| **OkHttp** | Java · ~645 | 2% cheaper | 13% fewer | 31% faster | 45% fewer |
| **Gin** | Go · ~110 | 21% cheaper | 34% fewer | 27% faster | 40% fewer |
| **Alamofire** | Swift · ~110 | 47% cheaper | 64% fewer | 48% faster | 83% fewer |
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.
Full benchmark details
**Methodology.** Each arm is `claude -p` (Claude Opus 4.7) 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 on codegraph **v0.9.4** (2026-05-24); 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. Tokio's without-arm hit $2.41/3m one batch).
**Queries:**
| Codebase | Query |
|----------|-------|
| VS Code | "How does the extension host communicate with the main process?" |
| Excalidraw | "How does Excalidraw render and update canvas elements?" |
| Django | "How does Django's ORM build and execute a query from a QuerySet?" |
| Tokio | "How does tokio schedule and run async tasks on its runtime?" |
| OkHttp | "How does OkHttp process a request through its interceptor chain?" |
| Gin | "How does gin route requests through its middleware chain?" |
| Alamofire | "How does Alamofire build, send, and validate a request?" |
**Raw medians — WITH → WITHOUT:**
| Codebase | Cost | Tokens | Time | Tool calls |
|----------|------|--------|------|------------|
| VS Code | $0.60 → $0.80 | 601k → 2.8M | 1m 10s → 2m 26s | 8 → 55 |
| Excalidraw | $0.43 → $0.90 | 344k → 3.5M | 48s → 2m 58s | 3 → 79 |
| Django | $0.59 → $0.67 | 739k → 1.2M | 1m 19s → 1m 38s | 9 → 19 |
| Tokio | $0.42 → $2.41 | 379k → 2.6M | 53s → 3m 2s | 4 → 53 |
| OkHttp | $0.47 → $0.47 | 636k → 730k | 42s → 1m 1s | 6 → 11 |
| Gin | $0.37 → $0.47 | 444k → 675k | 44s → 1m 0s | 6 → 10 |
| Alamofire | $0.61 → $1.14 | 1.0M → 2.8M | 1m 17s → 2m 27s | 12 → 69 |
**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.
---
## Key Features
| | |
|---|---|
| **Smart Context Building** | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents |
| **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 |
| **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes |
| **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |
| **19+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi |
| **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 14 frameworks |
| **100% Local** | No data leaves your machine. No API keys. No external services. SQLite database only |
---
## Framework-aware Routes
CodeGraph detects web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions. Querying callers of a view/controller now surfaces the URL pattern that binds it.
| Framework | Shapes recognized |
|---|---|
| **Django** | `path()`, `re_path()`, `url()`, `include()` in `urls.py` (CBV `.as_view()`, dotted paths) |
| **Flask** | `@app.route('/path', methods=[...])`, blueprint routes |
| **FastAPI** | `@app.get(...)`, `@router.post(...)`, all standard methods |
| **Express** | `app.get(...)`, `router.post(...)` with middleware chains |
| **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` |
| **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |
| **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |
| **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=>` syntax |
| **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
| **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` |
| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
| **ASP.NET** | `[HttpGet("/x")]` attributes on action methods |
| **Vapor** | `app.get("x", use: handler)` |
| **React Router** / **SvelteKit** | Route component nodes |
---
## Quick Start
### 1. Run the Installer
```bash
npx @agentllm/codegraph-arkts
```
The installer will:
- Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**
- Prompt to install `codegraph` on your PATH (so agents can launch the MCP server)
- Ask whether configs apply to all your projects or just this one
- Write each chosen agent's MCP server config + an instructions file (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`)
- Set up auto-allow permissions when Claude Code is one of the targets
- Initialize your current project (local installs only)
**Non-interactive (scripting / CI):**
```bash
codegraph install --yes # auto-detect agents, install global
codegraph install --target=cursor,claude --yes # explicit target list
codegraph install --target=auto --location=local # detected agents, project-local
codegraph install --print-config codex # print snippet, no file writes
```
| Flag | Values | Default |
|---|---|---|
| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,...`) | prompt |
| `--location` | `global`, `local` | prompt |
| `--yes` | (boolean) | prompt every step |
| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
| `--print-config ` | dump snippet for one agent and exit | — |
### 2. Restart Your Agent
Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent) for the MCP server to load.
### 3. Initialize Projects
```bash
cd your-project
codegraph init -i
```
Builds the per-project knowledge graph index. Also wires up any project-local agent surfaces (e.g. Cursor's `.cursor/rules/codegraph.mdc`) so a single global `codegraph install` works in every project you open — no need to re-run the installer per project.
That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
## ArkTS Support
CodeGraph ArkTS fork includes first-class ArkTS support for HarmonyOS Stage model apps built from `.ets` files.
Chinese quickstart:
- [README.zh-CN.md](./README.zh-CN.md)
- ArkTS is enabled by default during indexing.
- ArkTS extraction uses the `ArkAnalyzer` backend, not the tree-sitter TypeScript path.
- The current ArkTS scope covers Stage model entries, `@Entry` / `@Component` / `@ComponentV2`, `@Builder`, core state decorators, `module.json5` declaration linkage, and navigation-visible `Want/IPC` relation hints.
- ArkTS facts now participate in shared `search`, `context`, `trace`, `impact`, `callers`, and `callees`.
Tooling note:
- For `ArkAnalyzer` boundaries, direct-use inspection, and fork-side capability uplift, see [docs/tools/arkanalyzer-integration-guide.md](./docs/tools/arkanalyzer-integration-guide.md).
## Release Verification
Release readiness for this fork requires more than unit tests.
Current release-candidate note:
- the core incremental ArkTS sync path has now been RSS-stabilized with bounded cache release and isolated changed-file extraction
- targeted medium refresh diagnostics now reproduce at low single-digit RSS drift on the product path
- the repository-owned synthetic benchmark still carries a remaining `medium repeated-refresh` RSS headline above the earlier soft target, and that benchmark/harness alignment is treated as next-version follow-up rather than a release-line blocker
Core verifier commands:
```bash
npx vitest run __tests__/release-packaging.test.ts
npm run verify:arkanalyzer-pack-install
npm run verify:global-install-mcp
```
Optional slower reinstall path:
```bash
npm run verify:global-reinstall-mcp
```
Run the two install-oriented verifier scripts sequentially, not in parallel.
Manual Setup (Alternative)
**Install globally:**
```bash
npm install -g @agentllm/codegraph-arkts
```
**Add to `~/.claude.json`:**
```json
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}
```
**Add to `~/.claude/settings.json` (optional, for auto-allow):**
```json
{
"permissions": {
"allow": [
"mcp__codegraph__codegraph_search",
"mcp__codegraph__codegraph_context",
"mcp__codegraph__codegraph_callers",
"mcp__codegraph__codegraph_callees",
"mcp__codegraph__codegraph_impact",
"mcp__codegraph__codegraph_node",
"mcp__codegraph__codegraph_status",
"mcp__codegraph__codegraph_files"
]
}
}
```
Global Instructions Reference
The installer automatically adds these instructions to `~/.claude/CLAUDE.md`:
```markdown
## CodeGraph
CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.
### If `.codegraph/` exists in the project
**Answer directly with CodeGraph — don't delegate exploration to a file-reading sub-agent or a grep/read loop.** CodeGraph *is* the pre-built search index; re-deriving its answers with grep + Read repeats work it already did and costs more for the same result. For "how does X work?", architecture, trace, or where-is-X questions, answer in a handful of CodeGraph calls and stop — typically with **zero file reads**. The returned source is complete and authoritative: treat it as already read and do not re-open those files. Reach for raw Read/Grep only to confirm a specific detail CodeGraph didn't cover.
**Tool selection by intent:**
| Tool | Use For |
|------|---------|
| `codegraph_context` | Map a task / feature / area first — composes search + node + callers + callees in one call |
| `codegraph_trace` | "How does X reach Y" — the call path, each hop's body inline (follows dynamic-dispatch hops grep can't) |
| `codegraph_explore` | Survey several related symbols' source in ONE budget-capped call |
| `codegraph_search` | Find a symbol by name |
| `codegraph_callers` / `codegraph_callees` | Walk call flow one hop at a time |
| `codegraph_impact` | Check what's affected before editing |
| `codegraph_node` | Get a single symbol's source / signature |
A direct CodeGraph answer is a handful of calls; a grep/read exploration is dozens.
### If `.codegraph/` does NOT exist
At the start of a session, ask the user if they'd like to initialize CodeGraph:
"I notice this project doesn't have CodeGraph initialized. Would you like me to run `codegraph init -i` to build a code knowledge graph?"
```
---
## How It Works
```
┌───────────────────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ "How does a request reach the database?" │
│ calls CodeGraph tools directly — no Explore sub-agent │
│ │ │
└─────────────────────────────────┬─────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ CodeGraph MCP Server │
│ │
│ context · trace · explore · callers · callees · impact │
│ │ │
│ ▼ │
│ SQLite knowledge graph │
│ symbols · edges · files · FTS5 full-text search │
└───────────────────────────────────────────────────────────────────┘
```
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).
2. **Storage** — Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search.
3. **Resolution** — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.
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.
---
## CLI Reference
```bash
codegraph # Run interactive installer
codegraph install # Run installer (explicit)
codegraph uninstall # Remove CodeGraph from your agents (inverse of install)
codegraph init [path] # Initialize in a project (--index to also index)
codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path] # Full index (--force to re-index, --quiet for less output)
codegraph sync [path] # Incremental update
codegraph status [path] # Show statistics
codegraph query # Search symbols (--kind, --limit, --json)
codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json)
codegraph context # Build context for AI (--format, --max-nodes)
codegraph callers # Find what calls a function/method (--limit, --json)
codegraph callees # Find what a function/method calls (--limit, --json)
codegraph impact # Analyze what code is affected by changing a symbol (--depth, --json)
codegraph affected [files...] # Find test files affected by changes (see below)
codegraph serve --mcp # Start MCP server
codegraph upgrade [version] # Update to the latest release (--check, --force)
```
### `codegraph affected`
Traces import dependencies transitively to find which test files are affected by changed source files.
```bash
codegraph affected src/utils.ts src/api.ts # Pass files as arguments
git diff --name-only | codegraph affected --stdin # Pipe from git diff
codegraph affected src/auth.ts --filter "e2e/*" # Custom test file pattern
```
| Option | Description | Default |
|--------|-------------|---------|
| `--stdin` | Read file list from stdin | `false` |
| `-d, --depth ` | Max dependency traversal depth | `5` |
| `-f, --filter ` | Custom glob to identify test files | auto-detect |
| `-j, --json` | Output as JSON | `false` |
| `-q, --quiet` | Output file paths only | `false` |
**CI/hook example:**
```bash
#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fi
```
---
## MCP Tools
When running as an MCP server, CodeGraph exposes these tools to Claude Code:
| Tool | Purpose |
|------|---------|
| `codegraph_search` | Find symbols by name across the codebase |
| `codegraph_context` | Build relevant code context for a task |
| `codegraph_trace` | Trace the call path between two symbols ("how does X reach Y") in one call — each hop with its body inline, following dynamic-dispatch hops (callbacks, React re-render, interface→impl) that grep can't |
| `codegraph_callers` | Find what calls a function |
| `codegraph_callees` | Find what a function calls |
| `codegraph_impact` | Analyze what code is affected by changing a symbol |
| `codegraph_node` | Get details about a specific symbol (optionally with source code) |
| `codegraph_explore` | Return source for several related symbols grouped by file, plus a relationship map, in one call |
| `codegraph_files` | Get indexed file structure (faster than filesystem scanning) |
| `codegraph_status` | Check index health and statistics |
---
## Library Usage
```typescript
import CodeGraph from '@agentllm/codegraph-arkts';
const cg = await CodeGraph.init('/path/to/project');
// Or: const cg = await CodeGraph.open('/path/to/project');
await cg.indexAll({
onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});
const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);
cg.watch(); // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();
```
---
## Configuration
There isn't any — CodeGraph is zero-config, with **no config file** to write or
keep in sync. Language support is automatic from the file extension; there's
nothing to wire up per language.
What it skips out of the box:
- **Dependency, build, and cache directories** — `node_modules`, `vendor`,
`dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every
[supported stack](#supported-languages) — so the graph is your code, not
third-party noise. This holds even with no `.gitignore`.
- **Anything in your `.gitignore`** — honored in git repos via git, and in
non-git projects by reading `.gitignore` directly (root and nested).
- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.
To keep something else out, add it to `.gitignore`. To pull a default-excluded
directory back **in** (say you really do want a vendored dependency indexed),
add a negation — `!vendor/`. The defaults apply uniformly, so committing a
dependency or build directory doesn't force it into the graph; the `.gitignore`
negation is the explicit opt-in.
## Supported Platforms
Every release ships a self-contained build (bundled Node runtime — nothing to
compile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):
| Platform | Architectures | Install |
|----------|---------------|---------|
| Windows | x64, arm64 | PowerShell installer or npm |
| macOS | x64, arm64 | shell installer or npm |
| Linux | x64, arm64 | shell installer or npm |
See [Get Started](#get-started) for the one-line install commands.
## Supported Agents
The interactive installer auto-detects and configures each of these — wiring up
the MCP server and writing its instructions file:
- **Claude Code**
- **Cursor**
- **Codex CLI**
- **opencode**
- **Hermes Agent**
## Supported Languages
| Language | Extension | Status |
|----------|-----------|--------|
| TypeScript | `.ts`, `.tsx` | Full support |
| JavaScript | `.js`, `.jsx`, `.mjs` | Full support |
| Python | `.py` | Full support |
| Go | `.go` | Full support |
| Rust | `.rs` | Full support |
| Java | `.java` | Full support |
| C# | `.cs` | Full support |
| PHP | `.php` | Full support |
| Ruby | `.rb` | Full support |
| C | `.c`, `.h` | Full support |
| C++ | `.cpp`, `.hpp`, `.cc` | Full support |
| Swift | `.swift` | Full support |
| Kotlin | `.kt`, `.kts` | Full support |
| Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) |
| Dart | `.dart` | Full support |
| Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |
| Vue | `.vue` | Full support (script + script-setup extraction, Nuxt page/API/middleware routes) |
| Liquid | `.liquid` | Full support |
| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX form files) |
| Lua | `.lua` | Full support (functions, methods with receivers, local variables, `require` imports, call edges) |
| Luau | `.luau` | Full support (everything in Lua, plus `type`/`export type` aliases, typed signatures, and Roblox instance-path `require`) |
## Measured cross-file coverage
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.
| Language | Benchmark repo | Coverage |
|---|---|---|
| TypeScript / JavaScript | this repo | 95.8% |
| Python | psf/requests | 100% |
| Go | gin-gonic/gin | 96.6% |
| Rust | BurntSushi/ripgrep | 86.7% |
| Java | google/gson | 93.3% |
| C# | jbogard/MediatR | 85.2% |
| PHP | guzzle/guzzle | 100% |
| Ruby | sidekiq/sidekiq | 100% |
| C | redis/redis | 92.2% |
| C++ | google/leveldb | 94.8% |
| Objective-C | SDWebImage | 91.6% |
| Swift | Alamofire | 95.3% |
| Kotlin | square/okhttp | 96.2% |
| Scala | gatling/gatling | 91.2% |
| Dart | flutter/packages | 92.4% |
| Svelte / SvelteKit | sveltejs/realworld | 100% |
| Vue / Nuxt | nuxt/movies | 93.5% |
| Lua | nvim-telescope/telescope.nvim | 84.2% |
| Luau | dphfox/Fusion | 92.2% |
| Liquid | Shopify/dawn | 73.8% |
| Pascal / Delphi | PascalCoin | 75.7% |
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%.
## Troubleshooting
**"CodeGraph not initialized"** — Run `codegraph init` in your project directory first.
**Indexing is slow** — Check that `node_modules` and other large directories are excluded. Use `--quiet` to reduce output overhead.
**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:
- **You're on an old install.** Reinstall this fork with `npm i -g @agentllm/codegraph-arkts@latest` or re-run `npx @agentllm/codegraph-arkts`.
- **`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.
**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.
**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`).
**Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.
## Star History
## License
MIT
---
**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent**
[Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues)
Get early beta access to the hosted product · getcodegraph.com