Graph-It-Live

See your codebase as a graph — in VS Code, your CLI, and your AI assistant.

Graph-It-Live analyzes imports, symbols, calls, cycles, unused exports, and change impact. Use it as a VS Code extension, a standalone CLI, or an MCP/native tool provider for GitHub Copilot and other AI clients. Analysis runs locally and returns evidence from your codebase.

▶ Watch the 75-second tour

Click the image to play the video (sound on). It walks through the file graph with Louvain import clusters, the Dependency Structure Matrix, boundary rules declared in graphit.architecture.json, and an AI agent fixing a rule violation through the Graph-It-Live MCP server.

Table of Contents

• What it does
• Quick start
• Features
• Standalone CLI
• AI integrations
• Configuration
• CI review gate
• Supported languages
• Documentation
• Development
• License

What it does

Graph-It-Live provides three views of a codebase:

Use the same graph data to navigate code, review refactors, generate codemaps, and give AI assistants focused context instead of entire source files.

Quick start

VS Code extension

Requirements: VS Code 1.96 or later. Install from the VS Code Marketplace or Open VSX.

1. Open a project.
2. Open the Graph-It-Live view from the Activity Bar.
3. Run Graph-It-Live: Show Dependency Graph from the Command Palette.
4. Click a file to open it, double-click it for the Symbol View, or use Show Call Graph for cross-file calls.

Supported projects include TypeScript, JavaScript, Python, Rust, C#, Go, Java, Vue, Svelte, and GraphQL.

First useful actions

Features

File dependency graph

• Visualize file-to-file imports across a workspace.
• Detect circular dependencies and highlight cycles.
• Expand and collapse nodes as you explore.
• Open files directly from graph nodes.
• Find reverse dependencies with an indexed lookup.

Symbol View

Drill into TypeScript, JavaScript, Python, or Rust files to see functions, classes, variables, outgoing calls, incoming callers, and recursive calls. Click a symbol to navigate to its definition.

Live Call Graph

The Live Call Graph shows cross-file symbol relationships in a Cytoscape.js panel.

• Expand callers and callees with a depth from 1 to 5. A view shows at most 500 symbols, nearest hops first; a notice counts the hidden ones.
• Group symbols by folder.
• Number calls in invocation order.
• Highlight self-recursion and mutual recursion.
• Filter by symbol type or folder.
• Refresh automatically after file saves.

The Live Call Graph supports TypeScript, JavaScript, Vue, Svelte, Python, Rust, C#, Go, and Java. C#, Go, and Java are supported in the file graph and Live Call Graph; Symbol View support is currently limited to TypeScript, JavaScript, Python, and Rust.

Architecture view

The Architecture view draws the whole workspace as units (packages, else top-level folders) in layers, with the import edges between them, their roles and their cycles. It answers three questions: what are my layers, who depends on this, and does the code follow my rules. The architecture guide defines every term, explains the marks of each view and how to fix what they raise: cycles, rule violations, unmatched files.

Units in layers with their roles, a cycle outlined, and rule violations (test fixture monorepo). Open it with Switch to Architecture View in the Dependency Graph view title bar.

Quick start:

1. Open the Dependency Graph view and click Switch to Architecture View (icon $(type-hierarchy)).
2. Double-click a unit to enter its folders; Escape goes back.
3. Click an edge to list the file pairs behind it.
4. Select a node, then Dependents by group to see every group that imports it.
5. Click Matrix for the dependency structure matrix of the level.

The CLI (graph-it architecture --level units) and the MCP tool explore_architecture report the same counts.

Role badges: [library?] inferred, [library] declared. Click a role in the units legend to filter.

Double-click a unit or folder to enter it; the breadcrumb or Escape goes back.

Click an edge for its file pairs, then a file to open it.

Select a node, then Dependents by group in the bottom-left action bar.

Enter a unit with more than 50 folder groups: the view draws the 50 largest, and Show more groups draws up to 150.

Click Matrix in the Graph | Matrix switch for the dependency structure matrix.

Architecture rules

Declare your intended architecture in graphit.architecture.json at the workspace root: elements name sets of files, rules say what each may import, and roles declare what each unit is. The view lists each rule with its violations; graph-it check-architecture exits with 1 on a new error violation, so it can gate CI, with SARIF output for code scanning and a baseline for existing code. See the config file for a complete example.

Write graphit.architecture.json at the workspace root, then click Refresh: click a rule to list the file pairs that break it, then a file to open it.

graph-it check-architecture on this repository: 8 rules, no violation, exit code 0.

Unused dependencies and impact analysis

• Hide or dim unused dependencies.
• Detect unused exported symbols.
• Trace execution from a function or symbol.
• Identify callers affected by a signature change.
• Generate a codemap with exports, internals, dependencies, dependents, and call flow.

Standalone CLI

Use the same analysis engine without VS Code. Install it globally:

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

Or run it with npx:

npx @magic5644/graph-it-live scan

Common commands:

graph-it scan                         Index the workspace
graph-it summary                      Show a workspace overview
graph-it summary <file>               Generate a file codemap
graph-it trace <file#Symbol>          Trace execution from a symbol
graph-it explain <file>               Explain intra-file call flow
graph-it path <file>                  Show a dependency path
graph-it check [path]                 Find unused exported symbols
graph-it architecture --groups        Show the workspace architecture by folder or community
graph-it check-architecture           Check imports against graphit.architecture.json
graph-it query "<question>"           Ask a natural-language graph question
graph-it context "<question>"         Retrieve bounded graph context
graph-it wiki                         Generate a navigable Markdown wiki
graph-it serve                        Start the MCP stdio server
graph-it export [path]                Export the graph as HTML
graph-it --help                       Show all commands and options

Analysis commands support --format json|toon|markdown. trace, path and architecture also support --format mermaid, architecture --matrix supports --format csv, and check-architecture supports --format sarif. Use --workspace <path> or -w to analyze a project other than the current directory.

See the complete CLI reference, including installation troubleshooting, REPL commands, output formats, and tool details.

Unified graph context

graph-it context combines imports, symbols, calls, tests, impact, paths, hubs, and communities in one bounded response. It supports search, neighbors, path, impact, refactor, and overview modes.

graph-it context "what calls the request handler" --scope 'src/**' --format toon
graph-it context --mode path --from src/api.ts#handle --to src/db.ts#query
graph-it context --mode impact --seeds src/api.ts#handle --depth 3 --format json

Use --detail compact and --token-budget for agent-oriented responses. See the TOON format specification for the output format and measurement protocol.

AI integrations

Graph-It-Live exposes local graph analysis to GitHub Copilot, Claude, Cursor, Windsurf, Antigravity, and other MCP-compatible clients.

Native Copilot tools

When the extension is installed, use these tools in Copilot Agent mode without configuring MCP:

The graph-context tool is available as #graphContext. Other native references include #graphDeps, #graphFindRefs, #graphCallers, #graphImpact, #graphCodemap, #graphTrace, #graphDeadCode, #graphReviewPr, and #graphQuery.

MCP server

The MCP server exposes 24 graph-analysis tools. Enable it in VS Code with graph-it-live.enableMcpServer, or start it from the CLI:

graph-it serve

For VS Code, add .vscode/mcp.json:

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

For Cursor, use .cursor/mcp.json with the same server definition under mcpServers instead of servers. The same graph-it serve command works with Claude Desktop, Claude Code, Windsurf, and Antigravity. See the CLI/MCP documentation for client-specific configuration and environment variables.

For Codex CLI:

codex mcp add graph-it-live --env WORKSPACE_ROOT=/path/to/project -- graph-it serve

Portable agent plugin

The plugins/graph-it-live/ directory is the portable Agent Plugin package. It bundles the MCP server and four skills: graph-it-live, onboarding-express, dead-code-hunter, and pr-review. Install it with the client you use:

Claude Code

From Claude Code, add the repository marketplace and install the plugin:

claude plugin marketplace add magic5644/Graph-It-Live
/plugin install graph-it-live@graph-it-live

For a local checkout, start a session with claude --plugin-dir ./plugins/graph-it-live.

GitHub Copilot CLI

copilot plugin marketplace add magic5644/Graph-It-Live
copilot plugin install graph-it-live@graph-it-live

VS Code

1. Open the Command Palette.
2. Run Chat: Install Plugin From Source.
3. Select plugins/graph-it-live/.

The VS Code extension itself remains available from the VS Code Marketplace and Open VSX.

Cursor

Open the Plugins panel, choose Install from local source, and select plugins/graph-it-live/.

Codex

Add the repository's Codex marketplace catalog to a configured plugin marketplace, then open /plugins in Codex and install Graph-It-Live.

Windsurf, Antigravity, and other MCP clients

These clients can use the MCP server directly. Add this server entry to the client's MCP configuration:

{
  "graph-it-live": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@magic5644/graph-it-live@latest", "serve"]
  }
}

Use the client's MCP configuration file and its expected top-level key (servers or mcpServers). See the MCP server instructions for ready-to-copy VS Code, Cursor, and Codex examples.

The repository also includes marketplace catalogs for Claude Code and Codex. The MCP entry pins the latest published @magic5644/graph-it-live version and starts it with npx --prefer-offline, so a cached package starts without a registry lookup; a workflow updates the pin, the plugin manifests and the marketplace versions after each npm publish.

Agent skill

Install the Graph-It-Live skill for an AI agent:

npx skills add magic5644/skills/graph-it-live

The skill documents graph queries, codemaps, impact analysis, dead-code detection, and safe refactoring workflows.

Configuration

Branch Watch

Branch Watch is disabled by default. Enable graph-it-live.branchWatch.enabled for a workspace folder, select a local Git base branch and optionally a local or remote head branch, and use the native Branch status view to inspect changes automatically (it starts collapsed in the Graph-It-Live panel: expand it, or run Graph-It-Live: Show Branch Status). Branch selections are stored per workspace in the ignored .graph-it/branch-watch.json; the baseRef and headRef settings are retained only as a legacy fallback. An empty head uses the current branch plus the final on-disk state; an explicit head compares committed branch refs and does not include untracked workspace files. It never fetches, runs tests, or reports test success. The view shows file impact for supported languages, TS/JS signature evidence, cycle history when the graphs are complete, and explicit limitations. Impact traversal is intentionally bounded (depth 3 and at most 200 affected files), so a partial result is reported with its risk and confidence instead of being presented as complete. Right-click any message row and choose Copy Message to pass the exact text to an LLM or issue. The reminder Tests must pass before delivery. is informational.

Branch Watch requires the Graph-It-Live workspace root to be a supported Git repository. A folder without Git, an unborn or detached repository, conflicts, an inaccessible index, or an unsupported VCS is shown as Branch watch unavailable; the normal graph and CLI/MCP tools remain available.

Set these options in VS Code settings:

Workspace indexing (extension, CLI, and MCP) skips paths listed in the root .gitignore, plus tests/fixtures/ and out-*/ by default. Add a root .graphitignore with gitignore syntax to exclude more paths, or negate a rule to include it again, for example !tests/fixtures/.

performanceProfile sets indexing concurrency, cache sizes, and unused-analysis limits. To tune them by hand, select custom and edit the Advanced: Performance overrides section (search @tag:advanced graph-it-live in the Settings editor). The other profiles ignore these overrides.

CI review gate

The graph-it review-pr command performs a deterministic local Git diff review before CI. It compares exported TypeScript and JavaScript signatures, follows bounded dependent-symbol impact, and reports cycle evidence, unused exports, test candidates, and consumer standing. Consumers are classified as updated in the diff, covered by a test path, or unverified. The score reflects the highest-risk changed symbol; a high risk is report data, not a failing exit status.

By default, --base <ref> is compared with the current working tree, including staged and unstaged file contents. Pass --head <ref> to compare two Git refs. Use --depth and --max-files to bound impact traversal and changed-file analysis. See the review-pr CLI reference for scoring thresholds, output formats, limitations, and examples.

The reusable GitHub Action is informational by default. Set fail-on-risk: high or critical to gate a pull request. Add it to a consumer workflow with docs/examples/graph-it-review-gate.yml.

Use pull_request, not pull_request_target, for untrusted pull requests. The action analyzes the consumer checkout in an isolated temporary directory and sends only a sanitized report to GitHub.

Supported languages

Documentation

• CLI reference — commands, REPL, output formats, and MCP tools
• Architecture guide — Architecture view, graphit.architecture.json rules, and check-architecture
• Development guide — setup, builds, tests, and WASM architecture
• Contributing guide — contribution workflow and conventions
• System architecture
• Class hierarchy
• TOON format
• Coding standards
• Cross-platform testing
• Performance optimizations
• Documentation index

Development

Requirements: Node.js 22 or later and npm.

git clone https://github.com/magic5644/Graph-It-Live.git
cd Graph-It-Live
npm install
npm run build

Press F5 in VS Code to launch the Extension Development Host.

See DEVELOPMENT.md for the full project structure, test strategy, WASM details, and troubleshooting.

License

MIT. See LICENSE.

Language icons are provided by SuperTinyIcons under the CC0-1.0 license.

Star History