Codebase Visualizer

Overview

The Codebase Visualizer creates interactive HTML visualizations of your project structure, helping you understand architecture, identify patterns, and document your codebase.

SKILL.md Template

---
name: codebase-visualizer
description: Generate interactive visual maps of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python:*)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

This creates codebase-map.html in the current directory and opens it in your default browser.

What the Visualization Shows

• Collapsible directories: Click folders to expand/collapse
• File sizes: Displayed next to each file
• Colors: Different colors for different file types
• Directory totals: Shows aggregate size of each folder
• Summary sidebar: File count, total size, file types breakdown

## Supporting Script

Create `~/.claude/skills/codebase-visualizer/scripts/visualize.py`:

```python
#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({
                    "name": item.name,
                    "size": size,
                    "ext": ext
                })
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {
        "files": 0,
        "dirs": 0,
        "extensions": Counter(),
        "ext_sizes": Counter()
    }
    data = scan(target, stats)
    # Generate HTML visualization...

Example Visualization Features

Summary Sidebar

📊 Summary
─────────────────
Files         1,234
Directories     156
Total size   45.2 MB
File types      23

By file type
─────────────────
.ts    ████████  45%
.tsx   █████     28%
.json  ███       15%
.md    ██        12%

Interactive Tree

📁 src/ (12.3 MB)
├── 📁 components/ (3.2 MB)
│   ├── 📁 ui/ (1.1 MB)
│   │   ├── Button.tsx (2.3 KB)
│   │   ├── Input.tsx (1.8 KB)
│   │   └── Modal.tsx (3.1 KB)
│   └── 📁 layout/ (2.1 MB)
├── 📁 services/ (4.5 MB)
└── 📁 utils/ (1.2 MB)

Usage

/codebase-visualizer

Or ask naturally:

Visualize this codebase structure

Use Cases

1. Onboarding - Help new team members understand the project
2. Architecture review - Identify structural issues
3. Documentation - Generate visual architecture docs
4. Size analysis - Find large files or directories
5. Dependency mapping - Understand module relationships

Customization

Modify the IGNORE set to exclude or include specific directories:

IGNORE = {
    '.git',
    'node_modules',
    '__pycache__',
    'coverage',      # Add test coverage
    '.next',         # Add Next.js build
}

Output Formats

The skill can generate:

• HTML - Interactive browser visualization
• ASCII - Terminal-friendly tree output
• JSON - Machine-readable structure data
• Mermaid - Diagram syntax for documentation