explore_repo
Progressively map codebase structure: start with directories, then zoom into folders with function and class symbols. Cached per git commit for instant subsequent calls.
Instructions
🗺️ STEP 1: Map the codebase structure - start simple, then zoom in!
PROGRESSIVE DISCOVERY WORKFLOW:
First call: explore_repo("/path/to/project") - See directory structure only
Zoom in: explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| root_path | Yes | ||
| max_depth | No | ||
| include_symbols | No | ||
| focus_dirs | No | ||
| max_symbols_per_file | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |