Codebase Explorer
Investigates an existing codebase topic by topic, grounds every finding in actual source code, and persists results for long-term reference.
Output Mode
Users can change this at any time — e.g. "use Notion", "save to files". When the mode is set, read the corresponding reference file before any documentation step:
- → read
references/output-obsidian.md
- → read
references/output-notion.md
- → read
references/output-files.md
Session Setup
Before starting, establish with the user:
- The reference repo — codebase to study and its local path
- The goal — what they're building and what they need to learn
- Output destination — confirm or change the active output mode, then read its reference file
Immediately create the investigation index using
assets/templates/index.md
. This becomes the navigation hub for the entire session.
Core Constraints
Non-negotiable throughout the session:
- Source code is ground truth — read the actual files, never hallucinate APIs or behavior
- Cite file:line — every claim ties back to a specific location:
src/agents/tools/web-search.ts:215
- One topic at a time — complete, document, then move to the next
- Concise — direct answers with code references, no padding or hedging
Investigation Loop
For each topic the user asks about:
1. Find relevant code
Use targeted searches before reading anything:
Glob: **/web-search*.ts → find files by name pattern
Grep: "resolveSearchProvider" → find specific function definitions
Read: specific file once located
Prefer Glob + Grep over broad reads. Only read files after confirming they're relevant.
2. Read and understand
Read source files directly. For long files (>300 lines), read in sections using offset + limit.
Focus on:
- Entry point functions and their signatures
- Data flow (what goes in, what comes out)
- Key types and interfaces
- Configuration structures
3. Answer concisely
Structure every answer as:
- What it does (1-2 sentences)
- How it works (key implementation with file:line references)
- Key files (list with one-line descriptions)
- Notable design decisions or trade-offs
4. Persist findings
After answering, create a note using
assets/templates/topic-note.md
and write it using the active output mode (see
references/output-{mode}.md
for exact operations).
Then update the investigation index: add a
entry with a 2-3 sentence summary and a link to the new note.
5. Cross-link
Link related notes to each other and back to the index. The index is the hub. See the active output mode reference for the correct linking syntax.
Investigation Areas (AI Agent Codebases)
When the user hasn't specified a topic, suggest from this list in rough dependency order:
- Agentic loop — how the agent processes a message, calls tools, retries
- Tool system — how tools are defined, registered, and executed
- Streaming / feedback — how intermediate results reach the user in real-time
- Short-term memory — session context, compaction, context window management
- Long-term memory — RAG, vector search, embedding providers
- Sub-agents / parallelism — spawning, communication, lifecycle management
- Error handling — retry logic, fallbacks, recovery strategies
- Configuration — how the system is configured and extended
For other codebase types, adapt the topic list to the domain.
Session Continuity
When resuming an investigation in a new session:
- Read the active output mode reference:
references/output-{mode}.md
- Load the existing investigation index to recall what was covered
- Confirm with the user what to investigate next
- Continue the loop — don't re-document already-covered topics
Templates
- — investigation index / README template
- — per-topic deep-dive note template