codebase-index

Roger-Parkinson-EHP's avatarfrom Roger-Parkinson-EHP

Quickly index and understand a codebase's architecture. Use at session start to get up to speed fast. Finds entry points, API routes, classes, models, configs, and patterns.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026
[Architecture Design]

When & Why to Use This Skill

Codebase Index is a high-efficiency Claude skill designed for rapid architectural discovery and codebase mapping. It enables developers to instantly identify entry points, API routes, data models, and configuration patterns using optimized search commands, significantly reducing the time required to gain context in unfamiliar or complex repositories while maintaining token efficiency.

Use Cases

  • Rapid Project Onboarding: Quickly map the structure of a new repository to understand component interactions and entry points without manual file-by-file inspection.
  • Context Recovery: Re-establish a mental map of the project after a session break or context window compaction by identifying core classes, functions, and architectural patterns.
  • API and Route Discovery: Instantly locate and list all REST endpoints or internal API routes across various frameworks such as FastAPI, Express, Flask, and Django.
  • Architectural Pattern Analysis: Identify project dependencies, database models (SQLAlchemy, Prisma, etc.), and common design patterns like dependency injection or decorators to ensure consistency.
namecodebase-index
descriptionQuickly index and understand a codebase's architecture. Use at session start to get up to speed fast. Finds entry points, API routes, classes, models, configs, and patterns.
allowed-toolsBash, Read, Grep, Glob

Codebase Index - Fast Architecture Discovery

Get up to speed on any codebase in seconds, not minutes.

When to Use

  • Session startup - First thing after entering a new repo
  • Context recovery - After compaction, understand what you're working with
  • New project - Quickly map an unfamiliar codebase
  • Architecture review - Find patterns and structure

Quick Start Commands

Run these in sequence to build a mental map:

1. Entry Points (Where does it start?)

# Python entry points
rg "if __name__.*main" --type py -l

# Node/TypeScript entry points
rg "^(export default|module\.exports)" --type ts --type js -l | head -20

# Main files
ls -la **/main.* **/index.* **/app.* 2>/dev/null | head -20

2. API Endpoints (What does it expose?)

# FastAPI routes
rg "@(app|router)\.(get|post|put|delete|patch)" --type py -n | head -30

# Flask routes
rg "@.*\.route\(" --type py -n | head -30

# Express routes
rg "(app|router)\.(get|post|put|delete)\(" --type js --type ts -n | head -30

# Cloud Functions
rg "functions_framework|@functions\." --type py -n

3. Classes & Core Definitions

# Python classes
rg "^class \w+" --type py -n | head -40

# TypeScript/JS classes and interfaces
rg "^(export )?(class|interface|type) \w+" --type ts -n | head -40

# Python functions (top-level only)
rg "^def \w+" --type py -n | head -40

4. Database Models

# SQLAlchemy models
rg "class.*\(.*Base\)|class.*Model\):" --type py -n

# Prisma models
rg "^model \w+" --glob "*.prisma"

# Django models
rg "class.*models\.Model" --type py -n

# Pydantic models
rg "class.*\(.*BaseModel\)" --type py -n

5. Configuration & Environment

# Find config files
fd -e yaml -e yml -e toml -e ini -e json -e env 2>/dev/null | grep -i config | head -20

# Environment variable usage
rg "os\.environ|os\.getenv|process\.env" -n | head -30

# Settings/config classes
rg "class.*(Config|Settings)" --type py -n

6. Tests Structure

# Find test files
fd -e py -e ts -e js | grep -i test | head -20

# Test classes and functions
rg "^(class Test|def test_|describe\(|it\()" --type py --type ts --type js -n | head -30

7. Key Imports (Dependencies)

# Most imported packages (Python)
rg "^(from|import) " --type py | cut -d' ' -f2 | cut -d'.' -f1 | sort | uniq -c | sort -rn | head -20

# Package.json dependencies
cat package.json 2>/dev/null | grep -A 50 '"dependencies"' | head -30

8. Architecture Patterns

# Decorators (Python)
rg "^@\w+" --type py | cut -d':' -f2 | sort | uniq -c | sort -rn | head -15

# Dependency injection
rg "Depends\(|@inject|@Inject" --type py --type ts -n

# Error handling patterns
rg "class.*Exception|class.*Error\(" --type py -n

# Logging setup
rg "logging\.(getLogger|basicConfig)|logger = " --type py -n | head -15

Language-Specific Quick Indexes

Python Project

# One-liner: core structure
rg "^(class |def |@app\.|@router\.)" --type py -n | head -50

TypeScript/Node Project

# One-liner: core structure
rg "^(export |class |interface |function |\s*(get|post)\()" --type ts -n | head -50

Go Project

# One-liner: core structure
rg "^(func |type .* struct)" --type go -n | head -50

Full Codebase Snapshot

Run this to get a complete picture:

echo "=== ENTRY POINTS ===" && rg "if __name__|^func main" --type py --type go -l 2>/dev/null
echo "=== API ROUTES ===" && rg "@(app|router)\.(get|post|put|delete)" --type py -c 2>/dev/null
echo "=== CLASSES ===" && rg "^class " --type py -c 2>/dev/null | head -10
echo "=== CONFIG FILES ===" && fd -e yaml -e toml -e env 2>/dev/null | head -10
echo "=== TEST FILES ===" && fd test --type f 2>/dev/null | wc -l

Pro Tips

Tip Why
Use -c (count) first See scope before diving in
Use -l (files only) Find relevant files, then read them
Pipe to head Don't overwhelm context with output
Chain with grep -i topic Filter results to what you care about
Use --type flags Focus on relevant file types

Token Efficiency

All commands return summaries, not full files. A complete codebase index typically uses <500 tokens while giving you the mental map to know exactly what to read next.

  • index-docs: Markdown heading extraction
  • search-history: Find past discussions about this codebase
  • post-compact: Full context recovery workflow