Graphite

A local-first semantic code graph for TypeScript and JavaScript. Index your project once, then query its structure — who calls what, where things are defined, how files depend on each other — from the CLI, an MCP-enabled AI assistant, or the VS Code sidebar.

Table of Contents

• Installation
• Quick Start
• Usage: CLI
• Usage: MCP Server (AI Assistants)
• Usage: VS Code Extension
• Query Reference
• Configuration
• Architecture
• Supported Languages
• Limitations
• Contributing
• License

Installation

# Install locally in your project
npm install graphite

# Or run without installing
npx graphite index

For the VS Code extension, install from the vscode-extension/ directory:

cd vscode-extension
npm install && npm run compile
# Then press F5 in VS Code to launch the Extension Development Host

Quick Start

# 1. Index your project (creates .graphite/index.db)
npx graphite index

# 2. Find where a function is defined
npx graphite query find_definition processPayment

# 3. Find who calls it
npx graphite query find_callers processPayment

# 4. Start the MCP server for AI assistants
npx graphite serve

Usage: CLI

The CLI has four commands: index, query, status, and serve.

Global Options

| Flag | Description | |------|-------------| | --project-root <path> | Project root (default: current directory) | | --json | Output raw JSON instead of human-readable tables | | --verbose | Show timing information |

graphite index

Index (or re-index) the current project. Uses content hashing for incremental updates — unchanged files are skipped.

# Index the current directory
graphite index

# Index a specific project
graphite index --project-root /path/to/project

# Get JSON output for scripting
graphite index --json

Output example:

Indexed 142/142 files (38 new, 12 updated, 2 deleted, 90 skipped, 0 failed)

graphite status

Show the current state of the index.

graphite status

Output example:

Graphite Status
  Files   142
  Nodes   Function:89, Class:23, Method:67, Interface:12, TypeAlias:8, Variable:34
  Edges   CONTAINS:156, IMPORTS:78, EXPORTS:102, CALLS:213, EXTENDS:5, IMPLEMENTS:8

graphite query <tool> [args...]

Run any of the 10 query tools. The first positional argument after the tool name is the primary argument (usually a symbol name or file path). The second is an optional secondary argument.

# Find a symbol's definition
graphite query find_definition UserService

# Search symbols by prefix
graphite query search_symbols handle

# Get the structure of a file
graphite query get_file_structure src/services/auth.ts

# Get a file's exports
graphite query get_exports src/utils/index.ts

# Find callers of a function (with depth)
graphite query find_callers processPayment --depth 3

# Find callees of a function
graphite query find_callees handleRequest --depth 2

# Find implementations of an interface
graphite query find_implementations EventHandler

# Analyze blast radius of changing a symbol
graphite query analyze_impact createUser --max-depth 5

# Find the import path between two files
graphite query find_dependency_path src/app.ts src/db/client.ts

# Get overall graph statistics
graphite query get_graph_stats

Query Options

| Flag | Applies to | Description | |------|-----------|-------------| | --depth <n> | find_callers, find_callees | Traversal depth (default: 1) | | --max-results <n> | find_callers, find_callees, search_symbols | Max results (default: 50) | | --max-depth <n> | analyze_impact | Max reverse-traversal depth (default: 5) |

graphite serve

Start the MCP server on stdio. This is what AI assistants connect to.

graphite serve
graphite serve --project-root /path/to/project

The server auto-indexes the project on the first tool call if no index exists.

Usage: MCP Server (AI Assistants)

Graphite exposes all 10 query tools as an MCP server. Any MCP-compatible client can use it.

GitHub Copilot (VS Code)

Option A: Install the VS Code extension (recommended)

The Graphite VS Code extension automatically registers the MCP server with Copilot. Install the extension and it works out of the box — Copilot can immediately use all 10 tools.

Option B: Manual configuration

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "graphite": {
        "type": "stdio",
        "command": "npx",
        "args": ["graphite", "serve", "--project-root", "${workspaceFolder}"]
      }
    }
  }
}

Or add a .vscode/mcp.json to your project:

{
  "servers": {
    "graphite": {
      "type": "stdio",
      "command": "npx",
      "args": ["graphite", "serve"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "graphite": {
      "command": "npx",
      "args": ["graphite", "serve", "--project-root", "/absolute/path/to/your/project"]
    }
  }
}

Claude Code (CLI)

claude mcp add graphite -- npx graphite serve --project-root /path/to/project

Cursor

Add to Cursor's MCP config (Settings → MCP):

{
  "mcpServers": {
    "graphite": {
      "command": "npx",
      "args": ["graphite", "serve", "--project-root", "/path/to/project"]
    }
  }
}

Any MCP Client

Graphite uses stdio transport. Spawn the process and communicate via stdin/stdout:

npx graphite serve --project-root /path/to/project

Usage: VS Code Extension

The extension lives in vscode-extension/ and provides a graphical interface to the code graph.

Sidebar Panels

Open the Graphite sidebar (type-hierarchy icon in the activity bar):

• File Structure — Shows all symbols in the current file (functions, classes with methods, interfaces, types, enums, variables). Click any symbol to jump to it. Updates automatically when you switch files.
• Callers — Shows functions that call the selected symbol. Use right-click → "Find Callers" to populate.
• Callees — Shows functions called by the selected symbol. Use right-click → "Find Callees" to populate.

Commands

Open the Command Palette (Cmd+Shift+P) and type "Graphite":

| Command | What it does | |---------|--------------| | Graphite: Index Project | Manually trigger a full re-index | | Graphite: Show Index Status | Opens a document showing file/node/edge counts | | Graphite: Find Callers | Finds callers of the word under cursor, shows in sidebar | | Graphite: Find Callees | Finds callees of the word under cursor, shows in sidebar | | Graphite: Find Definition | Jumps to definition (or shows a picker if multiple) | | Graphite: Find Implementations | Shows implementations of an interface/class | | Graphite: Analyze Impact | Opens blast radius analysis for the word under cursor | | Graphite: Refresh Explorer | Refreshes all sidebar panels |

Context Menu

Right-click in any TypeScript/JavaScript file to access:

• Find Callers
• Find Callees
• Find Implementations
• Analyze Impact

Auto-Indexing

By default, the extension indexes the project on activation and re-indexes when you save a .ts/.js file. Disable with:

{
  "graphite.autoIndex": false
}

Copilot Integration

When the extension is active in VS Code 1.99+, it automatically registers the Graphite MCP server with GitHub Copilot. Copilot can then use all 10 tools in chat without any manual MCP configuration.

Extension Settings

| Setting | Default | Description | |---------|---------|-------------| | graphite.autoIndex | true | Auto-index on activation and file changes | | graphite.maxDepth | 3 | Default depth for caller/callee traversal | | graphite.maxResults | 50 | Maximum results for queries |

Query Reference

| Tool | Description | Required Args | Optional Args | |------|-------------|--------------|---------------| | find_definition | Locate where a symbol is defined | symbol | type | | search_symbols | Prefix search across all symbols | query | type, max_results | | get_file_structure | All symbols in a file, grouped by type | file_path | — | | get_exports | Public exports of a file or module | file_or_module | — | | find_callers | Who calls this function (multi-hop) | symbol | depth, max_results | | find_callees | What does this function call (multi-hop) | symbol | depth, max_results | | get_graph_stats | Summary stats for the entire graph | — | — | | find_implementations | Classes implementing an interface/extending a class | symbol | — | | analyze_impact | Blast radius: all affected files/symbols | symbol | max_depth | | find_dependency_path | Shortest import chain between two files | source_file, target_file | — |

Configuration

.graphiteignore

Place a .graphiteignore file in your project root (same syntax as .gitignore) to exclude additional paths from indexing:

# Skip generated code
src/generated/**
*.d.ts

# Skip test fixtures
test/fixtures/**

The indexer always skips: node_modules, .git, .graphite, dist, build, coverage.

tsconfig.json Path Aliases

Graphite reads your tsconfig.json and respects compilerOptions.paths and baseUrl for import resolution:

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@utils/*": ["utils/*"],
      "@services/*": ["services/*"]
    }
  }
}

Imports like import { foo } from '@utils/helpers' will resolve correctly.

Architecture

src/
  indexer/        Tree-sitter parsing, AST extraction, cross-file stitching
  storage/        SQLite schema, migrations, read/write layers
  query/          10 query functions (callers, callees, impact, etc.)
  cli/            Commander.js CLI with 4 commands
  mcp/            MCP server, tool registry, LLM response formatting

vscode-extension/
  src/            VS Code extension: sidebar, commands, MCP registration

• Indexer: tree-sitter parses TS/JS → extracts functions, classes, imports, exports → resolves cross-file calls and inheritance → stores as nodes + edges in SQLite
• Storage: SQLite with WAL mode, FTS5 for symbol search, prepared statements for performance
• Query: SQL queries using recursive CTEs for multi-hop traversal
• MCP: Stdio transport, auto-index on first call, response truncation for LLMs

Supported Languages

| Language | Extensions | |----------|-----------| | TypeScript | .ts, .tsx | | JavaScript | .js, .jsx, .mjs, .cjs |

Limitations

• TypeScript and JavaScript only (no Python/Go/Rust yet)
• No real-time file watcher (re-index on save via VS Code extension, or run graphite index manually)
• Local projects only (no remote/SSH indexing)
• Dynamic import() expressions are not resolved
• CommonJS module.exports = patterns have limited support

Contributing

git clone <repo>
cd graphite
npm install
npm run build
npm test

• See docs/PRD.md for the product requirements
• See docs/TASKS.md for the task list and architecture notes
• Run benchmarks: npm run benchmark:indexer

License

MIT