Claude Code Subagent Model Configuration: Running Explore on Haiku 5.5

Claude Code's Explore subagent runs on the main model by default, and setting the CLAUDE_CODE_SUBAGENT_MODEL environment variable alone won't switch it to Haiku 5.5. Based on real testing, this article presents three viable configuration approaches.

Background: Why the Environment Variable Doesn't Work

Claude Code distinguishes architecturally between a "main model" and a "subagent model." The Explore subagent handles auxiliary tasks like codebase exploration and file retrieval, which in theory suits a lighter, cheaper model. In practice, however, you'll find that even after setting CLAUDE_CODE_SUBAGENT_MODEL, Explore still runs on the main model.

This suggests Claude Code doesn't route all subagent model bindings through a single environment variable. Explore may have its own model resolution logic, or its configuration may take precedence over the environment variable. Understanding this is the prerequisite for finding the right configuration.

Claude Code's Model Hierarchy and Subagent System

Claude Code is Anthropic's command-line AI programming tool, and its architecture contains two concepts: the "main model" and "subagents." The main model handles core tasks like conversation, reasoning, and code generation, while subagents are independent execution units launched by the main model for specific tasks. Claude Code ships with several built-in subagents, such as Explore (codebase exploration) and Plan (planning), each with distinct responsibilities.

The point of this design is to break down complex tasks: the main model focuses on understanding and decision-making, while subagents handle auxiliary work like retrieval and traversal. Since the complexity of different subagents varies widely, in theory each should be able to bind to a different model — for example, cheap and fast Haiku for exploration tasks, and a more capable model for core reasoning.

The problem is that Claude Code's model resolution logic isn't unified. Some subagents read the CLAUDE_CODE_SUBAGENT_MODEL environment variable, while others go through config files or dedicated resolution paths. Explore falls into the latter category, which is why setting the environment variable alone has no effect. Understanding this hierarchy is the starting point for diagnosing any "model configuration not taking effect" issue.

Three Ways to Switch Explore to Haiku 5.5

Method 1: Override the Subagent Model via Config File

Bypass the environment variable and specify the model for the subagent directly in Claude Code's config file. Config files typically take precedence over environment variables, so they can override Explore's default resolution path. This approach suits scenarios where you need Haiku 5.5 stably over the long term — configure once and it stays in effect.

Method 2: Specify the Model Parameter at the Call Layer

Through Claude Code's interface or invocation parameters, explicitly pass in the model identifier when triggering the Explore subagent. This gives finer granularity, letting you switch models for specific tasks without affecting other subagents' behavior. It suits developers who need to flexibly switch models between tasks.

Method 3: Adjust the Subagent's Model Resolution Order

If the first two approaches still don't work, the problem may lie in the priority chain of model resolution. By adjusting the loading order of configuration items, or overriding Explore's dedicated model setting, you can force it to use Haiku 5.5. The original author verified this path's feasibility through multiple rounds of testing.

Each of the three methods has its use case: config files suit long-term fixes, call parameters suit fine-grained control, and resolution-order adjustments suit troubleshooting tricky situations.

On Haiku 5.5 and Claude's Model Tiers

Anthropic's Claude models are generally divided into three tiers by capability and price: Haiku (lightweight and fast), Sonnet (balanced), and Opus (flagship and powerful). The Haiku series targets low latency and low cost, suited to high-frequency tasks that don't demand deep reasoning, such as file retrieval, simple classification, and codebase traversal.

"Haiku 5.5" refers to a specific version in that series. Its capability is sufficient for the exploration work of the Explore subagent, while its unit price and response time are significantly better than Sonnet/Opus. Binding Explore to Haiku exploits the cost-performance gradient of model tiers: put the cheap model on simple tasks and reserve the expensive one for steps that truly need deep reasoning.

Additionally, "configuration priority" is a key concept. In Claude Code, model sources may exist in multiple places at once: environment variables, project config files, user global config, and explicit parameters passed at call time. Their override order determines the final effective value, and generally the more specific and closer-to-call-site a configuration is, the higher its priority. This is the fundamental reason why environment variables get overridden by config files.

Testing Verification and Actual Results

The original author ran tests (test runs) on all three methods, confirming that the Explore subagent can correctly switch to Haiku 5.5. The point of testing is to verify the configuration actually takes effect, not just to "look like" it's set.

For developers using Claude Code daily, putting Explore on Haiku 5.5 offers two direct benefits: reduced token consumption on the main model, and faster response times for exploration tasks. Explore is a high-frequency but relatively simple operation, so handling it with a lightweight model is the more economical choice.

Practical Advice for Developers

If you're using Claude Code and want to optimize costs, check in the following order: first confirm which model Explore is actually running on, then try config file overrides, and finally consider call-layer parameters or resolution-order adjustments. Don't assume setting an environment variable is enough.

The essence of these configuration issues is that the tool treats different components differently at the abstraction layer, and the documentation rarely spells out every resolution path. When you hit a "set but not effective" situation, starting from configuration priority and component-specific logic is usually more effective than repeatedly trying environment variables.

A General Approach to Systematically Diagnosing "Configuration Not Taking Effect" Issues

These issues are fundamentally "configuration priority chain" problems, and not limited to Claude Code. In any tool with multi-level configuration (like Git, npm, or various CLIs), there are multiple override relationships at the system, user, project, and call levels. When diagnosing, follow a bottom-up principle: first confirm the value actually in effect at runtime, then trace back layer by layer to find which configuration item is overriding it.

Specifically for Claude Code, you can confirm the actual model by observing the model identifier in use during a session, checking configuration loading logs, or using debug commands. Don't conclude it's effective just because "I set it" — the root cause of many problems is that a configuration gets overridden by a higher-priority source, or the wrong key name was specified.

Another general lesson: documentation usually only describes the "common paths," and a tool's differentiated logic (such as a particular subagent having its own resolution code) often isn't documented. When facing tricky configuration problems, tackling them from the two angles of "component-specific logic" and "priority order" is more efficient than repeatedly trial-and-erroring with environment variables.

One-line Summary

Claude Code's Explore subagent runs on the main model by default, and setting environment variables alone won't switch it to Haiku 5.5 — you need one of three methods: config files, call parameters, or resolution order.

Paragraph Summary

This article addresses the issue reported by Claude Code users where the Explore subagent still runs on the main model after setting CLAUDE_CODE_SUBAGENT_MODEL, explaining the root cause: Claude Code doesn't route all subagent model bindings through a single environment variable — Explore has its own model resolution logic, and config files take precedence over environment variables. The article offers three viable solutions: first, directly overriding the subagent model via config file, suited to long-term fixed use; second, explicitly passing model parameters at the call layer, suited to fine-grained control; third, adjusting the model resolution order or overriding the dedicated setting, used to solve tricky cases. The author verified through actual test runs that all three methods can correctly switch Explore to Haiku 5.5, and notes that this reduces main-model token consumption and speeds up exploration tasks. Finally, it suggests developers diagnose in the order of "confirm current state → config file override → call layer/resolution order," rather than assuming that setting the environment variable is enough.