codebase-explorer

Codebase Explorer

Expert guidance for exploring and understanding codebases.

Exploration Strategy

Phase 1: High-Level Structure

# Get directory tree (limit depth)
tree -L 2 -d

# List top-level contents
ls -la

# Check for documentation
ls README* CONTRIBUTING* docs/ doc/

Phase 2: Project Detection

# Identify project type by manifest files
ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle Gemfile

Phase 3: Deep Dive

# Entry points
cat main.py src/index.js cmd/main.go

# Configuration
cat config/*.yaml .env.example

# Dependencies
cat package.json requirements.txt Cargo.toml

Project Type Detection

File	Project Type	Next Steps
package.json	Node.js	Check scripts, dependencies
pyproject.toml	Python (modern)	Check [project], [tool.*]
requirements.txt	Python (legacy)	Check dependencies
Cargo.toml	Rust	Check [package], [dependencies]
go.mod	Go	Check module path, dependencies
pom.xml	Java (Maven)	Check <dependencies>
build.gradle	Java (Gradle)	Check dependencies block
Gemfile	Ruby	Check gems
composer.json	PHP	Check require
Makefile	C/C++/Generic	Check targets

Finding Key Components

Entry Points

# Common entry point names
find . -name "main.*" -o -name "index.*" -o -name "app.*" | head -20

# Scripts directory
ls bin/ scripts/ cmd/

Configuration

# Config files
find . -name "*.config.*" -o -name "*.yaml" -o -name "*.toml" | grep -v node_modules

Tests

# Test directories and files
find . -type d -name "test*" -o -type d -name "__tests__"
find . -name "*test*.py" -o -name "*.test.js" -o -name "*_test.go"

API/Routes

# Common API patterns
grep -r "app\.\(get\|post\|put\|delete\)" --include="*.js" --include="*.ts"
grep -r "@app\.route\|@router" --include="*.py"
grep -r "func.*Handler\|http\.Handle" --include="*.go"

Code Search Patterns

Find Function Definitions

# Python
grep -rn "^def \|^async def \|^class " --include="*.py"

# JavaScript/TypeScript
grep -rn "function \|const .* = \|class " --include="*.js" --include="*.ts"

# Go
grep -rn "^func " --include="*.go"

Find Imports/Dependencies

# Python
grep -rn "^import \|^from .* import" --include="*.py"

# JavaScript
grep -rn "^import \|require(" --include="*.js" --include="*.ts"

# Go
grep -rn "^import" --include="*.go"

Find TODO/FIXME

grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.py" --include="*.js" --include="*.go"

Architecture Analysis

Dependency Graph

# NPM
npm ls --depth=0

# Python
pip list

# Cargo
cargo tree --depth=1

Code Statistics

# Lines of code by type
find . -name "*.py" | xargs wc -l | tail -1
find . -name "*.js" -not -path "*/node_modules/*" | xargs wc -l | tail -1

# File counts
find . -name "*.py" | wc -l

Output Template

When exploring a codebase, structure findings as:

📁 Project: {name}
📋 Type: {language} ({framework})
📦 Package Manager: {manager}

## Structure
{tree output, annotated}

## Key Files
- {file}: {purpose}
- {file}: {purpose}

## Dependencies
{key dependencies with versions}

## Entry Points
- {main entry point}
- {API entry if applicable}

## Architecture Notes
{observations about patterns, structure}

Tips

1. Start broad, go deep - Tree first, then specific files
2. Follow imports - Trace from entry point
3. Read tests - They document expected behavior
4. Check CI/CD - .github/workflows/, .gitlab-ci.yml reveal build process
5. Look for docs - docs/, doc/, wiki, README sections