# Graph-It-Live
**The AI-first dependency intelligence platform for VS Code.**
See your codebase the way your AI does β as a graph.
[](https://marketplace.visualstudio.com/items?itemName=magic5644.graph-it-live)
[](https://marketplace.visualstudio.com/items?itemName=magic5644.graph-it-live)
[](https://open-vsx.org/extension/magic5644/graph-it-live)
[](https://open-vsx.org/extension/magic5644/graph-it-live)
[](https://www.npmjs.com/package/@magic5644/graph-it-live)
[](https://modelcontextprotocol.io)
[](https://github.com/magic5644/Graph-It-Live/blob/main/LICENSE)
[](https://github.com/magic5644/Graph-It-Live)
## Star History
[](https://www.star-history.com/?repos=magic5644%2Fgraph-it-live&type=timeline&logscale=&legend=top-left)
---
Graph-It-Live turns your codebase into a live, interactive dependency graph β one that both **you** and your **AI assistant** can query in real time.
Built for **architects** who need the big picture and **developers** who need to ship safely, it combines three analysis layers in one tool:
| Layer | What you see | Powered by |
|-------|-------------|------------|
| **File Graph** | File-to-file import relationships | Regex + AST parsing |
| **Symbol View** | Function/class call hierarchy inside a file | AST (ts-morph) |
| **Live Call Graph** | Cross-file symbol call relationships | Tree-sitter + SQLite |
All three layers are also exposed to AI via a **22-tool MCP server**, so your assistant can answer architecture questions with zero hallucination.
---
## Why Graph-It-Live?
## Graph-It Review Gate
`graph-it review-pr --base origin/main --format markdown` performs a deterministic, local Git-diff review before CI. It compares exported TypeScript signatures and, when the warmed local index supports them, reports cycle and unused-export evidence, known dependents, and conventional test-file candidates. Every score factor and unavailable analysis capability is explicit; bounded work is marked partial rather than complete. The composite Action is informational by default; set `fail-on-risk: high` or `critical` to gate a PR. It sends only a sanitized report to GitHub, verifies GitHub API responses, and emits an encoded VS Code link only when a workspace-relative risky symbol exists.
The Action does not trigger itself: add a consumer workflow such as [`docs/examples/graph-it-review-gate.yml`](docs/examples/graph-it-review-gate.yml). It installs `@magic5644/graph-it-live@latest` into an isolated temporary directory and analyzes the consumer checkout; it never runs `npm ci` or builds that checkout. Set `cli-version` to an npm version, tag, or range to override `latest`. The Action logs and exposes the resolved `cli-version`, and rejects an installed version below `1.13.0`.
```yaml
- uses: magic5644/Graph-It-Live/.github/actions/graph-it-review-gate@v1.13.0
with:
token: ${{ secrets.GITHUB_TOKEN }}
cli-version: 1.13.2 # optional; omitted means npm latest
comment: true
fail-on-risk: high
```
Use `pull_request`, not `pull_request_target`, for untrusted PR code. Fork workflows should set `comment: false`; remove `pull-requests: write` when comments are disabled. The npm publication of `1.13.0`, the public `npx` verification, and the immutable Git tag `v1.13.0` are manual post-merge release steps, not part of this PR.
| Pain point | Without Graph-It-Live | With Graph-It-Live |
|---|---|---|
| "What breaks if I touch this file?" | Grep + hope | One-click reverse dependency lookup |
| "Explain this module's architecture" | Read 30 files | AI generates a codemap in seconds |
| "Are there circular deps?" | Manual tracing | Auto-detected, red-highlighted cycles |
| "What calls this function across the project?" | Global search + noise | Live Call Graph with depth control |
| "Onboard a new developer" | Hours of walkthroughs | Interactive graph + AI-generated overviews |
---
## Table of Contents
- [Graph-It-Live](#graph-it-live)
- [Why Graph-It-Live?](#why-graph-it-live)
- [Table of Contents](#table-of-contents)
- [π€ Supercharge Your AI Assistant](#-supercharge-your-ai-assistant)
- [What your AI can do with Graph-It-Live](#what-your-ai-can-do-with-graph-it-live)
- [πΊοΈ Codemap Generation *(New)*](#οΈ-codemap-generation-new)
- [π File Logic Analysis *(New)*](#-file-logic-analysis-new)
- [ποΈ Features for Humans](#οΈ-features-for-humans)
- [File Dependency Graph](#file-dependency-graph)
- [Symbol-Level Drill-Down](#symbol-level-drill-down)
- [π· Live Call Graph *(New)*](#-live-call-graph-new)
- [Unused Dependency Filter](#unused-dependency-filter)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [From Marketplace](#from-marketplace)
- [From Open VSX Registry](#from-open-vsx-registry)
- [Usage](#usage)
- [Configuration](#configuration)
- [Performance Profiles](#performance-profiles)
- [All Settings](#all-settings)
- [Standalone CLI](#standalone-cli)
- [Agent Skill](#agent-skill)
- [MCP Server (AI/LLM Integration)](#mcp-server-aillm-integration)
- [Setup](#setup)
- [Available Tools](#available-tools)
- [TOON Format (Token-Optimized Output)](#toon-format-token-optimized-output)
- [Native LM Tools (Copilot Agent Mode)](#native-lm-tools-copilot-agent-mode)
- [Manual MCP Server Configuration](#manual-mcp-server-configuration)
- [VS Code / VS Code Insiders](#vs-code--vs-code-insiders)
- [Cursor](#cursor)
- [Claude Desktop](#claude-desktop)
- [Development / Local Testing](#development--local-testing)
- [Windsurf](#windsurf)
- [Antigravity](#antigravity)
- [Development](#development)
- [Quick Start](#quick-start)
- [Project Structure](#project-structure)
- [Build \& Test Commands](#build--test-commands)
- [WASM Architecture](#wasm-architecture)
- [Architecture](#architecture)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [License](#license)
- [Acknowledgements](#acknowledgements)
- [Author](#author)
---
## π€ Supercharge Your AI Assistant
Stop pasting file paths and explaining your project structure. Graph-It-Live exposes **23 powerful dependency analysis tools** directly to your AI assistant via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), and **22 native LM Tools** directly in Copilot Agent mode (no MCP setup required).
**Works with:** GitHub Copilot, Claude (Desktop & Code), Cursor, Windsurf, Antigravity, and any MCP-compatible client.
### What your AI can do with Graph-It-Live
| You ask | AI uses | Result |
|---------|---------|--------|
| *"Map out the architecture of the auth module"* | `crawl_dependency_graph` | Full dependency tree as structured data |
| *"What breaks if I change User.ts?"* | `find_referencing_files` | All dependent files with O(1) lookup |
| *"Give me an overview of Spider.ts"* | `generate_codemap` | Exports, internals, deps, dependents, call flow β in one call |
| *"What calls formatDate() across the project?"* | `get_symbol_callers` | All callers with instant lookup |
| *"Show function-level flow in this file"* | `analyze_file_logic` | Intra-file call hierarchy |
| *"Analyze the impact of changing calculateTotal's signature"* | `get_impact_analysis` | Breaking change detection + all affected callers |
| *"Find unused exports in the codebase"* | `find_unused_symbols` | Dead code detection |
| *"Are there circular dependencies?"* | `crawl_dependency_graph` | Cycle detection built in |
| *"How does Spider crawl files?"* | `query_natural_language` | Natural language answer synthesised from the call graph |
GitHub Copilot querying Graph-It-Live to analyze a project's dependency structure
### πΊοΈ Codemap Generation *(New)*
The `graphitlive_generate_codemap` tool gives your AI a **complete structural overview of any file** in a single call β no more chaining 5 different tools.
**What it returns:**
```
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β Spider.ts (247 lines, TypeScript) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β EXPORTS: Spider, SpiderOptions β
β INTERNALS: crawlFile, resolveImport, visitNode β
β DEPENDENCIES: Parser.ts, PathResolver.ts, ... β
β DEPENDENTS: SpiderBuilder.ts, extension.ts β
β CALL FLOW: crawl β crawlFile β resolveImport β
β CYCLES: none β
βββββββββββββββββββββββββββββββββββββββββββββββββββ
```
**Use cases:**
- **Onboarding:** *"Give me an overview of every file in src/analyzer/"* β AI maps the full module
- **Pre-refactor audit:** *"Generate codemaps for all files that import UserService"* β understand coupling before changing
- **Documentation:** *"Create architecture docs from codemaps"* β structured data β Markdown in seconds
- **Code review:** *"What does this new file export and who depends on it?"* β instant context
> **Token-efficient:** Output uses a compact format optimised for LLM consumption. Combine with `format: "toon"` for up to 60% token savings.
### π File Logic Analysis *(New)*
The `graphitlive_analyze_file_logic` tool reveals the **call hierarchy inside a single file** β which functions call which, in what order.
**Example prompt:** *"Show me how data flows through src/mcp/mcpServer.ts"*
**AI response (powered by the tool):**
```
Entry points: initializeServer(), main()
βββ initializeServer()
βββ registerAllTools() [call #1]
βββ setupFileWatcher() [call #2]
βββ startListening() [call #3]
βββ handleToolCall()
βββ validateWorkspace()
βββ invokeWorker()
```
**Use cases:**
- **Understand complex files** without reading every line
- **Find entry points** and trace execution paths
- **Detect internal cycles** (recursive calls between functions)
- **Refactoring confidence** β see what internal logic is affected
---
## ποΈ Features for Humans
### File Dependency Graph
The core of Graph-It-Live: a **real-time interactive graph** showing file-to-file import relationships across your project.
- **Multi-language:** TypeScript, JavaScript, Python, Rust, C#, Go, Java, Vue, Svelte, GraphQL
- **Cycle detection:** Circular dependencies highlighted with red dashed lines and badges
- **Smart navigation:** Click any node to open the file; expand/collapse dependencies dynamically
- **Reverse lookup:** Right-click β "Find Referencing Files" for instant reverse dependency discovery
- **Background indexing:** Workspace indexed in a background thread for O(1) queries
Interactive file dependency graph with expand/collapse and cycle detection
### Symbol-Level Drill-Down
Go beyond file dependencies β **drill into any file to visualize function-to-function and class-to-class call relationships** powered by AST analysis (ts-morph for TypeScript/JavaScript, tree-sitter for Python/Rust).
**How it works:**
1. **From the File Graph:** Double-click any file node (or right-click β "Drill Down")
2. **Instant symbol graph:** See an interactive tree showing:
- **Functions** in vibrant blue
- **Classes** in deep purple
- **Variables/Constants** in amber
- **β calls** β outgoing calls from each symbol
- **β called by** β incoming callers (including from other files)
- **Recursive calls** with cycle badges
3. **Click-to-navigate:** Click any symbol to jump to its definition
4. **Breadcrumb nav:** `Project > folder > file.ts` β one click to return to file view
**Multi-language support (symbol drill-down):**
- TypeScript / JavaScript (ts-morph AST)
- Python (tree-sitter WASM)
- Rust (tree-sitter WASM)
> **Note:** C#, Go, and Java are supported at the **file dependency graph level** (L1) and the **Live Call Graph** level (L3). Symbol drill-down (intra-file view, L2) is not yet available for these languages.
**Benefits:**
- **Understand code flow** without reading every line
- **See who calls your exports** β incoming dependencies from other files
- **Detect recursive calls** β cycle detection with visual indicators
- **Refactoring confidence** β visualize all internal dependencies
Symbol drill-down: purple classes, blue functions, amber variables with call relationships
### π· Live Call Graph *(New)*
The **Live Call Graph** visualises **cross-file symbol call relationships** across your entire project in a Cytoscape.js panel backed by an in-memory SQLite database.
Unlike the Symbol View (which shows relationships *within* a single file via AST), the Call Graph shows how symbols call each other *across files* using Tree-sitter AST extraction.
**Key capabilities:**
| Feature | Description |
|---------|-------------|
| **Cross-file analysis** | See function calls that span multiple files |
| **Neighbourhood queries** | BFS expansion from any symbol, configurable depth (1β5) |
| **Cycle detection** | Mutual-recursion and self-recursion highlighted in red |
| **Compound node layout** | Symbols grouped by folder for visual clarity |
| **Call order numbering** | CALLS edges numbered to show invocation order |
| **Theme-aware** | Adapts to dark, light, and high-contrast VS Code themes |
| **Live refresh** | On file save, the graph updates automatically (500ms debounce) |
| **Filter legend** | Toggle visibility by symbol type (function, class, variable) and by folder |
**How to use:**
1. Open a source file and place the cursor on a symbol (function, class, methodβ¦). Then open the command palette β `Graph-It-Live: Show Call Graph` or click the "Call Graph" button in the sidebar toolbar
2. The extension indexes your workspace (Tree-sitter AST extraction)
3. Click any symbol to re-center the neighbourhood
4. **Drag any node** (symbol or entire file/folder group) to rearrange the layout freely
5. Use the depth slider to expand or narrow the view
6. Filter by symbol type or folder using the legend overlay
Live Call Graph β cross-file symbol relationships with cycle detection and folder grouping
**Language support (Live Call Graph):**
- TypeScript / JavaScript (including Vue, Svelte)
- Python
- Rust
- C# *(New)*
- Go *(New)*
- Java *(New)*
### Unused Dependency Filter
Smart filter to show only dependencies that are actually used in your code. Toggle between showing all imports or filtering unused ones with a single click.
- **Hide mode:** Unused dependencies completely removed from the graph
- **Dim mode:** Unused dependencies shown with reduced opacity and dashed lines
Hide mode: Unused dependencies completely removed
Dim mode: Unused dependencies shown with reduced opacity
---
## Prerequisites
- **Node.js**: v22 or higher
- **VS Code**: v1.96.0 or higher
**No build tools required** β the extension uses WebAssembly (WASM) parsers. No Python, C++ compiler, or native compilation needed.
## Installation
### From Marketplace
Search for **"Graph-It-Live"** in the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`), or install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=magic5644.graph-it-live).
### From Open VSX Registry
Also available on the [Open VSX Registry](https://open-vsx.org/extension/magic5644/graph-it-live) for VSCodium and other compatible editors.
## Usage
1. **Open a Project** β TypeScript, JavaScript, Python, Rust, C#, Go, Java, Vue, Svelte, or GraphQL
2. **Open the Graph** β Click the Graph-It-Live icon in the Activity Bar, or run `Graph-It-Live: Show Dependency Graph`
3. **Interact:**
- **Click** a node β open the file
- **Double-click** a node β drill down to symbol view
- **Right-click** a node β expand, collapse, find referencing files
- **Command palette** β `Show Call Graph` for cross-file symbol analysis
---
## Configuration
### Performance Profiles
Choose a performance profile based on your machine:
| Profile | RAM | Concurrency | Max Edges | Cache |
|---------|-----|-------------|-----------|-------|
| **`default`** *(recommended)* | 4-8 GB | 4 | 2000 | 500/200 |
| **`low-memory`** | < 4 GB | 2 | 1000 | 200/100 |
| **`high-performance`** | 16 GB+ | 12 | 5000 | 1500/800 |
| **`custom`** | Any | Manual | Manual | Manual |
Set via `graph-it-live.performanceProfile` in VS Code settings.
With **`custom`** profile, you can fine-tune:
- `unusedAnalysisConcurrency` (1-16)
- `unusedAnalysisMaxEdges` (0 = unlimited)
- `maxCacheSize` (50-2000)
- `maxSymbolCacheSize` (50-1000)
- `indexingConcurrency` (1-16)
### All Settings
Configure how unused dependencies are displayed: hide (remove completely) or dim (show with reduced opacity)
| Setting | Default | Description |
| :----------------------------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `graph-it-live.performanceProfile` | `default` | Performance preset: `default`, `low-memory`, `high-performance`, or `custom` for manual control. |
| `graph-it-live.enableMcpServer` | `false` | Enable the MCP server for AI/LLM integration. |
| `graph-it-live.enableMcpDebugLogging` | `false` | Privacy-sensitive debug logging for MCP (creates `~/mcp-debug.log`). Enable only for troubleshooting. |
| `graph-it-live.maxDepth` | `50` | Maximum dependency depth to analyze. |
| `graph-it-live.excludeNodeModules` | `true` | Exclude `node_modules` imports from the graph. |
| `graph-it-live.ignoreTypeImports` | `false` | Ignore TypeScript type-only imports/exports in the dependency graph. A VS Code restart may be required after changing this setting. |
| `graph-it-live.enableBackgroundIndexing` | `true` | Enable background indexing for O(1) reverse dependency lookups. |
| `graph-it-live.persistIndex` | `false` | Persist reverse index to disk for faster startup. |
| `graph-it-live.indexingConcurrency` | `4` | Parallel file processing during indexing (1-16). |
| `graph-it-live.indexingStartDelay` | `1000` | Delay (ms) before starting background indexing after activation. |
| `graph-it-live.logLevel` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error`, or `none`. |
| `graph-it-live.unusedDependencyMode` | `hide` | How to display unused dependencies: `hide` or `dim`. |
| `graph-it-live.unusedAnalysisConcurrency` | `4` | Parallel file analysis for unused detection (1-16). |
| `graph-it-live.unusedAnalysisMaxEdges` | `2000` | Skip auto unused analysis above this edge count (0 = no limit). |
| `graph-it-live.persistUnusedAnalysisCache` | `false` | Cache unused analysis results to disk. |
| `graph-it-live.maxUnusedAnalysisCacheSize` | `200` | Max cached unused analysis results (LRU eviction). |
| `graph-it-live.maxCacheSize` | `500` | Max cached file dependency analyses. |
| `graph-it-live.maxSymbolCacheSize` | `200` | Max cached symbol analysis results. |
| `graph-it-live.preIndexCallGraph` | `true` | Pre-index the call graph database at startup for near-instant first query. |
| `graph-it-live.symbolViewLayout` | `hierarchical` | Layout for symbol drill-down: `hierarchical`, `force-directed`, or `radial`. |
---
## Standalone CLI
Graph-It-Live is also available as a standalone npm package β no VS Code required.
```bash
npm install -g @magic5644/graph-it-live
```
After install, `graph-it` is available on your PATH:
```bash
graph-it --version # Show installed version
graph-it --help # Full help with MCP config snippets
graph-it scan # Index/re-index the workspace
graph-it summary # Workspace overview
graph-it summary # Per-file codemap (exports, internals, deps, call flow)
graph-it trace # Trace execution flow from an entry symbol
graph-it explain # File logic analysis β intra-file call hierarchy
graph-it path # Full dependency graph from a file
graph-it check # Scan whole workspace for dead code (unused exports)
graph-it check # Scan a subdirectory for dead code
graph-it check # Detect unused exported symbols in a single file
graph-it query "" # Natural language query over the call graph (LLM or heuristic fallback)
graph-it wiki # Generate a navigable markdown wiki from the call graph
graph-it serve # Launch MCP stdio server (for AI clients)
graph-it tool --list # List all 22 CLI analysis tools
graph-it tool [args] # Run any MCP tool directly from the terminal
graph-it export [path] [--format html] # Export graph as standalone HTML (vis.js)
graph-it update # Update graph-it to the latest version
graph-it install # Symlink the binary into your system PATH (opt-in)
```
**Without installing globally:**
```bash
npx @magic5644/graph-it-live scan
npx @magic5644/graph-it-live serve
```
**Output formats:** All analysis commands support `--format json|toon|markdown`. Use `toon` for AI consumption (30β60% token savings). The `trace` and `path` commands additionally support `--format mermaid` to generate a Mermaid diagram of the call or dependency flow:
```bash
graph-it summary --format toon
graph-it path --format markdown
graph-it path --format mermaid # β Mermaid flowchart of dependency graph
graph-it trace --format mermaid # β Mermaid sequence/flowchart of execution trace
```
Example `--format mermaid` output for `graph-it path src/index.ts`:
```mermaid
graph LR
src/index.ts --> src/app.ts
src/app.ts --> src/router.ts
src/app.ts --> src/db.ts
```
This output can be pasted directly into any Markdown renderer (GitHub, Notion, VS Code Preview, etc.) or piped to a diagramming tool.
### Analyze Locally. Send Less Context.
Graph-It-Live reduces the context an AI assistant needs to inspect. Instead of sending source files or a broad repository dump to a model, use the CLI or MCP tools to ask for the specific dependency, symbol, caller, impact, or call-graph result you need.
The analysis happens locally. Graph-It-Live builds its index and extracts code structure with AST analysis and Tree-sitter, then computes graph traversal, reverse dependencies, and impact analysis in the local process. Architecture, codemap, impact, and call-graph tools do not need an LLM to calculate their results.
For AI-facing workflows, request `toon` output when the result contains structured lists or graphs. TOON (Token-Oriented Object Notation) removes repeated JSON field names while retaining the data an agent needs. This compounds the main saving: targeted local analysis first, compact structured output second.
The practical alternative is often much larger: pass a tool result to the model rather than the source files, imports, and unrelated modules it would otherwise need to reconstruct the same relationship. The exact reduction depends on the repository and the question. Measure it for your workflow by comparing the bytes or characters of the Graph-It-Live output with the raw source/context you would otherwise provide.
Run `npm run test:context-economy` to produce a reproducible JSON-versus-TOON corpus for architecture, codemap, impact, and call-graph analysis. Its report records bytes, characters, and `chars/4` token estimates separately from actual `llmUsage`. These are representation estimates, not provider billing tokens or a universal cost-saving guarantee.
The optional `query` command is deliberately narrower: a configured LLM can extract search keywords, but graph scoring and traversal stay local. Without provider credentials, it uses the heuristic keyword fallback.
**Workspace flag:** Use `--workspace ` (or `-w`) to specify the project root explicitly; defaults to the current working directory.
**Use as MCP server (no VS Code):** Run `graph-it serve` and point your AI client at it β see [Manual MCP Server Configuration](#manual-mcp-server-configuration).
**Interactive REPL:** Run `graph-it` with no arguments to enter interactive mode. Type `/query how does X work` to ask natural language questions about your codebase (no quotes needed). Use `/wiki` to generate a navigable markdown wiki from the call graph. Other slash commands: `/trace`, `/summary`, `/architecture`, `/check`, `/cycles`, `/export` (export dependency graph as standalone HTML), `/format`, `/help`.
**Full CLI reference:** See **[docs/CLI.md](docs/CLI.md)** for complete documentation on every command, all options, output format examples, advanced workflows, and the full MCP tools reference.
---
## Agent Skill
A **Graph-It-Live skill** is available for AI agents (GitHub Copilot, Claude Code, Cursor, and others). It gives your agent pre-built knowledge of all Graph-It-Live tools, workflows, and best practices β so it can use the extension and CLI without any manual guidance.
Install it with:
```bash
npx skills add magic5644/skills/graph-it-live
```
Once installed, your agent automatically knows how to query the dependency graph, use MCP tools, generate codemaps, detect breaking changes, and more.
---
## MCP Server (AI/LLM Integration)
Graph-It-Live includes an optional **MCP server** that exposes its full analysis engine to AI assistants and LLMs.
### Setup
**Option A β VS Code extension:**
1. Set `graph-it-live.enableMcpServer` to `true` in VS Code settings
2. The server starts automatically when the extension activates
3. Your AI assistant detects the tools via MCP auto-discovery
**Option B β Standalone CLI (no VS Code required):**
1. Install: `npm install -g @magic5644/graph-it-live`
2. Run `graph-it serve` β starts an MCP stdio server pointing at your current directory
3. Configure your AI client to invoke `graph-it serve` as the MCP server command (see [Manual MCP Server Configuration](#manual-mcp-server-configuration))
### Available Tools
The MCP server exposes **23 tools** for AI/LLM consumption. The 22 analysis tools, excluding the server-management-only `set_workspace`, are also available as **native LM Tools** (`#graphResolve`, `#graphBreaking`, `#graphCallGraph`, etc.) directly in Copilot Agent mode β no MCP server required for those.
| Tool | Description |
| :--- | :---------- |
| `graphitlive_set_workspace` | Set the project directory to analyze |
| `graphitlive_analyze_dependencies` | Analyze a single file's direct imports and exports |
| `graphitlive_crawl_dependency_graph` | Crawl the full dependency tree from an entry file |
| `graphitlive_find_referencing_files` | Find all files that import a given file (reverse lookup) |
| `graphitlive_expand_node` | Expand a node to discover dependencies beyond known paths |
| `graphitlive_parse_imports` | Parse raw import statements without path resolution |
| `graphitlive_verify_dependency_usage` | Verify whether a specific dependency is actually used in a file |
| `graphitlive_resolve_module_path` | Resolve a module specifier to an absolute file path |
| `graphitlive_get_symbol_graph` | Get symbol-level dependencies (functions, classes) within a file |
| `graphitlive_find_unused_symbols` | Find potentially unused exported symbols (dead code detection) |
| `graphitlive_get_symbol_dependents` | Find all symbols that depend on a specific symbol |
| `graphitlive_trace_function_execution` | Trace the complete execution path through function calls |
| `graphitlive_get_symbol_callers` | Find all callers of a symbol with O(1) instant lookup |
| `graphitlive_analyze_breaking_changes` | Detect breaking changes when modifying function signatures |
| `graphitlive_get_impact_analysis` | Full impact analysis combining callers and breaking changes |
| `graphitlive_get_index_status` | Get the current state of the dependency index |
| `graphitlive_invalidate_files` | Invalidate specific files from the cache after modifications |
| `graphitlive_rebuild_index` | Rebuild the entire dependency index from scratch |
| `graphitlive_analyze_file_logic` | Analyze symbol-level call hierarchy and code flow within a file |
| `graphitlive_generate_codemap` | Generate a comprehensive structured overview of any source file |
| `graphitlive_query_call_graph` | Query cross-file callers/callees via BFS on the call graph SQLite database |
| `graphitlive_scan_dead_code` | Scan the entire workspace (or a directory) for unused exported symbols in one call |
| `query_natural_language` | Answer a natural language question about the codebase using the call graph (LLM or heuristic fallback) |
| `graphitlive_generate_wiki` | Generate a navigable markdown wiki from the call graph (one article per file, hub scores, cross-links) |
### TOON Format (Token-Optimized Output)
All tools support an optional `format` parameter to reduce token consumption:
```json
{
"tool": "graphitlive_crawl_dependency_graph",
"params": {
"entryFile": "/path/to/main.ts",
"format": "toon"
}
}
```
| Format | Description | Token Savings |
|--------|-------------|---------------|
| `json` *(default)* | Standard JSON output | β |
| `toon` | Compact Token-Oriented Object Notation | 30-60% |
| `markdown` | JSON wrapped in markdown code blocks | β |
See [TOON Format Documentation](./docs/architecture/TOON_FORMAT.md) for full specifications, including the reproducible local-analysis and encoding-measurement protocol.
### Native LM Tools (Copilot Agent Mode)
All 21 analysis tools are also available **natively in GitHub Copilot** β no MCP server required. Reference them with `#` in Agent mode:
| Reference | Tool | Description |
|---|---|---|
| `#graphFindRefs` | `find_referencing_files` | All files that import a given file |
| `#graphDeps` | `analyze_dependencies` | Direct imports and exports of a file |
| `#graphCrawl` | `crawl_dependency_graph` | Full dependency tree from an entry file |
| `#graphSymbols` | `get_symbol_graph` | Symbol-level dependencies within a file |
| `#graphUnused` | `find_unused_symbols` | Dead code detection |
| `#graphCallers` | `get_symbol_callers` | All callers of a symbol |
| `#graphImpact` | `get_impact_analysis` | Full impact analysis |
| `#graphIndexStatus` | `get_index_status` | Current state of the dependency index |
| `#graphImports` | `parse_imports` | Raw import statements |
| `#graphCodemap` | `generate_codemap` | Comprehensive file structural overview |
| `#graphExpand` | `expand_node` | Incremental dependency exploration |
| `#graphVerifyUsage` | `verify_dependency_usage` | Is an import actually used? |
| `#graphInvalidate` | `invalidate_files` | Flush cache for specific files |
| `#graphRebuildIndex` | `rebuild_index` | Full index rebuild |
| `#graphDependents` | `get_symbol_dependents` | All symbols depending on a given symbol |
| `#graphTrace` | `trace_function_execution` | Full recursive call chain |
| `#graphFileLogic` | `analyze_file_logic` | Intra-file call hierarchy |
| `#graphResolve` | `resolve_module_path` | Resolve a module specifier to its absolute path |
| `#graphBreaking` | `analyze_breaking_changes` | Detect breaking changes between two file versions |
| `#graphCallGraph` | `query_call_graph` | BFS callers/callees via the SQLite call graph index |
| `#graphDeadCode` | `scan_dead_code` | Workspace-wide dead code scan β all unused exported symbols |
| `#graphQuery` | `query_natural_language` | Natural language question over the call graph (LLM or heuristic fallback) |
> **Note:** `#graphCallGraph` requires the Call Graph panel (`graph-it-live.showCallGraph`) to be opened at least once to build the index.
### Manual MCP Server Configuration
If automatic MCP registration doesn't work in your editor, you can configure the server manually.
Click to expand configuration instructions for VS Code, Cursor, Claude Desktop, Windsurf, etc.
#### VS Code / VS Code Insiders
Create or edit `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"graph-it-live": {
"type": "stdio",
"command": "graph-it",
"args": ["serve"],
"env": {
"WORKSPACE_ROOT": "${workspaceFolder}",
"EXCLUDE_NODE_MODULES": "true",
"MAX_DEPTH": "50"
}
}
}
}
```
> **Fallback (if CLI not installed):** replace `"command": "graph-it"` with `"command": "node"` and add `"args": ["${extensionPath:magic5644.graph-it-live}/dist/mcpServer.mjs"]`.
#### Cursor
Create or edit `.cursor/mcp.json` in your workspace or `~/.cursor/mcp.json` for global configuration:
```json
{
"mcpServers": {
"graph-it-live": {
"command": "graph-it",
"args": ["serve"],
"env": {
"WORKSPACE_ROOT": "${workspaceFolder}",
"EXCLUDE_NODE_MODULES": "true",
"MAX_DEPTH": "50"
}
}
}
}
```
> **Fallback (if CLI not installed):** `"command": "bash", "args": ["-c", "node ~/.cursor/extensions/magic5644.graph-it-live-*/dist/mcpServer.mjs"]`
#### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"graph-it-live": {
"command": "graph-it",
"args": ["serve"],
"env": {
"WORKSPACE_ROOT": "/path/to/your/project",
"EXCLUDE_NODE_MODULES": "true",
"MAX_DEPTH": "50"
}
}
}
}
```
> **Fallback (if CLI not installed):** `"command": "bash", "args": ["-c", "node ~/.vscode/extensions/magic5644.graph-it-live-*/dist/mcpServer.mjs"]`
#### Development / Local Testing
```json
{
"mcpServers": {
"graph-it-live": {
"command": "node",
"args": ["/path/to/Graph-It-Live/dist/mcpServer.mjs"],
"env": {
"WORKSPACE_ROOT": "/absolute/path/to/your/project",
"TSCONFIG_PATH": "/absolute/path/to/your/project/tsconfig.json",
"EXCLUDE_NODE_MODULES": "true",
"MAX_DEPTH": "50"
}
}
}
}
```
#### Windsurf
Create or edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"graph-it-live": {
"command": "graph-it",
"args": ["serve"],
"env": {
"WORKSPACE_ROOT": "${workspaceFolder}",
"EXCLUDE_NODE_MODULES": "true",
"MAX_DEPTH": "50"
}
}
}
}
```
> **Fallback (if CLI not installed):** `"command": "bash", "args": ["-c", "node ~/.windsurf/extensions/magic5644.graph-it-live-*/dist/mcpServer.mjs"]`
#### Antigravity
Create or edit `.antigravity/mcp.json` in your workspace or configure globally:
```json
{
"mcpServers": {
"graph-it-live": {
"command": "graph-it",
"args": ["serve"],
"env": {
"WORKSPACE_ROOT": "${workspaceFolder}",
"EXCLUDE_NODE_MODULES": "true",
"MAX_DEPTH": "50"
}
}
}
}
```
> **Fallback (if CLI not installed):** `"command": "bash", "args": ["-c", "node ~/.vscode/extensions/magic5644.graph-it-live-*/dist/mcpServer.mjs"]`
---
## Development
For comprehensive development instructions, see:
- **[DEVELOPMENT.md](DEVELOPMENT.md)** β Setup, build, testing, WASM architecture
- **[CONTRIBUTING.md](CONTRIBUTING.md)** β Contribution guidelines, branch naming, commit conventions
- **[docs/architecture/codemaps/architecture.md](docs/architecture/codemaps/architecture.md)** β **System architecture overview** with 5-layer diagram and 50+ component descriptions
- **[docs/architecture/codemaps/class-hierarchy.md](docs/architecture/codemaps/class-hierarchy.md)** β **Class hierarchy diagram** with 45+ core classes, interfaces, and design patterns
- **[docs/development/CODING_STANDARDS.md](docs/development/CODING_STANDARDS.md)** β TypeScript conventions and code style rules
- **[docs/development/CROSS_PLATFORM_TESTING.md](docs/development/CROSS_PLATFORM_TESTING.md)** β Cross-platform compatibility requirements (Windows/Linux/macOS)
- **[docs/architecture/TOON_FORMAT.md](docs/architecture/TOON_FORMAT.md)** β Token-Optimized Output format specification for AI tools
- **[docs/architecture/PERFORMANCE_OPTIMIZATIONS.md](docs/architecture/PERFORMANCE_OPTIMIZATIONS.md)** β Performance tuning and caching strategies
### Quick Start
```bash
git clone https://github.com/magic5644/Graph-It-Live.git
cd Graph-It-Live
nvm use # optional, uses Node.js 22 when nvm is installed
npm install
npm run build
# Press F5 in VS Code to launch the Extension Development Host
```
### Project Structure
```
Graph-It-Live/
βββ src/
β βββ analyzer/ # Dependency analysis (AST, Tree-sitter, SQLite)
β β βββ callgraph/ # Live Call Graph engine
β βββ extension/ # VS Code extension host
β β βββ services/ # Service layer (graph, symbol, call graph, indexing)
β βββ mcp/ # MCP server (22 AI tools)
β βββ shared/ # Types, protocols, utilities
β βββ webview/ # React UI (ReactFlow + Cytoscape.js)
β βββ callgraph/ # Call graph panel entry point
β βββ components/
β βββ reactflow/ # File graph + symbol view
β βββ cytoscape/ # Live call graph rendering
βββ tests/ # 1494+ tests (Vitest + VS Code E2E)
βββ resources/queries/ # Tree-sitter .scm queries (TS, Python, Rust)
βββ docs/ # Technical documentation
```
### Build & Test Commands
| Command | Description |
|---------|-------------|
| `npm run build` | Bundle via esbuild + copy WASM files |
| `npm run build:cli` | Build standalone CLI only (`dist/graph-it.js`) |
| `npm run watch` | Rebuild on change |
| `npm test` | Run unit tests (Vitest, mocked parsers) |
| `npm run test:cli` | Run CLI unit tests |
| `npm run test:vscode` | E2E tests from source with real WASM |
| `npm run test:vscode:vsix` | E2E tests from .vsix (pre-release) |
| `npm run lint` | Lint TypeScript (ESLint) |
| `npm run check:types` | Strict type checking |
| `npm run package` | Build .vsix package |
| `npm run package:verify` | Verify no .map files in package |
---
## WASM Architecture
Graph-It-Live uses **WebAssembly** tree-sitter parsers for cross-platform compatibility and security:
- No native compilation needed β no Python, C++ compiler, or build tools
- Pure JavaScript + WASM (~2-3 MB total)
- Works identically on Windows, Linux, and macOS
- Parsers: `tree-sitter.wasm`, `tree-sitter-python.wasm`, `tree-sitter-rust.wasm`
Click to expand WASM technical details
### Architecture
```
VS Code Extension Host (Electron)
βββ WasmParserFactory (Singleton)
β βββ tree-sitter.wasm (Core runtime)
β βββ tree-sitter-python.wasm (Python grammar)
β βββ tree-sitter-rust.wasm (Rust grammar)
βββ PythonParser, RustParser (use WASM)
βββ GraphExtractor (tree-sitter queries for call graph)
```
### Testing
- **Unit tests:** Mocked parsers (WASM doesn't run in Node.js)
- **E2E tests:** Real WASM parsers in VS Code's Electron environment
- **90+ E2E tests** validate all functionality with real parsers
### Troubleshooting
| Error | Cause | Solution |
|-------|-------|---------|
| "Extension path required" | Internal error | Report as bug |
| "LinkError: WebAssembly.instantiate()" | Node.js limitation | Expected in unit tests; works in VS Code |
| "WASM file not found" | Missing from dist/wasm/ | Run `npm run build` or reinstall |
---
## License
MIT License β see [LICENSE](LICENSE) file for details.
## Acknowledgements
Language icons provided by [SuperTinyIcons](https://github.com/edent/SuperTinyIcons) β CC0-1.0 license.
## Author
**magic56** (magic5644)