CodeGraphy

An interactive Relationship Graph for exploring how files and code concepts connect.

Install · Docs · Build a plugin · Contribute · Roadmap

CodeGraphy indexes a folder and projects its files and declarations into Nodes. It renders imports, calls, references, inheritance, containment, tests, and plugin-defined Relationships. Explore the graph inside VS Code or as native shapes in tldraw offline. Search, Graph Scope, and persistent filters narrow the VS Code view. The same Core engine supports both interfaces, the terminal CLI, and agent queries.

Features

Capability	What it provides
Relationship Graph	File, folder, package, Symbol, and plugin-defined Nodes connected by typed Edges.
Search and filters	Temporary search plus workspace-local include and exclude rules.
Graph Scope	One panel for Node Type and Edge Type visibility.
Symbol Nodes	Functions, classes, interfaces, types, variables, constants, and language-specific declarations.
Minimap	A live overview of the current Visible Graph with pointer and keyboard panning.
Theming	VS Code theme integration, Material Icon Theme file shapes, Legend Entries, and workspace CSS Snippets.
Large-graph renderer	Custom WebGPU drawing with deterministic WebAssembly force and collision physics.
Graph actions	Open, reveal, create, rename, delete, favorite, filter, and export from the graph.
Graph Cache	Workspace-local SQLite storage shared by the extension and CLI.
tldraw interface	A native, editable tldraw canvas with shared force physics and live refresh.
Plugins	Headless npm packages for deeper analysis and Graph View contributions.
Agent access	Bounded JSON queries through the Core CLI and a reusable Agent Skill source.

Gallery

Large workspace

Search and filters	Symbol Nodes

Install

VS Code Extension

1. Install CodeGraphy from the VS Code Marketplace.
2. Open a folder or workspace.
3. Open CodeGraphy from the Activity Bar.
4. Select Index Workspace to add semantic Relationships to the initial file graph.

The extension publishes native runtime targets for Linux x64, macOS Apple Silicon, and Windows x64. It bundles Core plus baseline analysis for JavaScript, TypeScript, TSX, Python, Go, Haskell, Java, Kotlin, Lua, PHP, Ruby, Rust, Swift, Dart, C#, C, C++, Objective-C, Scala, and Pascal. Markdown analysis ships as a bundled plugin that starts enabled in new workspaces.

CLI and Plugins

The terminal CLI supports Node.js 20 through 22. Node 22 LTS is recommended.

npm install -g @codegraphy-dev/core
codegraphy index
codegraphy search SettingsPanel
codegraphy dependencies packages/extension/src/webview/app/shell/view.tsx

Install, register, and enable optional plugins separately:

npm install -g @codegraphy-dev/plugin-vue
codegraphy plugins register @codegraphy-dev/plugin-vue
codegraphy plugins enable @codegraphy-dev/plugin-vue
codegraphy index

Commands target the current directory. Use -C, --workspace <path> before the command to select another CodeGraphy Workspace:

codegraphy -C /path/to/workspace index

tldraw Offline

The first tldraw interface supports macOS and Node.js 20 through 22. Node.js 22 LTS is recommended. Install the tldraw offline desktop app, Core, and the interface. Then run the launcher from the workspace to index:

npm install -g @codegraphy-dev/core @codegraphy-dev/tldraw
cd /path/to/workspace
codegraphy-tldraw

The launcher creates or refreshes CodeGraphy.tldraw, opens it in tldraw offline, and runs CodeGraphy's WebAssembly force physics on native tldraw shapes. Search file paths from the top of the canvas, or double-click a node to inspect its relationships. Pass a relative or absolute .tldraw path to use a named canvas:

codegraphy-tldraw docs/architecture.tldraw

Run the same command after workspace changes. An open canvas updates in place and keeps user-created notes, drawings, media, node positions, sizes, and styles. See the @codegraphy-dev/tldraw guide for controls and document behavior.

CLI Reference

All codegraphy ... commands are published by @codegraphy-dev/core. Data commands return { "ok": true, "command": "...", "data": ... } on stdout. Failures return { "ok": false, "command": "...", "error": ... } on stderr and use a nonzero exit code. An unhealthy doctor result keeps every completed check in error.details. Help and version output stay plain text.

Command	Result
codegraphy status	Reports fresh, stale, missing, or unusable Graph Cache state.
codegraphy doctor	Checks runtime, settings, Graph Cache schema, integrity, foreign keys, counts, and plugin state.
codegraphy index	Makes the selected workspace Graph Cache current.
codegraphy nodes	Lists bounded Nodes from saved Graph Scope.
codegraphy search <text>	Searches Nodes.
codegraphy edges	Lists bounded Edges.
codegraphy dependencies <node>	Lists outgoing Relationships for a file or exact Symbol Node.
codegraphy dependents <node>	Lists incoming Relationships for a file or exact Symbol Node.
codegraphy path <from> <to>	Finds bounded directed paths.
codegraphy scope	Reads or changes saved Node Type and Edge Type scope.
codegraphy filter	Reads or changes persisted filter patterns.
codegraphy plugins	Registers, links, lists, enables, or disables plugins.

Run codegraphy <command> --help for exact arguments. Query, settings, Indexing, and diagnostic commands keep machine-readable JSON on stdout. Verbose diagnostics go to stderr.

Agent Skill

The CodeGraphy Agent Skill teaches shell-capable agents to keep the index current and choose a bounded Graph Query before reading source. Install it from a clone of this repo:

npx skills@latest add ./skills/codegraphy

A public codegraphy/skills repository will host the skill once published.

Architecture

@codegraphy-dev/core owns File Discovery, built-in analysis, plugin discovery and activation, SQLite Graph Cache storage, Graph Query, and the CLI. It does not own rendering. The VS Code extension connects Core to the editor lifecycle and React Graph View. The tldraw interface connects Core data and shared physics to native tldraw shapes. @codegraphy-dev/graph-renderer owns WebGPU drawing and WebAssembly physics. Core plugins use @codegraphy-dev/plugin-api. VS Code Extension plugins use @codegraphy-dev/extension-plugin-api.

Package	Role
@codegraphy-dev/core	Shared indexing, cache, plugin, query, and CLI engine.
@codegraphy-dev/extension	VS Code host and Graph View product integration.
@codegraphy-dev/tldraw	macOS launcher and native tldraw offline canvas integration.
@codegraphy-dev/graph-renderer	WebGPU graph renderer and WebAssembly physics.
@codegraphy-dev/plugin-api	Public TypeScript contracts for Core plugins.
@codegraphy-dev/extension-plugin-api	Public TypeScript contracts for VS Code Extension plugins.
@codegraphy-dev/plugin-*	Optional plugins for Core or an interface host.
@codegraphy/web	Account, subscription, billing, and access routes.

The editable diagram source is docs/media/readme/codegraphy-architecture.excalidraw.

Development

pnpm install
pnpm run build
pnpm run dev
pnpm run test
pnpm run lint
pnpm run typecheck

See Contributing for the workflow and Documentation for the reference map. The active roadmap lives on Trello.

License

MIT