Overview
The Code Explorer provides powerful tools for navigating, analyzing, and understanding code repositories. It offers multiple methods to search, view, and explore code structure programmatically.
Main class for code repository exploration and analysis.
Constructor
CodeExplorerTools(
repo_path: str,
work_dir: Optional[str] = None,
docker_work_dir: Optional[str] = None,
init_embeddings: bool = False
)
Local path of the code repository to analyze
Working directory for temporary files and operations
Docker working directory path (for containerized environments)
Whether to initialize vector embeddings for semantic code search
Core Methods
list_repository_structure
View the hierarchical structure of the repository.
def list_repository_structure(
path: Optional[str] = None
) -> Union[str, Dict]
Path to list structure (must be absolute path). If None, shows entire repository structure
explorer = CodeExplorerTools("/path/to/repo")
structure = explorer.list_repository_structure()
# Returns hierarchical view of files and folders
search_keyword_include_code
Search for text lines containing specific keywords and code snippets.
def search_keyword_include_code(
keyword_or_code: str,
query_intent: Optional[str] = None
) -> str
Keywords or code snippets to search for matches
Search intent describing what problem this search aims to solve
>>>
Example:
results = explorer.search_keyword_include_code(
"async def",
query_intent="Find all async function definitions"
)
search_keyword_include_files
Search for files whose names or paths contain specified patterns.
def search_keyword_include_files(pattern: str) -> str
Keywords to search for in file names or paths
files = explorer.search_keyword_include_files("config")
# Returns all files with 'config' in their path
view_filename_tree_sitter
Parse and display structure information of Python files.
def view_filename_tree_sitter(
file_path: str,
simplified: bool = True
) -> str
File path (only supports Python files)
Whether to use simplified view showing only structure without complete code
structure = explorer.view_filename_tree_sitter("src/utils.py")
# Output:
# ### Module: src.utils
#
# class Helper:
# '''Tool class...'''
# def format_data(data):
# # Format input data
view_class_details
View comprehensive class information including inheritance and methods.
def view_class_details(class_id: str) -> str
Class identifier (can be complete path like ‘src.models.User’ or simple name like ‘User’)
details = explorer.view_class_details("User")
# Shows complete class documentation and structure
view_function_details
View comprehensive function or method information.
def view_function_details(function_id: str) -> str
Function identifier (complete path like ‘src.utils.format_data’ or simple name like ‘format_data’)
details = explorer.view_function_details("format_data")
# Returns:
# # Function: format_data
# Module location: src.utils
# Parameters: data, format_type
# Return type: Dict[str, Any]
find_references
Find all places in codebase that reference a specified entity.
def find_references(
entity_id: str,
entity_type: str
) -> str
Entity identifier (can be complete path or simple name)
Entity type - must be one of: ‘function’, ‘class’, or ‘module’
refs = explorer.find_references("format_data", "function")
# Output:
# Function utils.format_data is called by following functions:
# - services.data_processor.process
# - api.endpoints.format_response
find_dependencies
Find dependencies of a specific entity.
def find_dependencies(
entity_id: str,
entity_type: str
) -> str
Entity identifier (can be complete path or simple name)
Entity type - must be one of: ‘function’, ‘class’, or ‘module’
deps = explorer.find_dependencies("UserService", "class")
# Shows all classes and functions that UserService depends on
view_file_content
View complete file content with intelligent summarization for large files.
def view_file_content(
file_path: str,
query_intent: Optional[str] = None
) -> str
File path or filename to view
Intent describing what to find in the file
content = explorer.view_file_content(
"src/models.py",
query_intent="Understand user authentication models"
)
check_file_dir
Check if a file or directory exists in the repository.
def check_file_dir(file_path: str) -> Optional[Dict]
Relative path or filename (like ‘src/utils.py’ or ‘README.md’)
{
"is_python_module": bool,
"abs_path": str,
"relative_path": str
}
Usage Example
from src.core.tool_code_explorer import CodeExplorerTools
# Initialize explorer
explorer = CodeExplorerTools(
repo_path="/path/to/repository",
work_dir="/tmp/workspace",
init_embeddings=True # Enable semantic search
)
# Explore repository structure
structure = explorer.list_repository_structure()
# Search for specific code patterns
results = explorer.search_keyword_include_code(
"class.*BaseModel",
query_intent="Find all model base classes"
)
# View class details
class_info = explorer.view_class_details("UserService")
# Find where a function is used
references = explorer.find_references("process_data", "function")
# Check dependencies
dependencies = explorer.find_dependencies("DataProcessor", "class")
Advanced Features
Vector Embeddings Search
When init_embeddings=True, the explorer supports semantic code search using vector embeddings and BM25 hybrid search:
explorer = CodeExplorerTools(
repo_path="/path/to/repo",
init_embeddings=True
)
# Semantic search combines keyword and vector similarity
results = explorer.search_keyword_include_code(
"authentication",
query_intent="Find user login and authentication logic"
)
Token Management
The explorer automatically manages content size using token limits:
- Large files are automatically summarized
- Code is intelligently truncated to show relevant portions
- Structure views are provided for very large modules
See Also