🗺️ STEP 1: Map the codebase structure - start simple, then zoom in!

PROGRESSIVE DISCOVERY WORKFLOW:

1. First call: explore_repo("/path/to/project") - See directory structure only

2. Zoom in: explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)

3. Go deeper: explore_repo("/path/to/project", max_depth=3, include_symbols=True)

INPUTS:

• root_path: The ABSOLUTE path to the project (e.g., "/Users/john/myproject") NOT relative paths like "./myproject" or "~/myproject"

• max_depth: How deep to traverse directories (None = unlimited, accepts int or string)

• include_symbols: Show function/class signatures with docs (False = dirs only, accepts bool or string)

• focus_dirs: List of top-level directories to focus on (e.g., ["src", "lib"])

• max_symbols_per_file: Max symbols to show per file when include_symbols=True (accepts int or string)

EXAMPLE 1 - Initial exploration (directory only): explore_repo("/Users/john/project")

Returns:

/Users/john/project/

├── src/

├── tests/

├── docs/

└── README.md

EXAMPLE 2 - Zoom into src/ with symbols: explore_repo("/Users/john/project", focus_dirs=["src"], include_symbols=True)

Returns:

/Users/john/project/

└── src/

├── auth.py

│ ├── class AuthService: # Handles user authentication

│ ├── def authenticate(username, password): # Validates credentials

│ └── def logout(session_id): # Ends user session

└── models.py

├── class User(BaseModel): # User account model

└── ... and 3 more

EXAMPLE 3 - Limited depth exploration: explore_repo("/Users/john/project", max_depth=1, include_symbols=True)

Shows only top-level dirs and files with their symbols

💡 PRO TIP: Start with include_symbols=False to see structure, then set it to True for areas you want to examine in detail. This prevents information overload!

⚡ PERFORMANCE: Symbol extraction is cached per git commit - subsequent calls are instant!

WHAT TO DO NEXT:

• If you found interesting directories, zoom in with focus_dirs

• If you see relevant files, use find_symbol() to locate specific functions