CodeGraph

Semantic code search and project context for AI coding agents.

CodeGraph indexes your source code into a local graph database. After indexing, you can search symbols, inspect project structure, and generate focused context for coding agents without asking them to scan the whole repository again and again.

Published package: @tienmanh/codegraph

Why Use It

• Understand a codebase faster.
• Find functions, classes, routes, and files by name or meaning.
• Give AI agents focused context before they edit code.
• Inspect callers, callees, related symbols, and change impact through MCP.
• Keep the index local in .codegraph/.
• Use it with one repository or a multi-project workspace.

CodeGraph works best with MCP-compatible coding agents such as Claude Code, Cursor, Codex CLI, and opencode.

Requirements

• Node.js >=20 <25
• npm

node --version
npm --version

Install

Install globally:

npm install -g @tienmanh/codegraph
codegraph --help

Run without global install:

npx @tienmanh/codegraph --help

Upgrade:

npm install -g @tienmanh/codegraph@latest

Uninstall:

npm uninstall -g @tienmanh/codegraph

Quick Start

Initialize CodeGraph in a project:

cd your-project
codegraph init -i
codegraph status

Search indexed code:

codegraph query "PaymentService"
codegraph files

Build context for an AI task:

codegraph context "How does authentication work?"

Refresh the index after code changes:

codegraph sync

Rebuild the full index:

codegraph index

Remove CodeGraph data from the project:

codegraph uninit

Use With AI Agents

Install CodeGraph MCP configuration for the current project:

codegraph install --location local --target auto

Restart your agent after installation.

Once installed, your agent can use CodeGraph to search symbols, read focused code context, inspect callers/callees, list files, and check change impact. MCP tools auto-sync changed files before each index query by default, so agent queries see recently edited, added, or removed source files without a manual codegraph sync.

Preview installer changes before writing files:

codegraph install --location local --target auto --dry-run

Remove CodeGraph-owned agent configuration:

codegraph uninstall --location local --target auto

MCP Auto-Sync

Auto-sync is enabled by default when CodeGraph is installed or updated. It does not run a background watcher; each MCP query checks the selected project for changed source files, syncs only the affected files, then reads the index. In git projects, the check forces git status --untracked-files=all so new source files are detected even when they live inside a brand-new directory or the repo hides untracked files by default. When a workspace project lives inside a parent git repository, CodeGraph normalizes git paths back to the child project root before deciding what to sync. If the child project has its own .git, CodeGraph uses that child git root directly.

Default settings:

CODEGRAPH_AUTO_SYNC=query
CODEGRAPH_AUTO_SYNC_TTL_MS=0
CODEGRAPH_WORKSPACE_SYNC_CONCURRENCY=2

Useful overrides:

# Disable MCP auto-sync for debugging or benchmarks
CODEGRAPH_AUTO_SYNC=off

# Skip repeated checks for this many milliseconds
CODEGRAPH_AUTO_SYNC_TTL_MS=1000

# Limit concurrent project refreshes in workspace mode
CODEGRAPH_WORKSPACE_SYNC_CONCURRENCY=1

CLI commands still stay explicit: use codegraph sync or codegraph workspace sync when you want to refresh outside MCP.

Workspace Basics

Use workspace mode when one folder contains multiple projects:

cd your-workspace
codegraph workspace init
codegraph workspace discover
codegraph workspace index
codegraph workspace status

Each enabled child project gets its own .codegraph/codegraph.db. The workspace root keeps .codegraph/workspace.json. MCP workspace tools auto-sync the enabled child projects they query before returning results.

Refresh all enabled projects:

codegraph workspace sync

Local UI

Open the graph explorer:

codegraph ui

Common options:

codegraph ui --port 8732
codegraph ui --project ./packages/api
codegraph ui --workspace .

Common Commands

| Command | Purpose | |---|---| | codegraph init -i | Initialize and index the current project | | codegraph status | Show index status | | codegraph query <text> | Search indexed symbols | | codegraph context <task> | Build focused task context | | codegraph files | Show indexed files | | codegraph sync | Sync changed files | | codegraph index | Rebuild the index | | codegraph ui | Open the local UI | | codegraph install | Configure MCP integration | | codegraph uninstall | Remove CodeGraph-owned MCP config | | codegraph workspace ... | Manage multi-project workspaces |

Print help:

codegraph --help
codegraph install --help
codegraph workspace --help

Supported Codebases

CodeGraph supports common languages such as TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, and Pascal/Delphi.

It also understands common framework conventions for routes and project structure in frameworks such as Express, NestJS, Django, Flask, FastAPI, Laravel, Rails, Spring, Gin, Axum, ASP.NET, React Router, SvelteKit, and Nuxt.

More Documentation

• Workspace manifest
• Installer safety
• Search quality loop

License

MIT