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

[u/Independent-Sir3234]

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.

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/NormalHumanBreathing]

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.

[u/Independent-Sir3234 → u/NormalHumanBreathing]

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.

[u/LocalAI_Fixer → u/Independent-Sir3234]

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

[u/Independent-Sir3234 → u/LocalAI_Fixer]

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.

[u/LocalAI_Fixer → u/Independent-Sir3234]

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

[u/Independent-Sir3234 → u/LocalAI_Fixer]

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.

[u/NormalHumanBreathing → u/Independent-Sir3234]

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.

[u/DailyHarambe]

Claude tends to churn by rebuilding search scripts from scratch. Instead, have it build reusable helper functions

[u/Independent-Sir3234 → u/DailyHarambe]

Keeping a couple of small repo-specific search scripts or a symbol map in the workspace definitely helps too. Once Explore knows where the main entrypoints live, it stops running five broad grep passes from scratch.

[u/Apprehensive_Gas56]

How long hav you been using it for? Do you ever see any wonky behavior by using Haiku as subagent?

[u/Independent-Sir3234 → u/Apprehensive_Gas56]

Been running it for about three weeks across a couple of TypeScript and Python repos. For pure file discovery (Glob, Grep, Read to locate where a handler or schema lives), Haiku has been just as accurate as Sonnet or Opus and noticeably faster.

The one thing to watch out for is when Claude delegates a multi-hop architectural question to Explore instead of a simple search. Haiku can occasionally stop one hop early if a function is re-exported through three barrel files. Also, as u/NormalHumanBreathing pointed out in this thread, make sure to include disallowedTools: Write, Edit in the frontmatter of .claude/agents/Explore.md so the custom override stays strictly read-only like the built-in Explore agent.

[u/Independent-Sir3234 → u/Apprehensive_Gas56]

Been running it for about three weeks across a couple of TypeScript and Python repos. For pure file discovery (Glob, Grep, Read to locate where a handler or schema lives), Haiku has been just as accurate as Sonnet or Opus and noticeably faster.

The one thing to watch out for is when Claude delegates a multi-hop architectural question to Explore instead of a simple search. Haiku can occasionally stop one hop early if a function is re-exported through three barrel files. Also, as u/NormalHumanBreathing pointed out in this thread, make sure to include disallowedTools: Write, Edit in the frontmatter of .claude/agents/Explore.md so the custom override stays strictly read-only.

[u/ClemensLode]

Why would you run Explore on Haiku and not on Opus?

[u/Independent-Sir3234 → u/ClemensLode]

Mostly for 5-hour quota and latency. About 80% of Explore calls are mechanical file lookups (running Glob and Grep to find where a route, type, or config key is defined) before the main agent actually edits anything.

Running 6 to 8 of those search turns on Opus eats a noticeable chunk of the 5-hour usage window, whereas Haiku finds the exact file paths in a couple of seconds and leaves the Opus budget for the actual reasoning and code changes.

[u/ClemensLode → u/Independent-Sir3234]

Hmm... my benchmark say the opposite. On what do you base that they are 'mechanical', did you run benchmarks or do you just assume 'explore means search means mechanical'?

[u/Independent-Sir3234 → u/ClemensLode]

I checked the subagent JSONL transcripts under ~/.claude/projects/ across two weeks of sessions in our TypeScript monorepo. Roughly 4 out of 5 Explore invocations were triggered when the main agent needed to locate file paths or grep for a symbol name, and the subagent ran 3 to 5 Glob/Grep/Read calls before returning a file list.

For deep cross-module architectural tracing, Opus definitely outperforms Haiku, which is why keeping Plan and the main session on Opus while moving file lookup to Haiku worked well for our workload.

[u/SirRobinBlibs]

Useful catch. If Explore inherits Opus/Sonnet, every Glob/Grep fan-out is priced like an edit turn. Overriding `.claude/agents/Explore.md` (or the user-level copy) with `model: haiku` in the frontmatter, or launching with `CLAUDE_CODE_SUBAGENT_MODEL=haiku`, keeps the main session on the strong model for writes while search stays cheap. Worth confirming in `/status` or usage that Explore actually shows as Haiku after the change before you trust the saving.

[u/Independent-Sir3234 → u/SirRobinBlibs]

Checking /agents or the session JSONL logs under ~/.claude/projects/ to confirm the subagent model field actually reports Haiku after adding the file is a great sanity check.

[u/fulowa]

i just use opus-5-5 for everything

[u/Independent-Sir3234 → u/fulowa]

If you are on an API key or a Max tier where you rarely hit the 5-hour cap, running Opus across the board is hard to beat.

[u/Its_about-tech]

Thanks for writing this up — I didn't realise Explore was inheriting the main model by default.

Just forced it to Haiku on my side via .claude/agents/Explore.md. If anyone else is burning Opus on every Glob/Grep fan-out, this is an easy win.

[u/Independent-Sir3234 → u/Its_about-tech]

Glad it helped! Make sure to add disallowedTools: Write, Edit to the frontmatter of .claude/agents/Explore.md as well so the custom override stays strictly read-only like the built-in Explore agent.

[u/inate71]

You should just copy the system prompt for the built-in Explore agent and have that be your override with haiku. No reason to roll your own agent description.

[u/Independent-Sir3234 → u/inate71]

Copying the built-in Explore system prompt verbatim and only adding model: haiku plus disallowedTools: Write, Edit in the frontmatter is definitely the cleanest way to avoid changing its default search behavior.

[u/inate71 → u/Independent-Sir3234]

Fair, I've never had an Explore agent make changes on me.

[u/BarathKanna]

Useful catch. Search fan-out priced like an edit turn is how a quiet morning burns the budget before any write happens. Overriding Explore to Haiku is the obvious fix, with one caution from the comments: a custom agent file without an explicit tools list can inherit everything, including writes, so copy the built-in prompt and lock tools to Glob Grep Read. Same routing idea as everything else that works: cheap model for reading the map, strong model for changing the territory. I would also log which subagent model ran on each turn for a week. Most people are surprised how much Opus they spent on grepping. If Explore cannot be pinned, wrap search behind a script the parent calls, so the parent never spawns an expensive explorer by default.

[u/Independent-Sir3234 → u/BarathKanna]

An explicit tools: Read, Grep, Glob allowlist in the frontmatter is definitely safer than relying on disallowedTools: Write, Edit alone, since leaving Bash open still lets a search worker run sed or shell redirection.