Skip to content

codegraph_v2

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

codegraph_v2

README.md

CodeGraph v2

Workspace-aware semantic code intelligence for AI coding agents.

CodeGraph v2 indexes source code into a local SQLite knowledge graph so agents can answer structural questions with fast MCP tools instead of repeatedly scanning files. It is developed as a separate codebase from codegraph_v1; v1 remains the upstream reference baseline only.

What Is New In v2

  • First-class multi-repo workspace support.
  • Safe local-first installer for Claude Code, Cursor, Codex CLI, and opencode.
  • Global install protections: dry-run plan, backups, rollback, and marker-based instruction updates.
  • Workspace-aware MCP tools with project and projectPath targeting.
  • Child repositories ignored by the workspace root .gitignore can still be discovered and indexed.
  • One isolated .codegraph/codegraph.db per project.

Requirements

  • Node.js >=20 <25
  • npm
  • A supported agent if you want MCP integration: Claude Code, Cursor, Codex CLI, or opencode

Install

From npm:

npm install -g @dvttvnp/codegraph-v2
codegraph --help

From a local checkout:

cd codegraph_v2
npm install
npm run build
npm link
codegraph --help

Remove the local link when needed:

npm unlink -g @dvttvnp/codegraph-v2

After running any codegraph install ... command, restart your agent so it can load the MCP server.

Setup Option 1: Single Project

Use this when the current folder is one normal project or one git repository.

cd your-project
codegraph install --location local --target auto
codegraph init -i
codegraph status

What this does:

  • Adds project-local MCP configuration where supported.
  • Creates .codegraph/config.json.
  • Builds .codegraph/codegraph.db.
  • Keeps the configuration scoped to the current project.

Run a quick query:

codegraph query "PaymentService"
codegraph context "How does authentication work?"

Keep the index fresh manually:

codegraph sync

Remove CodeGraph from the project:

codegraph uninstall --location local --target auto
codegraph uninit

Setup Option 2: Multi-Repo Workspace

Use this when one umbrella folder contains many child projects, and each child project can be its own git repository.

cd your-workspace
codegraph install --location workspace --target auto
codegraph workspace init
codegraph workspace discover
codegraph workspace index
codegraph workspace status

What this does:

  • Creates .codegraph/workspace.json at the workspace root.
  • Discovers child projects using markers such as .git, package.json, pom.xml, go.mod, and Cargo.toml.
  • Indexes every enabled child project into that project's own .codegraph/codegraph.db.
  • Searches enabled projects from the workspace root through CLI and MCP.

Sync all enabled child projects:

codegraph workspace sync

Re-discover projects after adding or removing child repositories:

codegraph workspace discover

Remove CodeGraph from the workspace root and every enabled child project:

codegraph uninstall --location workspace --target auto
# or:
codegraph workspace uninstall --target auto

This removes CodeGraph-owned local agent config and deletes each managed .codegraph/ directory. Use --dry-run first if you want to preview every file and data directory that would be touched.

Example workspace manifest:

{
  "version": 1,
  "mode": "multi-project",
  "projects": [
    { "name": "api", "path": "api", "enabled": true },
    { "name": "web", "path": "web", "enabled": true },
    { "name": "legacy-service", "path": "legacy-service", "enabled": false }
  ],
  "scanIgnoredChildren": true,
  "maxDepth": 2,
  "workspaceExclude": ["**/node_modules/**", "**/target/**", "**/dist/**"],
  "projectMarkers": [".git", "package.json", "pom.xml", "go.mod", "Cargo.toml"]
}

Important workspace notes:

  • Set enabled: false to keep a project in the manifest but skip indexing and MCP search.
  • Keep scanIgnoredChildren: true when the workspace root .gitignore ignores child repositories but you still want CodeGraph to discover them.
  • Each child project's own .gitignore still controls which files are indexed inside that child project.
  • codegraph uninstall --location local --target auto only affects the current directory's agent config. Use --location workspace or codegraph workspace uninstall to clean the workspace root and enabled child projects, including their .codegraph/ data directories.

Local UI

Open the graph explorer from an initialized project:

cd your-project
codegraph ui

Open it from a workspace root that has .codegraph/workspace.json:

cd your-workspace
codegraph ui

Useful options:

codegraph ui --port 8732
codegraph ui --host 127.0.0.1
codegraph ui --project ./packages/api
codegraph ui --workspace .
codegraph ui --no-open

The UI binds to 127.0.0.1 by default and serves a local HTTP API plus static web assets. It shows project/workspace status, indexed files, symbol search results, node and edge details, source locations, and graph views for file dependencies, symbol neighborhoods, call graphs, type hierarchies, and impact radius. Sync, index, and workspace sync actions run through the UI job API and can also be run from the CLI.

Remote binding is disabled unless explicitly requested:

codegraph ui --host 0.0.0.0 --allow-remote --no-open

Use remote binding only on trusted networks.

Installer Safety

The v2 installer defaults to local or workspace-local setup. Global setup is available, but intentionally guarded because it edits user-wide agent files.

Preview a global install:

codegraph install --location global --force-global --dry-run

Apply a global install:

codegraph install --location global --force-global

Print instructions without writing files:

codegraph install --manual --target claude
codegraph install --print-config codex

Undo the latest global install backup:

codegraph install rollback

Safety rules:

  • Existing MCP servers and user instructions are preserved.
  • CodeGraph instructions are written only inside CODEGRAPH_START and CODEGRAPH_END marker blocks.
  • Global writes create backups before changing existing files.
  • Invalid JSON/JSONC global config is treated as unsafe and blocks the write.
  • Local and global uninstall remove only CodeGraph-owned MCP entries, permissions, and marker blocks.
  • Workspace uninstall reads .codegraph/workspace.json, removes those local config surfaces, deletes .codegraph/ data directories for the workspace root and enabled projects, skips disabled projects, and continues if one child project cannot be cleaned.

Common CLI Commands

Command Purpose
codegraph install Configure MCP integration for agents
codegraph install rollback Restore the latest global install backup
codegraph uninstall Remove CodeGraph-owned agent config
codegraph init -i Initialize and index a single project
codegraph index Rebuild the current project index
codegraph sync Incrementally sync the current project
codegraph status Show index health and statistics
codegraph ui Open the local graph explorer UI
codegraph query <text> Search indexed symbols
codegraph context <task> Build focused context for an AI task
codegraph files Show indexed file structure
codegraph affected <files...> Find tests affected by changed files
codegraph workspace init Create a workspace manifest
codegraph workspace discover Re-scan child projects
codegraph workspace index Index enabled workspace projects
codegraph workspace sync Sync enabled workspace projects
codegraph workspace status Show per-project workspace status
codegraph workspace uninstall Remove local agent config and .codegraph/ data from the workspace root and enabled child projects
codegraph serve --mcp Start the MCP server

MCP Tools

CodeGraph exposes these tools to MCP-compatible agents:

Tool Purpose
codegraph_search Find symbols by name
codegraph_context Build task-focused code context
codegraph_explore Inspect source for several related symbols in one call
codegraph_node Show symbol details, signature, and source
codegraph_callers Find what calls a symbol
codegraph_callees Find what a symbol calls
codegraph_impact Analyze the impact radius of a change
codegraph_files List indexed files
codegraph_status Check index health

In workspace mode, pass project or projectPath when the target child project is known:

{ "query": "PaymentService", "project": "payment-api" }
{ "symbol": "createPayment", "projectPath": "payment-api" }

If omitted, workspace-aware tools search all enabled projects and include projectName and projectPath in the result metadata.

Configuration

Single-project config lives at:

.codegraph/config.json

Workspace config lives at:

.codegraph/workspace.json

See the focused docs for details:

  • docs/WORKSPACE_MANIFEST.md
  • docs/INSTALLER_SAFETY.md
  • docs/MIGRATION_V1_TO_V2.md

Supported Languages

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

CodeGraph also extracts routes for common web frameworks such as Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, chi, gorilla/mux, Axum, actix, Rocket, ASP.NET, Vapor, React Router, SvelteKit, and Nuxt.

Troubleshooting

CodeGraph is not initialized

Run:

codegraph init -i

For workspace roots, run:

codegraph workspace init
codegraph workspace index

Workspace root has no symbols

This is expected for an umbrella workspace. The workspace root stores the manifest; each child project stores its own graph database.

Child repositories are ignored by root .gitignore

Keep scanIgnoredChildren: true in .codegraph/workspace.json, then run:

codegraph workspace discover
codegraph workspace index

Global install was unsafe or failed

Use dry-run first, fix the reported config file, then run the install again:

codegraph install --location global --force-global --dry-run

If a backup was created and you need to undo it:

codegraph install rollback

Indexing is slow

Check that large generated folders are excluded, then verify the SQLite backend:

codegraph status

Backend: native is the fast path. Backend: wasm works, but can be slower and may require rebuilding better-sqlite3 for best performance:

npm rebuild better-sqlite3

License

MIT