Codesight

Codesight

Visualize any codebase as an interactive, drillable graph — from high-level directories down to individual functions.

Codesight uses tree-sitter to parse your code, extract symbols, resolve imports, and build call graphs. Everything renders as a navigable map inside VS Code. No LLM required for the core experience.

Supports TypeScript, JavaScript, Python, C, C++, and Java.

---

Install

Prerequisites: Node.js 18+, VS Code 1.90+, Git

git clone https://github.com/spirituslab/codesight.git
cd codesight
npm install
cd vscode
npm install
npm run build
npx @vscode/vsce package --allow-missing-repository
code --install-extension codesight-0.1.1.vsix

That's it. Now open any project in VS Code and run:

Ctrl+Shift+P → Codesight: Open Graph

The graph appears with your project's structure.

---

The Graph

The graph works like a file explorer — click to drill in, breadcrumbs to go back:

Directories → Folders (as deep as your project goes) → Files → Symbols

Each level shows import relationships and call edges between items. Deeply nested projects work fine — folder drill-down is recursive.

Node Shapes

| Shape | Meaning | |-------|---------| | Rounded rectangle | Directory / module (L1) | | Barrel | Subfolder (L2) | | Cut rectangle | File (L2/L3) | | Rounded rectangle | Function / method (L4) | | Hexagon | Class / struct (L4) | | Diamond | Interface / type (L4) | | Octagon | Enum (L4) | | Tag | Constant (L4) |

Navigation

| Action | What it does | |--------|-------------| | Click node | Drill down into it | | Click symbol node | Opens the file at that line in VS Code | | ← button | Go back one level | | Breadcrumb path | Click any segment to jump to that level | | Ctrl+K | Global search across all nodes |

Commands

| Command | Description | |---------|-------------| | Codesight: Open Graph | Analyze and show the graph | | Codesight: Refresh Analysis | Re-analyze after code changes | | Codesight: Generate Idea Layer | Generate AI conceptual overlay (needs Copilot or Claude Code) | | Reveal in Codesight Graph | Right-click a file in the editor → find it in the graph |

---

Idea Layer

The idea layer is a second graph that shows what your project does — features, responsibilities, architecture — with lines connecting each concept to the code that implements it.

How to generate it

You need either GitHub Copilot or Claude Code. Pick whichever you have:

Option A — GitHub Copilot:

1. Install the GitHub Copilot extension and sign in
2. Ctrl+Shift+P → Codesight: Generate Idea Layer

Option B — Claude Code:

1. Install Claude Code and add codesight to your project's MCP config (see [MCP Setup](#setup) below)
2. In your terminal, ask:

> Generate the idea layer for this project

> Note for large projects: After Claude Code generates the idea layer, run Ctrl+Shift+P → Codesight: Refresh Analysis to have it display in the graph. The file watcher may not pick up the change automatically on larger codebases.

Using the idea layer

| Action | What it does | |--------|-------------| | Click idea node | Highlights mapping lines to the code layer | | Click background | Clears highlights |

The idea layer persists across refreshes — when you refresh the code analysis, the idea layer stays. Mappings to renamed or deleted code silently fade out.

---

MCP Integration (Claude Code)

Codesight exposes structural intelligence as MCP tools for Claude Code. These give Claude access to call graphs, impact analysis, and code structure that it can't get from reading files alone.

Setup

Run this from the codesight directory to register MCP in any project:

node analyze.mjs init ~/path/to/your/project

This creates a .mcp.json in that project with the correct path to codesight's MCP server. Then start Claude Code in that project — the tools are available immediately.

You can also create .mcp.json manually:

{
  "mcpServers": {
    "codesight": {
      "command": "node",
      "args": ["/path/to/codesight/mcp-server.mjs", "."]
    }
  }
}

Tools

| Tool | Description | |------|-------------| | codesight_explore | Navigate the code structure — project overview, module details, file symbols, or symbol callers/callees | | codesight_impact | What breaks if you change a file or symbol — direct and transitive dependents with risk levels | | codesight_trace | Find the call path between two functions | | codesight_search | Search for functions, classes, or types by name across the project | | codesight_idea_layer | Generate or push a conceptual idea layer overlay to the VS Code graph | | codesight_refresh | Re-run analysis to pick up file changes |

Example prompts

> Explore the src module
> What would break if I change src/auth/service.ts?
> Trace the call path from handleRequest to saveToDatabase
> Search for all classes in the project
> Generate the idea layer for this project

You don't need to name the tools — just ask naturally and Claude will use the right one.

---

CLI

Export analysis as JSON for CI or scripting (no VS Code required):

node analyze.mjs /path/to/project --json > analysis.json
node analyze.mjs /path/to/project -o analysis.json
node analyze.mjs /path/to/project --max-files 1000

| Flag | Description | |------|-------------| | --json | Output raw JSON to stdout | | -o, --output | Write analysis JSON to a file | | --max-files N | Maximum files to analyze (default: 5000) |

---

Supported Languages

| Language | Symbols | Imports | Call Graph | |----------|---------|---------|------------| | TypeScript / JavaScript | Functions, classes, interfaces, types, enums, constants | ES imports, re-exports, path aliases | Full with confidence scoring | | Python | Functions, classes, constants | import, from...import, relative imports | Full | | C | Functions, structs, unions, enums, typedefs | #include (local and system) | Full | | C++ | Classes, namespaces, templates + all C | #include, using declarations | Full | | Java | Classes, interfaces, enums, methods | Package imports, wildcards, static imports | Full | | C# | Classes, interfaces, structs, enums, methods, properties | using directives | Full | | Go | Functions, methods, structs, interfaces | import declarations | Full | | Rust | Functions, structs, enums, traits, impl methods, consts | use declarations | Full |

---

Analysis Features

Circular Dependency Detection

Codesight detects circular dependencies between modules (e.g., A imports B, B imports C, C imports A). Cycles are highlighted with red edges in the L1 graph and listed in the explorer sidebar.

Dead Code Detection

Codesight flags exported symbols that are never imported or called anywhere in the project. Results appear in the explorer sidebar under "Dead Code".

Caveat: Dead code detection uses static import and call graph analysis only. It will produce false positives for:

• Web components registered via customElements.define() (not imported by name)
• Framework entry points like activate/deactivate in VS Code extensions (called by the runtime)
• Dynamically imported functions called via import() expressions inside conditionals
• Public API symbols exported for external consumers but not used internally

Treat the results as "potentially dead" — a starting point for review, not a definitive list.

---

Development

npm test              # Run tests
npm run test:watch    # Watch mode

cd vscode
npm run build         # Build extension
npm run watch         # Watch mode for extension

Debug the extension:

1. Open the vscode/ folder in VS Code
2. Press F5 — launches a new VS Code window with the extension loaded
3. Open any project in that window and run Codesight: Open Graph

Web UI and the extension

The web UI source lives in web/src/ at the repo root. The VS Code extension serves these files from vscode/web/src/ at runtime. To avoid maintaining two copies, vscode/web is a symlink to the root web/ directory. This means edits to web/src/ are immediately available to the extension — no copy step needed.

If the symlink is missing (e.g., after a fresh clone on Windows), recreate it:

# From the repo root
ln -s "$(pwd)/web" vscode/web

> Note: The installed extension (in ~/.vscode/extensions/ or ~/.vscode-oss/extensions/) is a separate copy. During development, you can replace it with a symlink to vscode/ so changes take effect without reinstalling: > > ``bash > rm -rf ~/.vscode-oss/extensions/codesight.codesight- > ln -s /path/to/codesight/vscode ~/.vscode-oss/extensions/codesight.codesight- > `` > > After this, just reload the VS Code window to pick up changes.

---

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: spirituslab
• Source: spirituslab/codesight
• License: MIT

Install and usage instructions live in the source repository linked above.