Graph-It-Live

The AI-first dependency intelligence platform for VS Code.

See your codebase the way your AI does — as a graph.

Star History

Star History

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:

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. 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.

- 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.

Table of Contents

• Graph-It-Live
  • Why Graph-It-Live?
  • Table of Contents
  • 🤖 Supercharge Your AI Assistant
    • What your AI can do with Graph-It-Live
    • 🗺️ Codemap Generation (New)
    • 📊 File Logic Analysis (New)
  • 👁️ Features for Humans
    • File Dependency Graph
    • Symbol-Level Drill-Down
    • 🔷 Live Call Graph (New)
    • Unused Dependency Filter
  • Prerequisites
  • Installation
    • From Marketplace
    • From Open VSX Registry
  • Usage
  • Configuration
    • Performance Profiles
    • All Settings
  • Standalone CLI
  • Agent Skill
  • MCP Server (AI/LLM Integration)
    • Setup
    • Available Tools
    • TOON Format (Token-Optimized Output)
    • Native LM Tools (Copilot Agent Mode)
    • Manual MCP Server Configuration
      • VS Code / VS Code Insiders
      • Cursor
      • Claude Desktop
      • Development / Local Testing
      • Windsurf
      • Antigravity
  • Development
    • Quick Start
    • Project Structure
    • Build & Test Commands
  • WASM Architecture
    • Architecture
    • Testing
    • Troubleshooting
  • License
  • Acknowledgements
  • 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), 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

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](https://github.com/magic5644/Graph-It-Live/issues/1)]
      ├── setupFileWatcher()      [call [#2](https://github.com/magic5644/Graph-It-Live/issues/2)]
      └── startListening()        [call [#3](https://github.com/magic5644/Graph-It-Live/issues/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:

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.

From Open VSX Registry

Also available on the Open VSX Registry 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:

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)

Standalone CLI

Graph-It-Live is also available as a standalone npm package — no VS Code required.

npm install -g @magic5644/graph-it-live

After install, graph-it is available on your PATH:

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 <file>         # Per-file codemap (exports, internals, deps, call flow)
graph-it trace <file#Symbol>    # Trace execution flow from an entry symbol
graph-it explain <file>         # File logic analysis — intra-file call hierarchy
graph-it path <file>            # Full dependency graph from a file
graph-it check                  # Scan whole workspace for dead code (unused exports)
graph-it check <dir>            # Scan a subdirectory for dead code
graph-it check <file>           # Detect unused exported symbols in a single file
graph-it query "<question>"     # 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 21 CLI analysis tools
graph-it tool <mcp-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)

Troubleshooting: if graph-it runs but prints nothing at all (versions ≤ v1.13.6 shipped a broken npm bin wrapper), graph-it update can't help — the CLI is silently dead on arrival. Reinstall directly instead: npm install -g @magic5644/graph-it-live@latest. Fixed in v1.14.0; see docs/CLI.md for details.

Without installing globally:

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:

graph-it summary <file> --format toon
graph-it path <file> --format markdown
graph-it path <file> --format mermaid          # → Mermaid flowchart of dependency graph
graph-it trace <file#Symbol> --format mermaid  # → Mermaid sequence/flowchart of execution trace

Example --format mermaid output for graph-it path src/index.ts:

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 <path> (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.

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 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:

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)

Available Tools

The MCP server exposes 26 tools for AI/LLM consumption. The 21 general-purpose analysis tools, excluding the server-management-only set_workspace and the 4 tools with dedicated CLI commands (review-pr, query, wiki, stats), are also available as native LM Tools (#graphResolve, #graphBreaking, #graphCallGraph, etc.) directly in Copilot Agent mode — no MCP server required for those.

TOON Format (Token-Optimized Output)

All tools support an optional format parameter to reduce token consumption:

{
  "tool": "graphitlive_crawl_dependency_graph",
  "params": {
    "entryFile": "/path/to/main.ts",
    "format": "toon"
  }
}

See TOON Format Documentation 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:

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.

{
  "servers": {
    "graph-it-live": {
      "type": "stdio",
      "command": "graph-it",
      "args": ["serve"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}",
        "EXCLUDE_NODE_MODULES": "true",
        "MAX_DEPTH": "50"
      }
    }
  }
}

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}",
        "EXCLUDE_NODE_MODULES": "true",
        "MAX_DEPTH": "50"
      }
    }
  }
}

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/project",
        "EXCLUDE_NODE_MODULES": "true",
        "MAX_DEPTH": "50"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}",
        "EXCLUDE_NODE_MODULES": "true",
        "MAX_DEPTH": "50"
      }
    }
  }
}

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}",
        "EXCLUDE_NODE_MODULES": "true",
        "MAX_DEPTH": "50"
      }
    }
  }
}

Development

For comprehensive development instructions, see:

• DEVELOPMENT.md — Setup, build, testing, WASM architecture
• CONTRIBUTING.md — Contribution guidelines, branch naming, commit conventions
• docs/architecture/codemaps/architecture.md — System architecture overview with 5-layer diagram and 50+ component descriptions
• docs/architecture/codemaps/class-hierarchy.md — Class hierarchy diagram with 45+ core classes, interfaces, and design patterns
• docs/development/CODING_STANDARDS.md — TypeScript conventions and code style rules
• docs/development/CROSS_PLATFORM_TESTING.md — Cross-platform compatibility requirements (Windows/Linux/macOS)
• docs/architecture/TOON_FORMAT.md — Token-Optimized Output format specification for AI tools
• docs/architecture/PERFORMANCE_OPTIMIZATIONS.md — Performance tuning and caching strategies

Quick Start

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

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

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)

License

MIT License — see LICENSE file for details.

Acknowledgements

Language icons provided by SuperTinyIcons — CC0-1.0 license.

Author

magic56 (magic5644)