Codebase Exploration Agents
Relevant source files
The following files were used as context for generating this wiki page:
Codebase Exploration Agents are specialized sub-agents within the Continuous Claude ecosystem designed to perform token-efficient research, analysis, and navigation of large source code repositories. These agents utilize high-performance tools like repomix for compressed codebase packing and morph (WarpGrep) for rapid pattern matching, enabling them to understand complex architectures without exhausting context limits.
These agents are typically invoked via specific sub-agent configurations and primary execution scripts to handle multi-step research workflows that require cross-validation or data processing pipelines.
Sources: CLAUDE.md:28-36, CLAUDE_ONBOARDING.md:46-55, .claude/agents/codebase-explorer.md
Agent Specialized Roles
The exploration framework is divided into distinct agent configurations, each optimized for a specific stage of codebase interaction.
Explorer Agent (/codebase-explorer)
The Explorer agent is responsible for high-level codemapping. It utilizes repomix to generate compressed codebase structures, providing an overview with token-count trees. It is the primary tool for gaining an initial understanding of a "brownfield" codebase.
Analyzer Agent (/codebase-analyzer)
This agent focuses on deep structural analysis. It investigates relationships between modules and evaluates architectural patterns. It often works in conjunction with memory search tools to understand the evolution of the codebase across sessions.
Locator and Pattern Finder
The Locator agent is optimized for finding specific files or line ranges relevant to a feature request. The Pattern Finder specifically utilizes AST-based search (e.g., ast-grep) or WarpGrep to find implementation patterns, such as authentication handlers or specific API route structures.
Sources: .claude/agents/codebase-explorer.md, .claude/agents/codebase-analyzer.md, .claude/agents/codebase-locator.md, .claude/agents/codebase-pattern-finder.md, CLAUDE.md:14-23
Core Exploration Workflow
The exploration process follows a "Progressive Disclosure" pattern to save tokens. Agents start with broad, compressed overviews and drill down into specific files only when necessary.
The diagram above shows the standard flow from initial overview to detailed file analysis, culminating in a state update to preserve context across sessions.
Sources: CLAUDE.md:200-210, CLAUDE_ONBOARDING.md:22-29, servers/morph/README.md
Primary Exploration Tools
Codebase exploration agents rely on a suite of underlying tools and MCP servers to interact with the filesystem and external data sources.
| Tool | Purpose | Performance / Benefit |
|---|---|---|
| repomix | Compressed codebase packing | ~50% token reduction; XML/Markdown styles |
| Morph (WarpGrep) | Parallel grep codebase search | 20x faster than standard grep; multi-turn subagent |
| ast-grep | AST-based code pattern matching | Precise identification of syntactic structures |
| morph__edit_file | Selective file editing | 10,500+ tokens/sec; prevents context pollution |
| Grep (Built-in) | Local search fallback | Always available offline |
Sources: CLAUDE.md:14-23, CLAUDE_ONBOARDING.md:65-75, servers/morph/README.md
Morph Search & WarpGrep Logic
The morph MCP server provides warpgrep_codebase_search, which invokes a specialized search subagent. This subagent runs parallel grep and readfile calls over multiple turns to locate relevant line ranges based on natural language queries.
# Example Morph Search usage via script
# Sources: [scripts/morph_search.py:44-53](https://github.com/marlon-costa-dc/Continuous-Claude-v2/blob/a6585db6003235e583c0df07db5103ecda0af03f/scripts/morph_search.py#L44-L53)
elif args.search:
print(f"Searching: {args.search} in {args.path}")
result = await call_mcp_tool("morph__warpgrep_codebase_search", {
"search_string": args.search,
"repo_path": args.path
})
print(f"✓ Search complete")
Sources: scripts/morph_search.py:44-53, servers/morph/README.md
Interaction with Cross-Session Memory
Exploration agents do not work in isolation; they integrate with the claude-mem system to leverage information discovered in previous sessions. This prevents redundant exploration and ensures that architectural decisions are consistent.
This sequence shows how an agent first queries memory to gain context from past sessions before performing a new search on the current filesystem.
Sources: CLAUDE.md:148-165, CLAUDE.md:195-210
Implementation Patterns
When exploration agents are tasked with modifying code, they follow a strict protocol using the morph__edit_file tool. This tool requires the use of // ... existing code ... placeholders to minimize the amount of data sent back and forth, maintaining high speed (over 10,000 tokens/sec) and accuracy.
Editing Constraints
- Indentation: Must preserve the exact indentation of the final code.
- Context: Include just enough context to locate each edit precisely.
- Placeholders: Always use
// ... existing code ...to represent unchanged blocks. - Batching: All edits to a single file should be batched into one call.
Sources: servers/morph/README.md
Summary
Codebase Exploration Agents enable Claude to navigate large, unfamiliar projects by combining structural overviews (repomix), high-speed search (morph), and persistent memory (claude-mem). By prioritizing "Clear > Compact" and using token-efficient tools, these agents ensure that the model works with high-fidelity context while remaining within performance constraints.
Sources: CLAUDE_ONBOARDING.md:208-215, CLAUDE.md:32-45