🗺️ 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

🔍 STEP 2: Find specific functions, classes, or methods in the codebase.

USE THIS AFTER explore_repo() when you need to locate a specific piece of code. Uses fuzzy matching - you don't need the exact name!

INPUTS:

• root_path: Same ABSOLUTE path used in explore_repo

• query: What you're looking for (fuzzy search works!) Examples: "auth", "user service", "validate", "parseJSON"

EXAMPLE INPUTS: find_symbol("/Users/john/awesome-project", "authenticate") find_symbol("/Users/john/awesome-project", "user model") # Fuzzy matches "UserModel"

EXAMPLE OUTPUT: [ { "name": "authenticate_user", "type": "function", "path": "/Users/john/awesome-project/src/auth.py", "start_line": 45, "end_line": 67 }, { "name": "AuthService", "type": "class", "path": "/Users/john/awesome-project/src/services.py", "start_line": 12, "end_line": 89 } ]

RETURNS: List of symbol objects (dictionaries). Save these objects - you'll pass them to what_breaks()! Empty list if no matches found.

WHAT TO DO NEXT: Pick a symbol from the results and pass THE ENTIRE SYMBOL OBJECT to what_breaks() to see where it's used in the codebase.

📖 READ INTERFACE: Get a high-level overview of a file without reading implementation.

Returns function signatures, class definitions, and docstrings. Perfect for understanding how to USE a module without reading the whole thing.

INPUTS:

• root_path: The ABSOLUTE path to the project root

• file_path: The path to the specific file you want to read (can be relative to root)

EXAMPLE: read_interface("/Users/john/project", "src/auth.py")

💥 STEP 3: See what code might break if you change this symbol.

USE THIS AFTER find_symbol() to understand the impact of changing a function/class.

IMPROVEMENTS:

• Uses structural search (ast-grep) to find ACTUAL code references (ignoring comments/strings).

• Returns 2 lines of context around each match.

INPUT:

• exact_symbol: Pass THE ENTIRE SYMBOL OBJECT from find_symbol(), not just the name! Must be a dictionary with AT LEAST 'name' and 'path' keys.

EXAMPLE INPUT:

First, get a symbol from find_symbol():

symbols = find_symbol("/Users/john/project", "authenticate") symbol = symbols[0] # Pick the first result

Then pass THE WHOLE SYMBOL OBJECT:

what_breaks(symbol)

EXAMPLE OUTPUT: { "references": [ { "file": "/Users/john/project/src/api.py", "line": 23, "text": " # Authenticate the user user = authenticate_user(username, password) if not user:", "type": "code" } ], "total_count": 1, "strategy": "structural", "note": "Found 1 references using structural search." }