Dark Code Reader

Interactive codebase structure and execution flow visualization for VS Code. Understand any codebase at a glance — especially useful when working with AI-generated code.

Quick Start

1. Install from the VS Code Marketplace or install the .vsix file manually
2. Open any project in VS Code
3. Press Cmd+Shift+P (or Ctrl+Shift+P) and type Dark Code Reader: Analyze Workspace
4. A graph panel opens showing your file dependencies — click any file node to expand and see its functions, classes, and methods
5. Using an AI coding agent? Run Dark Code Reader: Connect AI Agent (MCP) from the command palette. This registers an MCP server that gives compatible AI agents direct access to your codebase analysis. Important: restart VS Code after connecting (Cmd+Q then reopen) — MCP servers are discovered at agent startup. Then ask your agent: "What tools do you have from darkcodeReader?"

No configuration needed. No API keys. Everything runs locally.

Features

Structure Graph

Visualize how your codebase is connected without running any code.

• File-first view — starts with a clean file-level dependency map
• Click to expand — click any file to reveal its functions, classes, and methods inside a colored container
• Nested directory hulls — files are grouped by directory with colored boundaries, nested to reflect the folder hierarchy
• Draggable groups — grab any colored hull to move an entire directory or file group
• Sticky positioning — drag individual nodes to arrange the graph; they stay put (gold glow indicates pinned). Double-click to unpin.
• Entry point detection — index, main, app, manage.py, wsgi.py etc. are automatically identified with a gold star and pinned as layout anchors
• Curved edges with arrowheads showing dependency direction
• Edge type toggles — show/hide Imports, Calls, Extends independently
• Hover highlighting — hover any node to see its connections light up; everything else dims
• Click selection — click a node to lock the highlight, see details panel with code preview, connected nodes get larger labels
• Code preview — syntax-highlighted code snippet in the details panel with line numbers
• Non-destructive search — type to filter; non-matching nodes fade but stay in place
• Semantic zoom — labels auto-adjust based on zoom level
• Minimap — always-visible overview in the corner showing your viewport position
• Spacing slider — adjust how spread out the graph is
• Reset button — return to the initial file-only view

Node Sizing

Switch the Size dropdown in the toolbar to encode meaning into node size:

• Connections (default) — file size reflects how many other files depend on it; hubs stand out
• Lines of Code — log-scaled so small utilities and 2000-line monsters read on the same graph
• Default — grows with child count (functions/classes inside)
• Uniform — flat size for pure topology focus

Dead Code Detection

Files with zero incoming dependencies and no recent git commits are automatically marked with a red dot — potential dead code candidates.

Execution Tracing

See what actually happens when your code runs.

• Node.js tracing — Chrome DevTools Protocol profiler (near-zero overhead)
• Python tracing — VizTracer (if installed) or sys.settrace fallback
• Timeline scrubber — step through execution chronologically with play/pause/step controls, speed selector, and active node highlighting
• Named traces — save traces with descriptive names to .darkcodeReader/traces/ for later comparison
• Flame chart and flow views

AI Agent Integration (MCP)

Dark Code Reader includes an MCP server that gives any MCP-compatible AI agent direct tool access to your codebase analysis.

Setup:

1. Run Dark Code Reader: Analyze Workspace
2. Run Dark Code Reader: Connect AI Agent (MCP)
3. Restart VS Code (Cmd+Q / Ctrl+Q, then reopen) — MCP servers are discovered at agent startup
4. Ask your agent: "What tools do you have from darkcodeReader?"

Tools available over MCP:

Static data files also available in .darkcodeReader/ (summary.json, dependencies.json, etc.) and auto-update when code changes.

Layout Persistence

Your graph layout saves to .darkcodeReader/layout.json — node positions, expanded files, spacing. Reopening VS Code restores exactly where you left it. Use the Reset button to start fresh.

SVG Export

Click "Export" in the toolbar to save the current graph view as an SVG file in .darkcodeReader/.

How to Use

Three ways to start

Commands

Graph interactions

Supported Languages

Settings

Performance

• Small projects (<100 files): Full TypeScript Compiler API analysis with type-checked call graphs
• Large projects (100+ files): Automatic fast mode using regex-based scanning (~100x faster)
• Very large projects (500+ files): Capped at maxNodes most-connected files, streaming analysis
• File finder: Uses VS Code's indexed workspace for fast file discovery

How It Works

Static Analysis

• TypeScript/JavaScript (small projects): TypeScript Compiler API — reads tsconfig.json, creates a type-checked program, walks the AST for imports, declarations, and call relationships.
• TypeScript/JavaScript (large projects): Regex-based scanner — extracts imports via import/require patterns, counts functions/classes, computes line counts. No type checking.
• Python: Spawns a subprocess using Python's ast module (no external dependencies).
• Other languages: File-level nodes with regex-based cross-reference detection.

Intelligence Files

Generated after analysis and auto-updated on file changes:

• Complexity: Counts branching keywords (if, elif, for, while, catch, &&, ||, ternary) per function.
• Clusters: Connected components in the dependency graph, labeled by directory and inferred purpose.
• Surfaces: Regex extraction of export function, export class, def, class declarations.
• Staleness: Compares file modification times against dependency modification times.

Runtime Tracing

• Node.js: --inspect + Chrome DevTools Protocol CPU Profiler.
• Python: VizTracer (C-level instrumentation, auto-detected) or sys.settrace fallback.

Development

git clone https://github.com/goldwinstewart/DarkCodeReader.git
cd DarkCodeReader
npm install
npm run build        # Build once
npm run watch        # Watch mode
# Press F5 in VS Code to launch Extension Development Host
node test/smoke-test.mjs  # Run tests

Project Structure

src/
  extension.ts              Main entry, command registration, file watcher
  analyzers/
    TypeScriptAnalyzer.ts   TS/JS analysis (full + fast + streaming modes)
    PythonAnalyzer.ts       Python analysis via ast module
    AnalyzerFactory.ts      Language detection, fast mode routing
  tracers/
    NodeInspectorTracer.ts  JS/TS runtime tracing via CDP
    PythonTracer.ts         Python tracing (VizTracer + sys.settrace)
  graph/
    GraphBuilder.ts         Transforms analysis into graph data
    GraphFilter.ts          Search and filter logic
  webview/
    WebviewManager.ts       Webview panel, HTML, CSP, messaging
  mcp/
    McpServer.ts            Graph data files for AI agents
  utils/
    entryPoints.ts          Entry point detection patterns
    gitStats.ts             Git log parsing for activity/authors
    intelligence.ts         Complexity, clusters, surfaces, staleness
    fileUtils.ts            File discovery and language detection

webview-ui/
  src/
    main.ts                 Webview entry, toolbar, legend, timeline
    graphs/
      StructureGraph.ts     D3.js force-directed graph with hulls
      ExecutionGraph.ts     Flame chart / flow graph
    styles/
      main.css              Full visual styling

License

MIT