codebase-visualizer

Overview

codebase-visualizer generates an interactive tree of your repository's structure. It's designed for quickly understanding project layout when exploring a new repo or getting orientation of modules, folders, and components. This helps teams spot organization gaps and plan refactors more efficiently.

How This Skill Works

From the repository root, the tool runs a Python script located at .claude/skills/codebase-visualizer/scripts/visualize.py to scan the codebase and build a hierarchical tree. It outputs codebase-map.html and opens it in your default browser for interactive exploration.

When to Use It

• When you open a new repository and want to understand its structure quickly
• During onboarding to show teammates how the project is organized
• When inspecting a monorepo to identify module boundaries and directories
• Before refactoring to spot oversized folders or tightly coupled components
• Before starting a code review to grasp dependencies and file ownership

Quick Start

1. Step 1: Open your terminal at the repo root
2. Step 2: Run python .claude/skills/codebase-visualizer/scripts/visualize.py .
3. Step 3: The tool creates codebase-map.html and opens it in your browser

Best Practices

• Run from the project root to ensure accurate path resolution
• Ensure Python is available and the repository permissions allow script execution
• Refresh the visualization after major structure changes
• Use the browser's zoom and search to focus on specific folders
• Document notable insights or bottlenecks found in the map

Example Use Cases

• Onboarding a junior dev to a Python project by showing package layout
• Exploring a new JS monorepo to locate shared utilities
• Identifying oversized directories before a performance audit
• Mapping dependencies and coupling by visualizing subfolder relationships
• Comparing branch structures to spot added or removed modules

Frequently Asked Questions