Getting Started

Getting Started

This guide walks you through your first run of codebase-vis on any project.

Step 1: Initialize

cd my-project
codebase-vis init

This creates a .agentignore file in your project root. It detects your tech stack and generates sensible defaults — ignoring node_modules/, dist/, .next/, venv/, target/, and other build artifacts automatically.

The .agentignore file is yours to edit. Add any additional patterns you want to exclude.

Step 2: Generate the Graph

codebase-vis generate

This is the main pipeline. It:

1. Discovers all source files in your project (respecting .agentignore)
2. Checks cache — unchanged files skip re-parsing
3. Parses changed files in parallel using a worker pool (CPU count - 1 workers)
4. Builds a directed dependency graph
5. Enriches it with Louvain community detection
6. Exports graph.json and graph.html to codebase-out/

Generate with Options

codebase-vis generate src/ tests/              # Only scan specific directories
codebase-vis generate --ignore tests,fixtures  # Additional ignore patterns
codebase-vis generate --jobs 4                 # Override worker count
codebase-vis generate --verbose                # Detailed logging
codebase-vis generate --no-clear               # Keep previous terminal output

Step 3: Serve the Visualizer

codebase-vis serve

Starts a local server at http://localhost:3000 and opens your browser automatically.

Features in the Visualizer

• ForceAtlas2 physics — nodes repel and settle into a readable layout
• Community legend — toggle visibility of entire modules (color-coded)
• Fuzzy search — find any file or entity by name
• Click to inspect — see dependencies, language, connection count
• Dependency/entity toggles — show/hide npm packages and inline entities
• Minimap — navigate large graphs (press M to toggle)
• Cycle overlay — highlight circular dependencies in red (after running detect)

Custom Port

codebase-vis serve --port 4000

Next Steps

• Explore the Commands section for detailed docs on each command
• Run codebase-vis query <file> to inspect a specific file's dependencies
• Run codebase-vis path <source> <target> to trace dependency chains
• Run codebase-vis detect to find circular dependencies
• Read the Architecture Overview to understand how it works under the hood