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.

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

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
docs		docs
scripts		scripts
src		src
test		test
vscode-extension		vscode-extension
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Graphite

Table of Contents

Installation

Quick Start

Usage: CLI

Global Options

graphite index

graphite status

graphite query <tool> [args...]

Query Options

graphite serve

Usage: MCP Server (AI Assistants)

GitHub Copilot (VS Code)

Claude Desktop

Claude Code (CLI)

Cursor

Any MCP Client

Usage: VS Code Extension

Sidebar Panels

Commands

Context Menu

Auto-Indexing

Copilot Integration

Extension Settings

Query Reference

Configuration

.graphiteignore

tsconfig.json Path Aliases

Architecture

Supported Languages

Limitations

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`graphite index`

`graphite status`

`graphite query <tool> [args...]`

`graphite serve`

`.graphiteignore`

`tsconfig.json` Path Aliases

Packages