codebase-graph

CodeGraph turns source code and project knowledge into a searchable graph for AI agents and developers. It parses code with tree-sitter, stores structural and temporal relationships in FalkorDB, and exposes five focused tools through the Model Context Protocol (MCP).
Access the project
- Landing page
- npm package
- Source code
- Issues
- Discussions
- Contribution guide
- Security policy
- MIT license
The public npm package is @agntk/codegraph-mcp. Version 0.1.0 provides the codegraph-mcp and codegraph-dashboard bins.
What it does
- Searches code by symbol, structure, and meaning.
- Extracts functions, classes, interfaces, variables, types, imports, calls, and other relationships.
- Stores project facts with valid_at and invalid_at timestamps for point-in-time queries.
- Supports first-class TypeScript, JavaScript, Python, Go, Rust, and Markdown parsing, with generic tree-sitter support for additional languages.
- Runs with embedded FalkorDBLite on Linux x64 and Apple silicon macOS, or an external FalkorDB service on any supported Node.js platform. Apple silicon requires Homebrew libomp and openssl@3 runtime libraries.
- Explores exact graph totals in Files or Symbols view with most-connected-first windows, Previous/Next paging, append-style loading, in-place neighbor expansion, and a Files-view toggle for unresolved external modules.
- Exposes analyze, codebase, knowledge, query, and search MCP tools.
Choose how to start
CodeGraph requires Node.js 20 or newer. The npm commands below install the public @agntk/codegraph-mcp package from the registry.
Agent-first with MCP
Add this server configuration to an MCP client:
In the first conversation, ask the agent to check CodeGraph status:
On a fresh install, codebase status returns configured: false and setupRequired: true. An empty database is a valid first run. Configure one absolute project path, then start a full index:
Configuration saves the project but does not index it. The full reindex parses structure first and then finishes embeddings. With the local provider, codebase status includes model load and indexing state while work is running.
Dashboard-first in a browser
Start the dashboard directly from the package:
Open the URL printed by the process. A fresh database opens on the setup flow. Confirm storage and embeddings, choose Browse to select a folder, then select Index project. The page shows model download and indexing progress, finishes remaining embeddings automatically, and reports file, symbol, edge, and embedding counts before opening the graph explorer.
The dashboard and MCP server are separate entry points. They can run at the same time against the same data path.
Platform and storage
| Platform | Default driver | Prerequisites | Configuration |
| --- | --- | --- | --- |
| Linux x64 | Embedded FalkorDBLite | Node.js 20 or newer | No database configuration when the embedded package is available |
| macOS Apple silicon | Embedded FalkorDBLite | Node.js 20 or newer, brew install libomp openssl@3 | No database configuration when the libraries and embedded package are available |
| macOS Intel | External FalkorDB | Node.js 20 or newer | Set the external variables below |
| Windows x64 | External FalkorDB | Node.js 20 or newer | Set the external variables below |
| Linux arm64 and other platforms | External FalkorDB | Node.js 20 or newer | Set the external variables below |
An explicit CODEGRAPH_DRIVER always wins. Without it, a configured FALKORDB_URL or FALKORDB_HOST selects external FalkorDB. Otherwise CodeGraph selects embedded FalkorDBLite on Linux x64, or on Apple silicon macOS when its native libraries are present, and falls back to external FalkorDB if the embedded package cannot load. All other platforms default to external FalkorDB.