CodeGraphy

Visualize relationships

Core · TypeScript/JavaScript Plugin · Python Plugin · C# Plugin · GDScript Plugin · MCP · Plugin API

CodeGraphy turns repository structure and code relationships into a Relationship Graph inside VS Code. Files start as File Nodes, indexing projects richer Edges into the graph, and the whole repo becomes something you can inspect, filter, and navigate instead of infer.

The same Relationship Graph can be used as local agent context through the @codegraphy-vscode/mcp package. Codex and other MCP clients can open a repo in the Core Extension, ask it to run Indexing, and query nodes, edges, relationships, symbols, and bounded paths without reading the whole repo into context.

CodeGraphy dependency graph

Now with Material Icon Theme!

CodeGraphy History

I originally came up with CodeGraphy back in college in 2021 after seeing Obsidian.md 's graph. I've always been a very visual thinker and so Obsidians graph felt very intuitive to me. The clusters of nodes that appeared represented bundles of knowledge that was closely entangled. These clusters reminded me of the way that code worked and the way files related to each other (whether importing, extending, referencing). I wanted to see those relationships in my code, just like in Obsidian's graph, and see what insights I could learn from it. And thats where CodeGraphy was born.

The first iteration was https://github.com/joesobo/CodeGraphy. Its pretty rough, but the core idea is there.

V2 was the last published version: https://github.com/joesobo/CodeGraphyV2. This version was a huge upgrade, enabling dynamic physics and a ton more features. But it was largely limited to Javascript

So I started working on V3 https://github.com/joesobo/CodeGraphyV3 this time with a broader scope. Instead of limited ourselves to a single language. The goal was to make the core renderer reusable and let plugins teach it new language semantics when needed.

Unfortunately I got quite busy and never was able to maintain V2 or finish V3.

CodeGraphy V4 is a ground-up for the 4th time. Probably wont be the last time either. This time its been primarily programmed via Codex. Ive followed the same concepts as the previous iterations of CodeGraphy compacted in this monorepo, as a means to test out agentic programming and different methodologies of doing so. This is not a serious project, I am doing this to learn. The project should work but I make no promises. Feel free to fork or look at any of the previous versions if you are interested in the project. Or hell submit an issue or PR.

Monorepo

CodeGraphy V4 is a pnpm monorepo with one Core Extension, one agent access package, one public Plugin API, optional language plugins, and repo-owned quality tooling.

The Core Extension is the source of truth for graph behavior. It discovers files, runs built-in Tree-sitter Analysis and plugin analysis, writes the Graph Cache, projects the Relationship Graph, renders the Graph View, and executes Graph Query requests.

The MCP package is the agent access layer. It does not index or parse code by itself; it opens or focuses the repo in VS Code, asks the Core Extension to run Indexing, and forwards Graph Query requests to the active Core Extension window.

The optional language plugins add ecosystem-specific filters or enrichment on top of the Core Extension baseline. Markdown ships built in, while TypeScript/JavaScript, C#, Python, and GDScript/Godot are packaged as installable examples of the plugin surface.

The quality tooling package owns the local architecture checks used by this repo: organize analysis, boundary checks, reachability, CRAP, scoped mutation, and SCRAP test-shape review.

Package Map

Package	Path	Install	What It Owns
CodeGraphy core extension	`packages/extension`	VS Code Marketplace	Graph View, Indexing, Tree-sitter Analysis, Graph Projection, repo-local Settings, Graph Cache, exports, and Graph Query execution
`@codegraphy-vscode/mcp`	`packages/codegraphy-mcp`	`npm install -g @codegraphy-vscode/mcp`	`codegraphy` CLI and local MCP server for agent access through the Core Extension
`@codegraphy-vscode/plugin-api`	`packages/plugin-api`	`npm install @codegraphy-vscode/plugin-api`	typed contracts for external CodeGraphy plugins and webview contributions
TypeScript/JavaScript plugin	`packages/plugin-typescript`	VS Code Marketplace	optional TypeScript and JavaScript enrichment outside the built-in baseline
C# plugin	`packages/plugin-csharp`	VS Code Marketplace	optional C# enrichment outside the built-in baseline
Python plugin	`packages/plugin-python`	VS Code Marketplace	optional Python enrichment outside the built-in baseline
GDScript/Godot plugin	`packages/plugin-godot`	VS Code Marketplace	optional Godot project, scene, resource, and script enrichment
Markdown plugin	`packages/plugin-markdown`	bundled with the Core Extension	Markdown wikilink and note relationship enrichment
Quality tools	`packages/quality-tools`	private workspace package	local architecture, coverage-risk, mutation, and test-shape checks

The MCP package is an agent companion, not a second indexer. The Core Extension owns Indexing, Graph Cache access, plugin wiring, and Graph Query execution. The MCP server opens/focuses the repo, forwards Indexing and Graph Query requests to the Core Extension, and returns the response to the agent.

Core Stack

TypeScript
VS Code extension host
React webview
Vite
native Tree-sitter in the extension core
LadybugDB for repo-local index storage
react-force-graph + Three.js
repo-local .codegraphy/ settings + metadata
shared per-file analysis results merged in plugin priority order
pnpm monorepo

What you get

Relationship Graph Open any project and CodeGraphy shows discovered File Nodes immediately. Index the repo to project richer Edges into the same Graph View. Drag nodes, zoom, search, and filter without switching to a separate built-in view.

Core pipeline, plugins for enrichment The Core Extension owns discovery, caching, Graph Projection, repo-local settings, and export flow. Built-in and external Plugins contribute per-file analysis results, richer Relationships, extra Node Types and Edge Types, and UI integrations.

Broad Tree-sitter baseline The core now ships native Tree-sitter coverage for JavaScript, TypeScript, TSX, Python, Go, Haskell, Java, Kotlin, Lua, PHP, Ruby, Rust, Swift, Dart, C#, C, and C++. That means many repos produce useful semantic edges before you install any language plugin at all.

Explorer-style theming in core The core extension now vendors material-icon-theme and uses it as the default file and folder theming layer. File nodes take the Material icon color as their base node color and render the icon in white. Folder nodes keep the configured folder color and render the original Material folder icon as-is.

One graph, configurable scope Use the Nodes, Edges, Legends, and Plugins popups to choose Graph Scope, Legend styling, and Plugin state. Turn on Depth Mode from the toolbar when you want a focused local graph around the current Focused Node.

Git timeline playback Index your repository history, scrub through commits, and watch the Relationship Graph evolve over time.

Timeline playback

Repo-local graph settings and cache CodeGraphy stores its Graph Cache and repo-specific Settings under .codegraphy/, so graph behavior, styling, toggles, and cached analysis stay with the repo instead of polluting .vscode/settings.json.

Agent-readable graph memory Install @codegraphy-vscode/mcp to expose Graph Query to Codex or any MCP-capable agent. Agents open a repo, index it when needed, list nodes and edges, inspect detailed relationships and symbols, and find bounded directed paths while the Core Extension keeps the graph logic centralized.

Configurable graph presentation Tune the physics, switch between 2D and 3D, adjust node sizes, color node and edge types, assign glob-based legend rules, and filter out noise.

Exports from cached graph data Graph Export the current Visible Graph as JSON/Markdown/image output, and Index Export lightweight symbol JSON from the warmed index without re-scanning the repo.

2D	3D

Actions from the graph Preview, open, rename, delete, favorite, and inspect File Nodes directly from the graph. Single-click previews a File Node, double-click opens it persistently, and non-file nodes can still be selected and focused.

Install

Install the CodeGraphy core extension.
Optionally install plugins for unsupported languages or richer semantics. Core already handles JavaScript, TypeScript, TSX, Python, Go, Haskell, Java, Kotlin, Lua, PHP, Ruby, Rust, Swift, Dart, C#, C, and C++ through Tree-sitter, and Markdown ships built in.
Click the CodeGraphy activity bar icon in VS Code.
Open the graph.
Click Index Repo when you want to visualize relationships.

Agent Setup

Use this to let an agent open or focus the repo, ask the Core Extension to index when needed, and query the Relationship Graph.

npm install -g @codegraphy-vscode/mcp
codegraphy setup
codegraphy open .
codex mcp list

Then start a new agent session and ask something short:

Use CodeGraphy to explain the relationship between deep.ts and branch.ts.

For the full setup flow, Codex config snippets, CLI table, MCP tool table, and verification prompts, see MCP Setup.

Legend Precedence

Legend styling is cumulative and resolves in this order:

Core defaults
- Material Icon Theme file and folder matches
- Defaults entries such as Files and Packages
Plugin defaults
Custom Legend Entries

Higher layers override lower ones only for the fields they set.

Development

Want to build your own language plugin? Start with the Plugin Guide, the plugin lifecycle docs, and @codegraphy-vscode/plugin-api.

Documentation


Timeline	Git history playback and incremental indexing
Settings	`.codegraphy/settings.json`, panels, and Settings Controls
Export menu	Graph Export JSON/Markdown/image plus Index Export symbol JSON
Commands	Command palette reference
Keybindings	Keyboard shortcuts
Interactions	Mouse, context menu, toolbar, and panels
Plugin Guide	Build and package plugins for CodeGraphy
MCP Setup	Quick start, step-by-step setup, CLI/tool tables, manual Codex config, and verification flow
MCP Package	Package-level install, commands table, MCP tools table, prompts, and skill link
CodeGraphy MCP Skill	Reusable skill that teaches agents to use CodeGraphy first for dependency and impact questions
Contributing	Development setup and contribution workflow

License

MIT