codemap-3d

3D code structure visualizer — CLI + MCP server powered by tree-sitter.

Parses source code into a graph of symbols and relationships (functions, classes, imports, call sites) and renders an interactive 3D visualization using 3d-force-graph.

Supported Languages

Language	Extensions
JavaScript/TypeScript	.js .mjs .cjs .jsx .ts .tsx
Python	.py
Go	.go
Java	.java
Kotlin	.kt .kts
PHP	.php
Dart	.dart

Installation

# Clone and link globally
git clone <repo-url>
cd code-visualizer
npm install
npm run build
npm link

# Now available everywhere:
codemap <path>

Development mode (no build needed)

npx tsx src/index.ts <path>

Commands

codemap <path> — Generate visualization

Analyzes a directory and generates a static 3D visualization.

codemap ./my-project
codemap ./my-project -t cyberpunk --open
codemap ./my-project -f json -o ./report

Option	Description	Default
-o, --output <dir>	Output directory	output
-f, --format <type>	Output format: html, json	html
-t, --theme <name>	Theme: clarity, cyberpunk	clarity
--open	Auto-open in browser
--no-files	Exclude file nodes from graph

Interactive controls:

• Fuzzy search — VS Code-style search with dropdown suggestions, keyboard navigation (arrow keys + enter), click to center camera on node
• Filter buttons — toggle Files, Classes, Functions, Methods visibility
• Node click — opens info panel with details, incoming/outgoing connections, and Center buttons to navigate to connected nodes
• Export Graph — download graph data as JSON
• Graph summary — sidebar showing node and edge counts

codemap blast <path> — Blast radius visualization

Visualizes the blast radius of git changes on the current branch. Shows the same 3D graph with visual indicators for how close each node is to the changed code.

• Changed nodes: original color + red 2D ring outline + black center dot
• Nearby nodes: original color + fading red ring based on distance
• Unaffected nodes: faded when "Fade unaffected nodes" is enabled

codemap blast ./my-project
codemap blast ./my-project -b develop --open
codemap blast ./my-project -t cyberpunk -o ./blast-report

Option	Description	Default
-o, --output <dir>	Output directory	output
-t, --theme <name>	Theme: clarity, cyberpunk	clarity
-b, --base <branch>	Base branch to diff against	auto-detect
--open	Auto-open in browser
--no-files	Exclude file nodes from graph

Interactive controls in the blast radius view:

• Changed Files panel — expandable list of changed files; each file expands to show individual changed nodes (functions, classes, methods) with kind badges
• Per-node filtering — toggle individual files or nodes on/off to isolate specific changes; file checkbox shows indeterminate state when partially selected
• Center button — zoom the camera to any changed node; also available on connections in the info panel
• Blast direction — Incoming (default, shows callers/importers), Both, or Outgoing (shows callees/dependencies)
• Max blast distance slider — limit blast radius depth (1–10, default 3)
• Fade unaffected nodes — checkbox (on by default) to fade nodes and links outside the blast radius
• Impact alert — top bar indicator showing how many nodes are affected
• Export Graph — download graph + blast radius data as JSON
• Fuzzy search — same VS Code-style search as the explorer view, with center-on-click

codemap serve <path> — Live dev server

Starts a dev server with file watching and live reload via WebSocket.

codemap serve ./my-project
codemap serve ./my-project -p 8080 --open

Option	Description	Default
-p, --port <number>	Server port	3333
-t, --theme <name>	Theme: clarity, cyberpunk	clarity
--open	Auto-open in browser

MCP Server

codemap-3d exposes an MCP server for integration with AI tools (Claude, Cursor, etc.).

Setup

node dist/server.js

Add to your MCP client config (e.g. Claude Desktop, Claude Code):

{
  "mcpServers": {
    "codemap-3d": {
      "command": "node",
      "args": ["/path/to/code-visualizer/dist/server.js"]
    }
  }
}

Tools

generate_graph

Parse a directory and return the full code structure graph as JSON.

Parameter	Type	Required	Description
directory	string	yes	Absolute path to analyze
include_files	boolean	no	Include file nodes (default: true)

Returns: Full graph with nodes (files, classes, functions, methods) and edges (calls, imports, contains).

analyze_blast_radius

Analyze the blast radius of git changes — returns structured JSON optimized for LLM consumption. Does not open a browser.

Parameter	Type	Required	Description
directory	string	yes	Absolute path to git repository
base_branch	string	no	Base branch to diff against (default: auto-detect)
max_distance	number	no	Max blast radius depth, 1–20 (default: 3)
direction	string	no	incoming, outgoing, or both (default: incoming)
include_files	boolean	no	Include file nodes (default: true)

Returns:

{
  "changed_files": [
    {
      "path": "src/utils/Mongo.ts",
      "changed_nodes": [
        { "id": "class:src/utils/Mongo.ts:Mongo", "name": "Mongo", "kind": "class" }
      ]
    }
  ],
  "blast_radius": {
    "direction": "incoming",
    "max_distance": 3,
    "total_changed": 2,
    "total_affected": 8
  },
  "affected_nodes": [
    { "id": "...", "name": "Mongo", "kind": "class", "file": "src/utils/Mongo.ts", "lines": "10-50", "blast_distance": 0, "is_changed": true },
    { "id": "...", "name": "UserService", "kind": "class", "file": "src/services/UserService.ts", "lines": "5-80", "blast_distance": 1, "is_changed": false }
  ],
  "graph_summary": { "files": 107, "classes": 46, "functions": 332, "call_edges": 427, "import_edges": 146 }
}

visualize_blast_radius

Same analysis as analyze_blast_radius, but also generates an interactive 3D HTML visualization and opens it in the browser.

Parameter	Type	Required	Description
directory	string	yes	Absolute path to git repository
base_branch	string	no	Base branch to diff against (default: auto-detect)
output_dir	string	no	Output directory for HTML (default: <dir>/codemap-blast)
theme	string	no	clarity or cyberpunk (default: clarity)
include_files	boolean	no	Include file nodes (default: true)

Returns: Summary JSON + opens interactive blast radius visualization in default browser.

get_supported_languages

List programming languages supported for code structure analysis. No parameters.

Themes

• clarity — light, professional (grays, blues, greens)
• cyberpunk — dark, neon (cyan, lime, magenta on black)