@optave/codegraph
Advanced tools
Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them
Always-fresh code intelligence for AI agents — sub-second incremental rebuilds, zero-cost by default, optionally enhanced with your LLM.
Why codegraph? • Quick Start • Features • Commands • Languages • AI Integration • Practices • CI/CD • Roadmap • Contributing
The code graph that keeps up with your commits.
Codegraph parses your codebase with tree-sitter (native Rust or WASM), builds a function-level dependency graph in SQLite, and keeps it current with sub-second incremental rebuilds. Every query runs locally — no API keys, no Docker, no setup. When you want deeper intelligence, bring your own LLM provider and codegraph enhances search and analysis through the same API you already use. Your code only goes where you choose to send it.
If you use a code graph with an AI agent, the graph needs to be current. A stale graph gives the agent wrong answers — deleted functions still show up, new dependencies are invisible, impact analysis misses the code you just wrote. The graph should rebuild on every commit, ideally on every save.
Most tools in this space can't do that:
| Problem | Who has it | Why it breaks on every commit |
|---|---|---|
| Full re-index on every change | code-graph-rag, CodeMCP, axon, joern, cpg, GitNexus | No file-level change tracking. Change one file → re-parse and re-insert the entire codebase. On a 3,000-file project, that's 30+ seconds per commit minimum |
| Cloud API calls baked into the pipeline | code-graph-rag, CodeRAG | Embeddings are generated through cloud APIs (OpenAI, Voyage AI, Gemini). Every rebuild = API round-trips for every function. Slow, expensive, and rate-limited. You can't put this in a commit hook |
| Heavy infrastructure that's slow to restart | code-graph-rag (Memgraph), axon (KuzuDB), badger-graph (Dgraph) | External databases add latency to every write. Bulk-inserting a full graph into Memgraph is not a sub-second operation |
| No persistence between runs | pyan, cflow | Re-parse from scratch every time. No database, no delta, no incremental anything |
Codegraph solves this with three-tier incremental change detection:
codegraph watch was running, a change journal records exactly which files were touched. The next build reads the journal and only processes those files — zero filesystem scanningResult: change one file in a 3,000-file project → rebuild completes in under a second. With watch mode active, rebuilds are near-instant — the journal makes the build proportional to the number of changed files, not the size of the codebase. Put it in a commit hook, a file watcher, or let your AI agent trigger it. The graph is always current.
And because the core pipeline is pure local computation (tree-sitter + SQLite), there are no API calls, no network latency, and no cost. LLM-powered features (semantic search, richer embeddings) are a separate optional layer — they enhance the graph but never block it from being current.
Comparison last verified: February 2026
Most code graph tools make you choose: fast local analysis with no AI, or powerful AI features that require full re-indexing through cloud APIs on every change. Codegraph gives you both — a graph that rebuilds in milliseconds on every commit, with optional LLM enhancement through the provider you're already using.
| Capability | codegraph | joern | narsil-mcp | code-graph-rag | cpg | GitNexus | CodeMCP | axon |
|---|---|---|---|---|---|---|---|---|
| Function-level analysis | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Multi-language | 11 | 14 | 32 | Multi | ~10 | 9 | SCIP langs | Few |
| Semantic search | Yes | — | Yes | Yes | — | Yes | — | — |
| MCP / AI agent support | Yes | — | Yes | Yes | Yes | Yes | Yes | — |
| Git diff impact | Yes | — | — | — | — | Yes | — | Yes |
| Watch mode | Yes | — | Yes | — | — | — | — | — |
| Cycle detection | Yes | — | Yes | — | — | — | — | Yes |
| Incremental rebuilds | O(changed) | — | O(n) Merkle | — | — | — | — | — |
| Zero config | Yes | — | Yes | — | — | — | — | — |
Embeddable JS library (npm install) | Yes | — | — | — | — | — | — | — |
| LLM-optional (works without API keys) | Yes | Yes | Yes | — | Yes | Yes | Yes | Yes |
| Commercial use allowed | Yes | Yes | Yes | Yes | Yes | — | — | — |
| Open source | Yes | Yes | Yes | Yes | Yes | Yes | Custom | — |
| Differentiator | In practice | |
|---|---|---|
| ⚡ | Always-fresh graph | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds even on large codebases. Competitors re-index everything from scratch; Merkle-tree approaches still require O(n) filesystem scanning |
| 🔓 | Zero-cost core, LLM-enhanced when you want | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider for richer embeddings and AI-powered search — your code only goes to the provider you already chose |
| 🔬 | Function-level, not just files | Traces handleAuth() → validateToken() → decryptJWT() and shows 14 callers across 9 files break if decryptJWT changes |
| 🤖 | Built for AI agents | 17-tool MCP server — AI assistants query your graph directly. Single-repo by default, your code doesn't leak to other projects |
| 🌐 | Multi-language, one CLI | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph — no juggling Madge, pyan, and cflow |
| 💥 | Git diff impact | codegraph diff-impact shows changed functions, their callers, and full blast radius — ships with a GitHub Actions workflow |
| 🧠 | Semantic search | Local embeddings by default, LLM-powered embeddings when opted in — multi-query with RRF ranking via "auth; token; JWT" |
The key question is: can you rebuild your graph on every commit in a large codebase without it costing money or taking minutes? Most tools in this space either re-index everything from scratch (slow), require cloud API calls for core features (costly), or both. Codegraph's three-tier incremental detection achieves true O(changed) in the best case — when the watcher is running, rebuilds are proportional only to the number of files that changed, not the size of the codebase. The core pipeline needs no API keys at all. LLM-powered features are opt-in, using whichever provider you already work with.
| Tool | What it does well | The tradeoff |
|---|---|---|
| joern | Full CPG (AST + CFG + PDG) for vulnerability discovery, Scala query DSL, 14 languages, daily releases | No incremental builds — full re-parse on every change. Requires JDK 21, no built-in MCP, no watch mode |
| narsil-mcp | 90 MCP tools, 32 languages, taint analysis, SBOM, dead code, neural search, Merkle-tree incremental indexing, single ~30MB binary | Merkle trees still require O(n) filesystem scanning on every rebuild. Primarily MCP-only — no standalone CLI query interface. Neural search requires API key or ONNX source build |
| code-graph-rag | Graph RAG with Memgraph, multi-provider AI, semantic search, code editing via AST | No incremental rebuilds — full re-index + re-embed through cloud APIs on every change. Requires Docker |
| cpg | Formal Code Property Graph (AST + CFG + PDG + DFG), ~10 languages, MCP module, LLVM IR support, academic specifications | No incremental builds. Requires JVM + Gradle, no zero config, no watch mode |
| GitNexus | Knowledge graph with precomputed structural intelligence, 7 MCP tools, hybrid search (BM25 + semantic + RRF), clustering, process tracing | Full 6-phase pipeline re-run on changes. KuzuDB graph DB, browser mode limited to ~5,000 files. PolyForm NC — no commercial use |
| CodeMCP | SCIP compiler-grade indexing, compound operations (83% token savings), secret scanning | No incremental builds. Custom license, requires SCIP toolchains per language |
| axon | 11-phase pipeline, KuzuDB, community detection, dead code, change coupling | Full pipeline re-run on changes. No license, Python-only, no MCP |
| Madge | Simple file-level JS/TS dependency graphs | No function-level analysis, no impact tracing, JS/TS only |
| dependency-cruiser | Architectural rule validation for JS/TS | Module-level only (function-level explicitly out of scope), requires config |
| Nx graph | Monorepo project-level dependency graph | Requires Nx workspace, project-level only (not file or function) |
| pyan / cflow | Function-level call graphs | Single-language each (Python / C only), no persistence, no queries |
If you are looking for local code intelligence over MCP, the closest alternative to codegraph is postrv/narsil-mcp. Both projects aim to give AI agents deep context about your codebase, but they approach the problem with fundamentally different philosophies.
Here is a cold, analytical breakdown to help you decide which tool fits your workflow.
| Aspect | Optave Codegraph | Narsil-MCP |
|---|---|---|
| Philosophy | Lean, deterministic, AI-optimized | Comprehensive, feature-dense |
| AI Tool Count | 17 focused tools | 90 distinct tools |
| Language Support | 11 languages | 32 languages |
| Primary Interface | CLI-first with MCP integration | MCP-first (CLI is secondary) |
| Supply Chain Risk | Low (minimal dependency tree) | Higher (requires massive dependency graph for embedded ML/scanners) |
| Graph Updates | Three-tier O(changed) — journal → mtime+size → hash. With watch mode, only changed files are touched | Merkle trees — O(n) filesystem scan on every rebuild to recompute tree hashes |
diff-impact are built specifically to tell you exactly how a changed function cascades through your codebase before you merge a PR.# Install from npm
npm install -g @optave/codegraph
# Or install from source
git clone https://github.com/optave/codegraph.git
cd codegraph
npm install
npm link
# Build a graph for any project
cd your-project
codegraph build # → .codegraph/graph.db created
# Start exploring
codegraph map # see most-connected files
codegraph query myFunc # find any function, see callers & callees
codegraph deps src/index.ts # file-level import/export map
| Feature | Description | |
|---|---|---|
| 🔍 | Symbol search | Find any function, class, or method by name with callers/callees |
| 📁 | File dependencies | See what a file imports and what imports it |
| 💥 | Impact analysis | Trace every file affected by a change (transitive) |
| 🧬 | Function-level tracing | Call chains, caller trees, and function-level impact |
| 📊 | Diff impact | Parse git diff, find overlapping functions, trace their callers |
| 🗺️ | Module map | Bird's-eye view of your most-connected files |
| 🔄 | Cycle detection | Find circular dependencies at file or function level |
| 📤 | Export | DOT (Graphviz), Mermaid, and JSON graph export |
| 🧠 | Semantic search | Embeddings-powered natural language search with multi-query RRF ranking |
| 👀 | Watch mode | Incrementally update the graph as files change |
| 🤖 | MCP server | 17-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
| 🔒 | Your code, your choice | Zero-cost core with no API keys. Optionally enhance with your LLM provider — your code only goes where you send it |
codegraph build [dir] # Parse and build the dependency graph
codegraph build --no-incremental # Force full rebuild
codegraph build --engine wasm # Force WASM engine (skip native)
codegraph watch [dir] # Watch for changes, update graph incrementally
codegraph query <name> # Find a symbol — shows callers and callees
codegraph deps <file> # File imports/exports
codegraph map # Top 20 most-connected files
codegraph map -n 50 # Top 50
codegraph impact <file> # Transitive reverse dependency trace
codegraph fn <name> # Function-level: callers, callees, call chain
codegraph fn <name> --no-tests --depth 5
codegraph fn-impact <name> # What functions break if this one changes
codegraph diff-impact # Impact of unstaged git changes
codegraph diff-impact --staged # Impact of staged changes
codegraph diff-impact HEAD~3 # Impact vs a specific ref
codegraph export -f dot # Graphviz DOT format
codegraph export -f mermaid # Mermaid diagram
codegraph export -f json # JSON graph
codegraph export --functions -o graph.dot # Function-level, write to file
codegraph cycles # Detect circular dependencies
codegraph cycles --functions # Function-level cycles
Codegraph can build local embeddings for every function, method, and class, then search them by natural language. Everything runs locally using @huggingface/transformers — no API keys needed.
codegraph embed # Build embeddings (default: minilm)
codegraph embed --model nomic # Use a different model
codegraph search "handle authentication"
codegraph search "parse config" --min-score 0.4 -n 10
codegraph models # List available models
Separate queries with ; to search from multiple angles at once. Results are ranked using Reciprocal Rank Fusion (RRF) — items that rank highly across multiple queries rise to the top.
codegraph search "auth middleware; JWT validation"
codegraph search "parse config; read settings; load env" -n 20
codegraph search "error handling; retry logic" --kind function
codegraph search "database connection; query builder" --rrf-k 30
A single trailing semicolon is ignored (falls back to single-query mode). The --rrf-k flag controls the RRF smoothing constant (default 60) — lower values give more weight to top-ranked results.
| Flag | Model | Dimensions | Size | License | Notes |
|---|---|---|---|---|---|
minilm | all-MiniLM-L6-v2 | 384 | ~23 MB | Apache-2.0 | Fastest, good for quick iteration |
jina-small | jina-embeddings-v2-small-en | 512 | ~33 MB | Apache-2.0 | Better quality, still small |
jina-base | jina-embeddings-v2-base-en | 768 | ~137 MB | Apache-2.0 | High quality, 8192 token context |
jina-code (default) | jina-embeddings-v2-base-code | 768 | ~137 MB | Apache-2.0 | Best for code search, trained on code+text |
nomic | nomic-embed-text-v1 | 768 | ~137 MB | Apache-2.0 | Good quality, 8192 context |
nomic-v1.5 | nomic-embed-text-v1.5 | 768 | ~137 MB | Apache-2.0 | Improved nomic, Matryoshka dimensions |
bge-large | bge-large-en-v1.5 | 1024 | ~335 MB | MIT | Best general retrieval, top MTEB scores |
The model used during embed is stored in the database, so search auto-detects it — no need to pass --model when searching.
Manage a global registry of codegraph-enabled projects. The registry stores paths to your built graphs so the MCP server can query them when multi-repo mode is enabled.
codegraph registry list # List all registered repos
codegraph registry list --json # JSON output
codegraph registry add <dir> # Register a project directory
codegraph registry add <dir> -n my-name # Custom name
codegraph registry remove <name> # Unregister
codegraph build auto-registers the project — no manual setup needed.
codegraph mcp # Start MCP server (single-repo, current project only)
codegraph mcp --multi-repo # Enable access to all registered repos
codegraph mcp --repos a,b # Restrict to specific repos (implies --multi-repo)
By default, the MCP server only exposes the local project's graph. AI agents cannot access other repositories unless you explicitly opt in with --multi-repo or --repos.
| Flag | Description |
|---|---|
-d, --db <path> | Custom path to graph.db |
-T, --no-tests | Exclude .test., .spec., __test__ files |
--depth <n> | Transitive trace depth (default varies by command) |
-j, --json | Output as JSON |
-v, --verbose | Enable debug output |
--engine <engine> | Parser engine: native, wasm, or auto (default: auto) |
-k, --kind <kind> | Filter by kind: function, method, class, struct, enum, trait, record, module (search) |
--file <pattern> | Filter by file path pattern (search) |
--rrf-k <n> | RRF smoothing constant for multi-query search (default 60) |
| Language | Extensions | Coverage |
|---|---|---|
 | .js, .jsx, .mjs, .cjs | Full — functions, classes, imports, call sites |
 | .ts, .tsx | Full — interfaces, type aliases, .d.ts |
 | .py | Functions, classes, methods, imports, decorators |
 | .go | Functions, methods, structs, interfaces, imports, call sites |
 | .rs | Functions, methods, structs, traits, use imports, call sites |
 | .java | Classes, methods, constructors, interfaces, imports, call sites |
 | .cs | Classes, structs, records, interfaces, enums, methods, constructors, using directives, invocations |
 | .php | Functions, classes, interfaces, traits, enums, methods, namespace use, calls |
 | .rb | Classes, modules, methods, singleton methods, require/require_relative, include/extend |
 | .tf, .hcl | Resource, data, variable, module, output blocks |
┌──────────┐ ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌─────────┐
│ Source │──▶│ tree-sitter│──▶│ Extract │──▶│ Resolve │──▶│ SQLite │
│ Files │ │ Parse │ │ Symbols │ │ Imports │ │ DB │
└──────────┘ └───────────┘ └───────────┘ └──────────┘ └─────────┘
│
▼
┌─────────┐
│ Query │
└─────────┘
tsconfig.json path aliases, baseUrl)Codegraph ships with two parsing engines:
| Engine | How it works | When it's used |
|---|---|---|
| Native (Rust) | napi-rs addon built from crates/codegraph-core/ — parallel multi-core parsing via rayon | Auto-selected when the prebuilt binary is available |
| WASM | web-tree-sitter with pre-built .wasm grammars in grammars/ | Fallback when the native addon isn't installed |
Both engines produce identical output. Use --engine native|wasm|auto to control selection (default: auto).
Calls are resolved with priority and confidence scoring:
| Priority | Source | Confidence |
|---|---|---|
| 1 | Import-aware — import { foo } from './bar' → link to bar | 1.0 |
| 2 | Same-file — definitions in the current file | 1.0 |
| 3 | Same directory — definitions in sibling files | 0.7 |
| 4 | Same parent directory — definitions in sibling dirs | 0.5 |
| 5 | Global fallback — match by name across codebase | 0.3 |
| 6 | Method hierarchy — resolved through extends/implements | — |
Dynamic patterns like fn.call(), fn.apply(), fn.bind(), and obj["method"]() are also detected on a best-effort basis.
Self-measured on every release via CI (full history):
| Metric | Latest |
|---|---|
| Build speed (native) | 2.5 ms/file |
| Build speed (WASM) | 5 ms/file |
| Query time | 1ms |
| ~50,000 files (est.) | ~125.0s build |
Metrics are normalized per file for cross-version comparability. Times above are for a full initial build — incremental rebuilds only re-parse changed files.
Codegraph includes a built-in Model Context Protocol server with 17 tools, so AI assistants can query your dependency graph directly:
codegraph mcp # Single-repo mode (default) — only local project
codegraph mcp --multi-repo # Multi-repo — all registered repos accessible
codegraph mcp --repos a,b # Multi-repo with allowlist
Single-repo mode (default): Tools operate only on the local .codegraph/graph.db. The repo parameter and list_repos tool are not exposed to the AI agent.
Multi-repo mode (--multi-repo): All tools gain an optional repo parameter to target any registered repository, and list_repos becomes available. Use --repos to restrict which repos the agent can access.
Add this to your project's CLAUDE.md to help AI agents use codegraph (full template in the AI Agent Guide):
## Code Navigation
This project uses codegraph. The database is at `.codegraph/graph.db`.
### Before modifying code, always:
1. `codegraph where <name>` — find where the symbol lives
2. `codegraph explain <file-or-function>` — understand the structure
3. `codegraph context <name> -T` — get full context (source, deps, callers)
4. `codegraph fn-impact <name> -T` — check blast radius before editing
### After modifying code:
5. `codegraph diff-impact --staged -T` — verify impact before committing
### Other useful commands
- `codegraph build .` — rebuild the graph (incremental by default)
- `codegraph map` — module overview
- `codegraph fn <name> -T` — function call chain
- `codegraph deps <file>` — file-level dependencies
- `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
- `codegraph cycles` — check for circular dependencies
### Flags
- `-T` / `--no-tests` — exclude test files (use by default)
- `-j` / `--json` — JSON output for programmatic use
- `-f, --file <path>` — scope to a specific file
- `-k, --kind <kind>` — filter by symbol kind
### Semantic search
Use `codegraph search` to find functions by intent rather than exact name.
When a single query might miss results, combine multiple angles with `;`:
codegraph search "validate auth; check token; verify JWT"
codegraph search "parse config; load settings" --kind function
Multi-query search uses Reciprocal Rank Fusion — functions that rank
highly across several queries surface first. This is especially useful
when you're not sure what naming convention the codebase uses.
When writing multi-queries, use 2-4 sub-queries (2-4 words each) that
attack the problem from different angles. Pick from these strategies:
- **Naming variants**: cover synonyms the author might have used
("send email; notify user; deliver message")
- **Abstraction levels**: pair high-level intent with low-level operation
("handle payment; charge credit card")
- **Input/output sides**: cover the read half and write half
("parse config; apply settings")
- **Domain + technical**: bridge business language and implementation
("onboard tenant; create organization; provision workspace")
Use `--kind function` to cut noise. Use `--file <pattern>` to scope.
See docs/recommended-practices.md for integration guides:
apiKeyCommand with 1Password, Bitwarden, Vault, macOS Keychain, passFor AI-specific integration, see the AI Agent Guide — a comprehensive reference covering the 6-step agent workflow, complete command-to-MCP mapping, Claude Code hooks, and token-saving patterns.
Codegraph ships with a ready-to-use GitHub Actions workflow that comments impact analysis on every pull request.
Copy .github/workflows/codegraph-impact.yml to your repo, and every PR will get a comment like:
3 functions changed → 12 callers affected across 7 files
Create a .codegraphrc.json in your project root to customize behavior:
{
"include": ["src/**", "lib/**"],
"exclude": ["**/*.test.js", "**/__mocks__/**"],
"ignoreDirs": ["node_modules", ".git", "dist"],
"extensions": [".js", ".ts", ".tsx", ".py"],
"aliases": {
"@/": "./src/",
"@utils/": "./src/utils/"
},
"build": {
"incremental": true
}
}
Codegraph supports an apiKeyCommand field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:
{
"llm": {
"provider": "openai",
"apiKeyCommand": "op read op://vault/openai/api-key"
}
}
The command is split on whitespace and executed with execFileSync (no shell injection risk). Priority: command output > CODEGRAPH_LLM_API_KEY env var > file config. On failure, codegraph warns and falls back to the next source.
Works with any secret manager: 1Password CLI (op), Bitwarden (bw), pass, HashiCorp Vault, macOS Keychain (security), AWS Secrets Manager, etc.
Codegraph also exports a full API for use in your own tools:
import { buildGraph, queryNameData, findCycles, exportDOT } from '@optave/codegraph';
// Build the graph
buildGraph('/path/to/project');
// Query programmatically
const results = queryNameData('myFunction', '/path/to/.codegraph/graph.db');
import { parseFileAuto, getActiveEngine, isNativeAvailable } from '@optave/codegraph';
// Check which engine is active
console.log(getActiveEngine()); // 'native' or 'wasm'
console.log(isNativeAvailable()); // true if Rust addon is installed
// Parse a single file (uses auto-selected engine)
const symbols = await parseFileAuto('/path/to/file.ts');
import { searchData, multiSearchData, buildEmbeddings } from '@optave/codegraph';
// Build embeddings (one-time)
await buildEmbeddings('/path/to/project');
// Single-query search
const { results } = await searchData('handle auth', dbPath);
// Multi-query search with RRF ranking
const { results: fused } = await multiSearchData(
['auth middleware', 'JWT validation'],
dbPath,
{ limit: 10, minScore: 0.3 }
);
// Each result has: { name, kind, file, line, rrf, queryScores[] }
.d.ts interfaces but doesn't use TypeScript's type checker for overload resolutioneval patterns are not resolvedsys.path or virtual environment packagesSee ROADMAP.md for the full development roadmap. Current plan:
apiKeyCommand secret resolution, global repo registrycodegraph ask command, conversational sessionsContributions are welcome! See CONTRIBUTING.md for the full guide — setup, workflow, commit convention, testing, and architecture notes.
git clone https://github.com/optave/codegraph.git
cd codegraph
npm install
npm test
Looking to add a new language? Check out Adding a New Language.
Built with tree-sitter and better-sqlite3. Your code only goes where you choose to send it.
FAQs
Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them
The npm package @optave/codegraph receives a total of 2,561 weekly downloads. As such, @optave/codegraph popularity was classified as popular.
We found that @optave/codegraph demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Packagist urges PHP projects to update Composer after a GitHub token format change exposed some GitHub Actions tokens in CI logs.
Research
GemStuffer abuses RubyGems as an exfiltration channel, packaging scraped UK council portal data into junk gems published from new accounts.
Company News
Socket was named to the Rising in Cyber 2026 list, recognizing 30 private cybersecurity startups selected by CISOs and security executives.