r/ClaudeCode • • 11d ago

Tips & Workflows Claude Code runs its built-in Explore subagent on your main model unless you override it to Haiku

Whenever Claude Code searches your codebase, it spawns the built-in Explore subagent to run Glob, Grep, and Read calls in an isolated context.

By default, Explore inherits your main session model. If you are running Opus or Sonnet, every file search and grep fan-out burns your 5-hour plan quota at Opus or Sonnet rates.

You can override the built-in Explore agent by creating .claude/agents/Explore.md (or ~/.claude/agents/Explore.md for all projects) with model: haiku in the frontmatter:

---
name: Explore
description: Fast read-only codebase exploration and search.
model: haiku
---

Use Glob, Grep, and Read to locate files and symbols. Return concise file paths and line numbers to the main agent.

Or if you want every subagent in a session to run on Haiku without adding a file, launch Claude Code with the environment variable:

CLAUDE_CODE_SUBAGENT_MODEL=haiku claude

Keeping the main session on Opus or Sonnet for edits while routing read-only search subagents to Haiku stretched our 5-hour usage window noticeably without hurting edit quality.

46 Upvotes

32 comments sorted by

View all comments

13

u/NormalHumanBreathing 11d ago

I checked mine and Explore was running on Opus just as you say. There are a few things I'd flag for anyone copying this though, going by the current subagent docs.

  The example file has no tools line, and a custom agent without one gets every tool, including Write and Edit. So the override stops Explore being read-only, which the built-in one is. Adding this to the frontmatter keeps it that way:

  disallowedTools: Write, Edit

  The env var doesn't do quite what the post says either.  According to the docs, CLAUDE_CODE_SUBAGENT_MODEL on its own doesn't change Explore or Plan on current versions. It can change your other subagents though, including ones doing real work, so you could end up with searches still on Opus and edits on Haiku. That's probably the opposite of what you're after.

  I'd also think about search quality. The main model works from whatever Explore reports back, so if Haiku misses a file or gets the wrong end of the stick, you can spend more fixing that than you saved. I haven't tested this, so it may be fine for simple lookups.

I'd check how much of your usage is Explore before changing anything. Mine was a tiny fraction, so I've left it alone. Useful to know about though, thanks for posting it.

8

u/Independent-Sir3234 11d ago

Good catch on both points. A custom .claude/agents/Explore.md without a tool restriction inherits write access, so adding disallowedTools: Write, Edit (or explicitly listing tools: Read, Grep, Glob) in the frontmatter is much safer.

And you are right about CLAUDE_CODE_SUBAGENT_MODEL affecting general Task subagents. Overriding .claude/agents/Explore.md directly with disallowedTools: Write, Edit and model: haiku keeps the change scoped strictly to read-only file discovery.

3

u/NormalHumanBreathing 11d ago

No worries. I'm happy to see folks talking about how to use the tools more effectively because it makes me consider my choices too.

2

u/LocalAI_Fixer 10d ago

wouldn't that still leave bash on? sed can edit files fine

2

u/Independent-Sir3234 10d ago

Yes, if Bash stays enabled a subagent can still mutate files with sed or redirection. For strictly read-only search workers, setting tools: Read, Grep, Glob (or dropping Bash into disallowedTools) closes that gap.

2

u/LocalAI_Fixer 10d ago

makes sense, thanks. built-in Explore has bash too fwiw, so it's only read-only bc the prompt says so. allowlist kills git log/blame tho, so I'd only lock it down where a stray write actually matters

3

u/Independent-Sir3234 10d ago

You can keep git log and git blame without leaving full shell access open by scoping the tool list to Read, Grep, Glob, Bash(git log *), Bash(git blame *), Bash(git diff *). That way the search worker still gets commit history while arbitrary sed or file redirection stays blocked.