Explore Subagent — Read-Only Investigation

Capsule description

You're going to learn to use Claude Code's Explore subagent from scratch. You're not going to read theory about what it "could do" — you're going to see it in action with concrete demos you can replicate in your terminal. Explore is the first Claude Code subagent you should master because it's the safest: it can't modify anything. And that safety gives you the freedom to investigate without restrictions.

This capsule answers three fundamental questions: what Explore is (a read-only subagent for investigation), how you invoke it (specific prompts with the word "Explore"), and when you use it instead of general Claude Code (when the goal is to understand, not to change). Each answer comes with practical demonstrations you can run immediately.

The connection with the project is direct: in capsule 05 you're going to use Explore to investigate a complete codebase by answering specific questions. This capsule gives you the mastery of the tool you need for that project.

What the Explore Subagent Is

The concept in 30 seconds

Explore is a subagent that Claude Code can invoke internally to investigate codebases. The difference from general Claude Code is a single but fundamental one: Explore operates in read-only mode. It can read any file, search in any directory, navigate the entire project structure — but it can't write, execute, or modify anything.

The simple architecture

You (developer)
    |
    v
Claude Code (main agent)
    |
    +-- Explore subagent (read-only)
    |     - Reads files
    |     - Searches directories
    |     - Analyzes content
    |     - Answers questions
    |     - Does NOT write
    |     - Does NOT execute
    |     - Does NOT modify
    |
    +-- Other subagents (with specific permissions)

When you ask Claude Code to use Explore, internally it spawns an agent with permissions restricted to read-only. That agent navigates your codebase autonomously — opening files, following imports, reading functions — until it has the information it needs to answer your question.

What Explore can do

What Explore CANNOT do

These restrictions aren't bugs — they're features. Each one gives you a guarantee:

• ✅ Your files are intact after the exploration
• ✅ No process ran without your knowledge
• ✅ No dependency was installed or modified
• ✅ Your git history didn't change
• ✅ Your development environment is exactly as you left it

How to Invoke Explore

Method 1: Direct invocation in the Claude Code CLI

The simplest way to use Explore is to ask Claude Code to use it:

claude

> Use Explore to investigate how this project handles authentication.

Expected output:

I'm going to use the Explore subagent to investigate this project's 
authentication system.

[Explore subagent activated - read-only mode]

Investigation findings:

1. **Authentication entry point:** src/api/v1/auth.py
   - POST /auth/login -> login() receives email and password
   - POST /auth/register -> register() creates a new user
   - POST /auth/refresh -> refresh_token() renews the JWT

2. **Authentication flow:**
   login() -> AuthService.authenticate()
           -> UserRepository.get_by_email()
           -> PasswordHasher.verify()
           -> TokenService.create_access_token()
           -> return {access_token, refresh_token}

3. **Authentication middleware:**
   src/core/security.py -> get_current_user()
   - Extracts the JWT from the Authorization header
   - Decodes with jose.jwt.decode()
   - Looks up the user in the DB
   - Injects the user into the endpoint via Depends()

4. **Dependencies:**
   - python-jose (JWT encoding/decoding)
   - passlib (password hashing with bcrypt)
   - Secret key in src/core/config.py -> Settings.SECRET_KEY

No file was modified during this investigation.

Method 2: Contextualized prompt

You can give Explore more context to guide its investigation:

> Use Explore to answer this specific question: 
  When a user does POST /api/v1/orders, what happens step by step 
  from when the request arrives to when it's saved in the database?

Expected output:

[Explore subagent - investigating the POST /api/v1/orders flow]

Complete step-by-step flow:

1. The request arrives at src/api/v1/orders.py -> create_order()
   - Depends(get_current_user) verifies the JWT
   - Depends(get_db) injects the DB session
   - The body is validated against the OrderCreate schema (src/schemas/order.py)

2. create_order() calls OrderService.create()
   (src/services/order_service.py line 45)
   - Verifies that the user exists
   - Verifies that the products exist and have stock
   - Computes the total with discounts

3. OrderService.create() calls OrderRepository.create()
   (src/repositories/order_repository.py line 23)
   - Creates an Order model instance (src/models/order.py)
   - Creates OrderItem instances for each product
   - session.add(order) + session.commit()

4. Post-creation hooks:
   - OrderService sends an event to NotificationService
   - NotificationService sends a confirmation email (async)
   - StockService.decrease_stock() updates inventory

5. Response:
   - OrderRepository returns the Order model
   - OrderService converts it to the OrderResponse schema
   - create_order() returns HTTP 201 with the order details

Method 3: Iterative exploration

You can ask Explore multiple questions in sequence, where each answer informs the next:

# Question 1: General overview
> Use Explore to give me an overview of the main modules 
  in this project and what each one does.

# [Explore responds with a list of modules]

# Question 2: Deep dive into a specific module
> Now use Explore to dig into the payments module: 
  what services it uses, what external dependencies it has, and what 
  error patterns it handles.

# [Explore responds with details of the payments module]

# Question 3: Follow a dependency
> Explore found that payments depends on StripeClient. 
  Use Explore to investigate StripeClient: where it's defined, 
  what methods it has, and how it handles Stripe errors.

# [Explore responds with details of StripeClient]

Each question narrows the focus. You start broad (all the modules), then dig deeper (the payments module), then follow a dependency (StripeClient). This is the most productive way to use Explore.

Practical Demo: Explore in Action

Demo 1: First exploration of an unfamiliar project

We're going to use a real Python project to demonstrate Explore. First, the setup:

# Clone a sample project
git clone --depth 1 https://github.com/encode/httpx /tmp/httpx-demo
cd /tmp/httpx-demo

# Start Claude Code
claude

Now the exploration:

> Use Explore to give me a complete overview of this project: 
  structure, entry points, and what each main module does.

Expected output:

[Explore subagent - investigating httpx]

httpx is an HTTP client for Python that supports sync and async.

Main structure:
httpx/
+-- _api.py           -> High-level functions (get, post, put, delete)
+-- _client.py        -> Client and AsyncClient (the main classes)
+-- _config.py        -> Configuration (timeouts, limits, SSL)
+-- _content.py       -> Request body encoding
+-- _decoders.py      -> Response decoders (gzip, deflate, brotli)
+-- _exceptions.py    -> Exception hierarchy
+-- _models.py        -> Request, Response, URL, Headers, Cookies
+-- _transports/      -> Real HTTP transport
|   +-- default.py    -> httpcore transport (sync + async)
|   +-- mock.py       -> Mock transport for testing
+-- _urls.py          -> URL parsing and manipulation

Entry point for users:
- httpx.get(), httpx.post() -> functions in _api.py
- httpx.Client() -> class in _client.py (sync)
- httpx.AsyncClient() -> class in _client.py (async)

Main pattern:
API functions -> Client -> Transport -> httpcore -> socket

Lines of code: ~8,500 (excluding tests)

Demo 2: Investigate a specific flow

> Use Explore to trace exactly what happens when I do 
  httpx.get("https://example.com"). From the call until 
  I receive the response.

Expected output:

[Explore subagent - tracing httpx.get()]

Complete flow of httpx.get("https://example.com"):

1. httpx.get() in _api.py line 106
   -> Creates a temporary Client()
   -> Calls client.get(url)

2. Client.get() in _client.py line 780
   -> Calls self.request("GET", url)

3. Client.request() in _client.py line 815
   -> Builds a Request object (_models.py)
   -> Applies middleware (auth, redirects, cookies)
   -> Calls self._send()

4. Client._send() in _client.py line 901
   -> Passes the Request to the transport layer
   -> transport.handle_request(request)

5. HTTPTransport.handle_request() in _transports/default.py
   -> Delegates to httpcore.ConnectionPool
   -> httpcore handles socket, TLS, HTTP/1.1 or HTTP/2

6. The Response comes back:
   -> httpcore returns (status, headers, stream)
   -> _client.py builds the Response object
   -> Applies decoders (gzip, etc.)
   -> Returns the Response to the user

Layers: API -> Client -> Transport -> httpcore -> Network

Demo 3: Semantic search in action

> Use Explore to find where httpx handles network errors. 
  Don't search for the word "error" — find where connectivity, 
  timeout, and DNS problems are detected and handled.

Expected output:

[Explore subagent - semantic search: network error handling]

Network error handling in httpx:

1. **Exception hierarchy** (_exceptions.py):
   HTTPError (base)
   +-- RequestError (problems while sending)
   |   +-- TransportError
   |   |   +-- ConnectError      -> connection failure
   |   |   +-- ConnectTimeout    -> timeout while connecting
   |   |   +-- ReadTimeout       -> timeout while reading
   |   |   +-- WriteTimeout      -> timeout while writing
   |   |   +-- PoolTimeout       -> timeout waiting for a pool connection
   |   +-- DecodingError         -> failure decoding the response
   |   +-- TooManyRedirects      -> exceeded max redirects
   +-- HTTPStatusError           -> status code >= 400 (with raise_for_status)

2. **Where they're detected:**
   - ConnectError: _transports/default.py when httpcore fails to connect
   - Timeouts: _config.py defines the Timeout class, _transports/ applies them
   - DNS: propagated from httpcore as ConnectError

3. **Handling pattern:**
   - httpcore raises httpcore.ConnectError
   - _transports/default.py catches it and re-raises it as httpx.ConnectError
   - The mapping is in _transports/default.py lines 60-85
   - map_httpcore_exceptions() converts httpcore exceptions -> httpx

Note: the search found these files without searching for "error" 
literally — it analyzed the meaning of the code to find 
where connectivity and timeouts are handled.

This example demonstrates the power of semantic search. A grep -r "error" would have returned hundreds of lines. Explore found exactly the relevant points because it understands that "handling network errors" includes connectivity exceptions, timeouts, and DNS.

Explore vs General Claude Code

Direct comparison

The following table summarizes when to use each tool:

The optimal workflow

The professional workflow this module establishes is:

PHASE 1: INVESTIGATION (Explore)
+----------------------------------------------+
| "Use Explore to understand how the           |
|  payment system works"                       |
|                                              |
| Explore reads -> analyzes -> answers         |
| Risk: ZERO                                   |
+----------------------------------------------+
          |
          | (now you understand the system)
          v
PHASE 2: PLANNING (your brain)
+----------------------------------------------+
| Based on what Explore found:                 |
| - I need to change PaymentService.process()  |
| - I must update the OrderCreate schema       |
| - Existing tests cover the happy path        |
| - I need to add a test for an edge case      |
+----------------------------------------------+
          |
          | (now you have a plan)
          v
PHASE 3: IMPLEMENTATION (general Claude Code)
+----------------------------------------------+
| "Modify PaymentService.process() to          |
|  add support for volume discounts"           |
|                                              |
| Claude Code reads + writes + runs tests      |
| Risk: controlled (review before commit)      |
+----------------------------------------------+

Example: the same task with both tools

Task: Understand and modify the input validation system.

Without Explore (general Claude Code only):

> Explain how input validation works and then 
  add email validation.

# Claude Code does both things at once:
# 1. Reads files to understand
# 2. Modifies files to add validation
# 
# Problem: the understanding was superficial because the focus
# was split between understanding and modifying.
# Result: the change works but it didn't consider that there's
# a global validation middleware in deps.py that should also
# be updated.

With Explore + general Claude Code (separated):

# Step 1: Investigate with Explore
> Use Explore to find ALL the points where inputs are validated 
  in this project. Include middleware, schemas, custom validation 
  functions, and any other mechanism.

# Explore investigates and reports:
# - Pydantic schemas in src/schemas/ (structure validation)
# - Global middleware in src/api/deps.py (auth validation)
# - Custom functions in src/utils/validators.py (business validation)
# - Decorators in src/core/validation.py (rate limiting + sanitization)

# Step 2: Plan with complete understanding
# Now you know there are 4 validation layers.
# To add email validation, you need:
# 1. Schema in src/schemas/user.py (Pydantic validator)
# 2. Possibly a function in src/utils/validators.py

# Step 3: Modify with general Claude Code
> Add email validation to the UserCreate schema in 
  src/schemas/user.py using a Pydantic validator. 
  Also add a validate_email_format function in 
  src/utils/validators.py that the schema can reuse.

# Claude Code modifies with complete understanding of the context.
# Result: a change that integrates correctly with the 4
# existing validation layers.

The difference: with Explore first, you discovered the 4 validation layers. Without Explore, you would have modified 1 layer and left the other 3 inconsistent.

Read-Only as a Feature: Use Cases

Case 1: Investigate a production codebase

# Scenario: your team has a bug in production.
# It's not your service. You need to understand how it works 
# quickly to diagnose it.

> Use Explore to investigate the notifications service. 
  I need to understand: how emails are sent, what happens if the 
  email service fails, and where the result is logged.

# With Explore: complete investigation without risk.
# Without Explore: the anxiety of "what if I modify something in production"
# would make you go slower and be more conservative in your investigation.

Case 2: Technical evaluation of a project

# Scenario: your company is evaluating acquiring another 
# product and you need to evaluate the code quality.

> Use Explore to do a quality evaluation of this codebase:
  1. What patterns are used and are they consistent?
  2. Are there tests? What approximate coverage?
  3. Where is the most critical tech debt?
  4. What external dependencies does it have and are they current?

# Explore investigates without touching anything.
# You produce a technical report based on facts from the code.

Case 3: Deep code review

# Scenario: a PR touches a module you don't know well.
# You need to understand the context before doing the review.

> Use Explore to explain the inventory module to me. 
  A PR is changing StockService.reserve_stock() and I need to 
  understand: what that function does, what calls it, and what happens 
  if the reservation fails.

# Explore gives you the complete context.
# Your code review is informed, not superficial.

Case 4: Emergency onboarding

# Scenario: 3am, a PagerDuty alert, another team's 
# service is failing. Nobody from the responsible team 
# is available.

> Use Explore to give me a quick overview of the checkout service:
  - Where's the main entry point?
  - What external dependencies does it have?
  - Where are errors logged?
  - What circuit breakers or retry logic does it have?

# In 5 minutes you have enough context to diagnose.
# With Explore: fast and safe.
# Without Explore: 30 minutes reading random files while 
# the service is down.

Comparison: Explore vs General Claude Code

When to use Explore? When your goal is to understand, investigate, analyze, diagnose, evaluate.

When to use general Claude Code? When your goal is to write, modify, refactor, create, execute.

Trade-off: Explore can't make changes. If you discover something you want to fix while investigating, you need to switch to general Claude Code. The benefit makes up for it: your investigation is deeper because it isn't interrupted by modifications.

Connection with the Project

In the Module Project (capsule 05) you're going to use Explore exclusively to investigate a codebase. Everything you learned in this capsule is the base:

• You'll use the direct invocation for your first exploration questions
• You'll use contextualized prompts to dig into specific areas
• You'll use iterative exploration to connect findings between modules
• The read-only guarantee will give you confidence to investigate aggressively

Everything you learn today applies directly to capsule 05.

Troubleshooting

Problem 1: Explore doesn't find relevant files

Cause: Your prompt is too generic or the project has an unconventional structure.

Solution:

# Instead of:
> Use Explore to understand this project.

# Be specific:
> Use Explore to find this application's entry point. 
  Look for files like main.py, app.py, __main__.py, or any 
  file that starts the application.

Problem 2: Explore answers superficially

Cause: Your question doesn't have enough direction.

Solution:

# Instead of:
> Use Explore to look at the users module.

# Ask for specific depth:
> Use Explore to analyze the users module in detail:
  1. What functions does it have and what does each one do?
  2. What external dependencies does it use?
  3. How does it connect with other modules in the project?
  4. What validations does it do?

Problem 3: The answer mixes several topics without depth

Cause: You asked for too many things in a single prompt.

Solution:

# Instead of:
> Use Explore to explain everything about authentication, 
  payments, notifications, and reports.

# One question at a time:
> Use Explore to explain how authentication works.
# [Wait for the answer]
> Now use Explore to explain the payments module.

Problem 4: Explore says it can't find something you know exists

Cause: The file or function name doesn't match your description.

Solution:

# If you know the exact name:
> Use Explore to read the file src/utils/helpers.py and 
  explain what each function does.

# If you don't know the name:
> Use Explore to look for functions that handle rate limiting 
  in this project. It may be in utils, middleware, decorators, 
  or any other place.

Problem 5: Claude Code doesn't invoke Explore and answers directly

Cause: Your prompt wasn't clear enough about using Explore.

Solution:

# Be explicit:
> Use the Explore subagent (read-only mode) to investigate 
  how this project handles caching.

# Or start with the keyword:
> Explore: how does this project handle caching?

Exercises

Exercise 1: First Explore invocation (Easy)

Clone a Python project you don't know (suggested: httpx, typer, or rich). Use Explore to get an overview of the project's structure. Your answer should include: main folders, what each one does, and the general architecture pattern.

# Clone the project
git clone --depth 1 https://github.com/encode/httpx /tmp/httpx-exercise
cd /tmp/httpx-exercise

# Start Claude Code
claude

# Invoke Explore
> Use Explore to give me an overview of this project's structure: 
  main folders, what each one contains, and what architecture 
  pattern it follows.

httpx/              -> Main HTTP client code
+-- _api.py         -> Convenience functions (get, post, etc.)
+-- _client.py      -> Client and AsyncClient (main classes)
+-- _models.py      -> Request, Response, URL, Headers
+-- _transports/    -> Transport layer (real connection)
tests/              -> Tests with pytest
docs/               -> Documentation with MkDocs

Pattern: Layered architecture (API -> Client -> Transport -> Network)

Exercise 2: Investigate a specific flow (Easy)

Using the same project, ask Explore to trace a specific flow: what happens when a user makes an HTTP GET request. Document the steps Explore identifies.

> Use Explore to trace step by step what happens when a user 
  runs httpx.get("https://example.com"). From the httpx.get() 
  function to when it receives the response.

1. httpx.get() in _api.py -> creates a temporary Client -> client.get(url)
2. Client.get() in _client.py -> self.request("GET", url)
3. Client.request() -> builds Request -> applies middleware -> self._send()
4. Client._send() -> transport.handle_request(request)
5. Transport -> httpcore -> socket -> actual send
6. Response comes back: httpcore -> Transport -> Client -> user

Exercise 3: Semantic search (Medium)

Ask Explore to find where the project handles network errors. The key instruction: DON'T search for the word "error" — find where connectivity problems are detected and handled.

> Use Explore to find where this project detects and handles 
  network connectivity problems. Don't search for the word "error" — 
  find the real mechanisms: exceptions, retry logic, timeouts, 
  and any other network problem handling mechanism.

Network problem handling:

1. Exceptions: _exceptions.py defines ConnectError, TimeoutException, 
   ReadTimeout, WriteTimeout, PoolTimeout
2. Mapping: _transports/default.py has map_httpcore_exceptions() 
   which converts httpcore exceptions to httpx exceptions
3. Timeouts: _config.py defines the Timeout class with configurable 
   connect, read, write, pool timeouts
4. Retries: Client has max_redirects but no automatic retry
   (users must implement retry manually)

Exercise 4: Iterative Explore (Medium)

Ask Explore 3 questions in sequence, where each question digs deeper into the previous answer. Start with a general overview, then dig into a module, then dig into a specific function of that module.

# Question 1: Overview
> Use Explore to give me an overview of the main modules 
  in this project and their responsibility.

# [Explore responds with a list of modules]

# Question 2: Dig into _client.py
> Use Explore to analyze _client.py in detail: what classes it has, 
  which are the main methods, and how it connects with other modules.

# [Explore responds with details of _client.py]

# Question 3: Dig into Client.request()
> Use Explore to break down the Client.request() function line by line: 
  what each step does, what validations it applies, and what other methods it calls.

Client.request() in _client.py:

1. Builds a Request object with URL, method, headers, content
2. Applies auth (if auth was configured on the Client)
3. Prepares cookies from the CookieJar
4. Calls self._send_with_response()
   a. Handles redirects (if follow_redirects=True)
   b. For each redirect, checks max_redirects
   c. Builds a new Request for the redirect URL
5. Reads the response stream if necessary
6. Returns the Response object

Calls: _build_request(), _send(), _send_handling_redirects()
Uses: _merge_url(), _merge_headers(), _merge_cookies()

Exercise 5: Compare Explore vs grep (Hard)

Choose an investigation question. First try it with grep (text search). Then try it with Explore (semantic search). Document the difference in results, time, and completeness.

grep -rn "redirect" httpx/ --include="*.py"
# Result: ~40 lines that contain "redirect"
# Many are comments, strings, or variable names
# You need to read each one to determine which is relevant
# Time: ~5-10 minutes to filter and understand

> Use Explore to explain how this project handles 
  HTTP redirects: where they're detected, how they're followed, 
  what limits there are, and what happens if they're exceeded.

Redirect handling in httpx:

1. Detection: Client._send_handling_redirects() in _client.py
   - Checks status codes 301, 302, 303, 307, 308
   - Reads the "Location" header for the destination URL

2. Following: 
   - If follow_redirects=True (default: False), follows automatically
   - Builds a new Request with the redirect URL
   - For 303: changes the method to GET
   - For 307/308: keeps the original method

3. Limits:
   - max_redirects=20 (default in Client)
   - If exceeded: raises a TooManyRedirects exception

4. Configuration:
   - follow_redirects parameter in Client() and in request()
   - max_redirects parameter in Client()

Summary

In this capsule you learned:

• What Explore is: A Claude Code subagent that operates in read-only mode, designed for codebase investigation
• How to invoke it: 3 methods — direct invocation, contextualized prompts, iterative exploration
• Read-only is a feature: It gives you total confidence to investigate without the risk of accidental modifications
• What it can and can't do: It reads, searches, analyzes, answers — but it doesn't write, execute, or modify
• Explore vs general Claude Code: Explore to investigate (understand), general Claude Code to implement (modify)
• The optimal workflow: Explore first (investigate), plan (your brain), general Claude Code later (implement)
• Specific questions produce better results: "How does it handle authentication?" > "Look at this codebase"

Next capsule: Semantic Search vs Grep — Finding by Meaning — the difference between searching for text and searching for meaning, and why it changes your investigation productivity.

Additional Resources

1. Claude Code Documentation — Subagents — Official documentation about subagents and Explore.
2. Agentic Patterns — Anthropic Research — Autonomous agent patterns for code investigation.
3. Read-Only Agents for Code Analysis — Research on read-only agents and their advantage in safety.
4. The Art of Code Reading — Diomidis Spinellis — Classic code reading techniques, complementary to the AI approach.
5. Understanding Software — Max Kanat-Alexander — A framework for understanding complex software.
6. httpx Documentation — Documentation for the project used in this capsule's demos.

Module 2, Capsule 02 — Refactoring & Legacy Code with Claude Code Guide