Codebase Exploration with Srclight

Systematic approach to understanding a codebase using structural analysis rather than reading files sequentially.

Level 1: Project Overview (30 seconds)

codebase_map()       → languages, file counts, symbol counts, directory structure
list_projects()      → all repos in workspace (if multi-repo)

Summarize: what languages, how big, how the directories are organized.

Level 2: Key Symbols (2 minutes)

hybrid_search("main entry point")    → find entry points
hybrid_search("config setup init")   → find initialization code
symbols_in_file("src/main.*")        → entry point symbols

Identify the top-level functions/classes that organize the application.

Level 3: Architecture Mapping (5 minutes)

For each key symbol identified:

get_callees(symbol, project)         → what it depends on
get_callers(symbol, project)         → what depends on it
get_type_hierarchy(symbol, project)  → inheritance structure
get_implementors(interface, project) → concrete implementations

Build a mental model: entry points → core logic → data layer → external interfaces.

Level 4: Subsystem Deep Dive

When the user asks about a specific area:

hybrid_search("topic keywords")     → find relevant symbols
get_symbol(name)                     → read the full source
get_callees(symbol, project)         → trace the flow downward
get_callers(symbol, project)         → trace usage upward
find_imports(path, project)          → understand dependencies

Level 5: History and Health

git_hotspots(project=project)        → most-changed files (complexity magnets)
recent_changes(project=project)      → what's been worked on lately
find_dead_code(project)              → unused code to ignore

Hotspots indicate where most development effort goes. Dead code can be ignored during exploration.

Exploration Strategies

Top-Down (recommended for new codebases)

1. codebase_map() → directory overview
2. Find entry points → hybrid_search("main app server")
3. Trace outward from entry points → get_callees()
4. Dive into interesting subsystems

Bottom-Up (when investigating a specific feature)

1. hybrid_search("feature keywords") → find relevant code
2. Read the symbol → get_symbol(name)
3. Trace upward → get_callers() to find who uses it
4. Trace downward → get_callees() to find what it uses

Change-Driven (when onboarding to active development)

1. recent_changes() → what's being worked on
2. git_hotspots() → where most effort goes
3. Focus exploration on active areas

Presenting Findings

When summarizing a codebase to the user, organize by:

1. Purpose: What the project does (from README/entry points)
2. Architecture: Major subsystems and how they connect
3. Key Files: The most important files to understand
4. Entry Points: Where execution starts
5. Hot Areas: Where active development happens