CodeGraph (Rust Engine)

A high-performance local AST query engine and file relationship indexer. CodeGraph parses your source files using Tree-sitter, resolves imports and calls, and builds an active queryable relationship graph inside a local SQLite database (.codegraph/intelligence.db).

CodeGraph is designed specifically to assist developer AI agents (such as Claude Code, Antigravity, or Cursor) in navigating complex codebases instantly without making recursive model calls to read files, saving credits and token space.

🚀 Features

• Incremental Watcher: Runs in the background (codegraph watch), monitoring file edits and saving updates incrementally in real-time.
• 10 Supported Languages: Native tree-sitter parsers for JavaScript, TypeScript, TSX, Python, Go, Rust, C, C++, Java, and Prisma.
• Smart Relative Import Resolution: Automatically resolves JS/TS relative imports (../x/y) to actual project file nodes.
• Undirected Path Tracing: BFS path finder (codegraph trace) traverses relations in both directions, displaying full caller/importer connectivity.
• Interactive Visualization Dashboard: Launch a local dashboard (codegraph viz) to interactively explore your project graph.

📦 Installation

To install CodeGraph globally on your system:

Option A: Via Cargo (Rust Package Manager)

If you have Rust/Cargo installed, run:

cargo install codegraph-cli

Option B: Via NPM (Node Package Manager)

If you have Node.js/NPM installed, you can install the platform-specific pre-compiled binary wrapper globally:

npm install -g @codegraph-cli/cli

Option C: Via Pre-compiled Binaries (GitHub Releases)

1. Download the pre-compiled binary for your operating system from the Releases tab:
   • Windows: codegraph.exe
   • macOS: codegraph-darwin
   • Linux: codegraph-linux
2. Move the binary into a folder in your system's environment variables PATH (e.g. /usr/local/bin or C:\Program Files\bin).

🛠️ CLI Cheat Sheet & Reference

1. Setup & Scaffolding

• codegraph init
  Scaffolds the default config file .codegraph/architecture.json and local AI agent workflow instructions in .agent/.
• codegraph build
  Re-parses the entire workspace and builds the local SQLite database at .codegraph/intelligence.db.
• codegraph rebuild
  Forcibly deletes old .codegraph/ assets and indexes from scratch.
• codegraph set-env <key> <val>
  Saves settings (e.g. Gemini API key for explain/ask capabilities):

  codegraph set-env GEMINI_API_KEY "your-key"

2. Exploration & Analysis

• codegraph trace <from> <to>
  BFS-traverses import, call, and containment edges (both forward and reverse) to trace the shortest path connecting two symbols.

  codegraph trace "AuthService" "PrismaService"

• codegraph dependents <symbol>
  Lists all symbols (classes, methods, variables, files) that depend on or call <symbol>.
• codegraph search "<query>"
  High-speed Full-Text Search (FTS5) for symbols or files.
• codegraph entrypoints
  Identifies root files in your codebase (files not imported by any other file).
• codegraph services
  Lists boundaries defined in architecture.json.

3. Monitoring & Diagnostics

• codegraph watch
  Starts a background listener that recursively watches files and incrementally updates database records in real-time as edits are saved.
• codegraph status
  Displays total project node, edge, and service counts.
• codegraph doctor
  Performs integrity checks, lists node and relationship breakdowns, and prints file coverage percentage.
• codegraph export [-o file.json]
  Exports the entire SQLite graph nodes and edges array into JSON format.
• codegraph viz [--port N]
  Launches local Axum server (default port 3000) hosting a premium interactive network visualizer.

📂 Configuration (architecture.json)

You can group files into architectural boundaries (e.g. backend, frontend) by configuring .codegraph/architecture.json:

{
  "services": [
    { "name": "backend", "path": "server" },
    { "name": "frontend", "path": "client" }
  ]
}

This isolates services and allows filtering search queries by service using --service <name>.