How-to

Use a smart model to drive cheap ones: sub-agents in Claude Code

Updated Jul 10, 2026 4 min

The trick that changed how I run Claude Code is not using a bigger model. It is using several models together: a capable one to plan and coordinate, and cheap, fast ones to do the bulk reading and searching. Claude Code calls the cheap workers sub-agents, and once you set them up well they save you both money and context. Here is how they work and how I wire them.

What a sub-agent actually is

A sub-agent is a separate Claude Code worker that your main session can hand a task to. The important part is that it runs in its own fresh context window. It does not inherit the main conversation's history; it gets your delegated task, loads your CLAUDE.md and tools, does the work, and returns a short summary. Whatever it read or searched along the way stays in its window, not yours.

That isolation is the whole point. The bulky, verbose part of a job, reading ten files, grepping a large codebase, sifting through logs, happens somewhere that never lands in your main session.

Why it saves money and context

Two things are working in your favor at once.

  1. Cheap tokens do the heavy lifting. A Haiku or Sonnet sub-agent reads the files at a fraction of Opus or Fable rates. Since exploration is where most of the tokens go, running it on a cheap model is where most of the savings come from.
  2. Your orchestrator stays lean. Only the summary comes back, so your capable planning model is never carrying the raw file contents or search dumps. That keeps its window small, its answers sharp, and its per-turn cost down. It is context management enforced by structure instead of discipline.

The math, roughly: if reading and searching is 80% of a task's tokens, moving that 80% from a five-times-pricier model down to the cheapest one is a large cut on the biggest chunk of the work, while the small, expensive planning-and-synthesis part stays where it belongs.

Setting one up

Sub-agents live in Markdown files under .claude/agents/ in your project (or ~/.claude/agents/ to make one available everywhere). Each file has a frontmatter header and a system prompt body:

---
name: codebase-scout
description: Reads and searches the codebase to answer "where is X" and "how does Y work" questions. Delegate exploration here.
model: haiku
tools: Read, Grep, Glob, Bash
---

You are a fast codebase scout. Given a question, find the relevant files and
return a tight summary: the file paths, the key functions, and a two-line
explanation. Do not edit anything. Quote only the lines that matter.

The fields that matter:

  • name and description: the description is how Claude Code decides when to reach for this agent, so write it as the job to delegate ("reads and searches the codebase"), not a vague label.
  • model: this is the lever. Set it to haiku or sonnet for a cheap worker. If you leave it out it defaults to inherit, meaning the sub-agent runs on whatever the main session is using, which defeats the cost savings. Set it deliberately.
  • tools: scope it down. A read-only scout does not need write access, and a tighter tool set keeps it focused.

Once the file exists, Claude Code will delegate to it on its own when a task matches the description, or you can tell it to ("use the codebase-scout to find where auth is handled").

When it is worth it, and when it is not

Delegation is not free. Spawning a sub-agent adds a little latency, and the win depends on how much exploration you are actually offloading.

  • Worth it: verbose, self-contained jobs. Searching a large codebase, reading many files, digesting long logs, running a batch of independent checks. The more reading it absorbs, the bigger the saving.
  • Not worth it: a one-line lookup or a quick edit you could do directly. Wrapping a trivial task in a sub-agent just adds overhead for no gain.

A good rule: if the task would dump a lot of text into your main window and you only need the conclusion, delegate it. If you need the model to keep the details in mind for the next step, keep it in the main session.

Turning it up to a fleet

Sub-agents are one capable model steering cheaper ones inside a single session. If you find yourself wanting that pattern turned all the way up, a whole fleet of agents you command from your phone, with memory, schedules, and your approval on anything risky, that is the exact idea I built MyAgens around. Same principle, more machinery: your own agents, on your own hardware, run from Telegram.

Where to go next

More in How-to

Serve a folder over HTTP in one line
Quick one-liners to serve the current directory over HTTP, no setup, when you just need to preview something.
Use Claude Code remotely from your phone or the web
Step away from your desk without stopping a Claude Code run. Turn on remote control and pick the session up from your phone, claude.ai/code, or another machine.
Stop running one giant chat: manage context in Claude Code
A long-running Claude Code session gets slower, pricier, and less accurate. Here is how I keep context lean, and the truth about what a big context window actually costs.
/clear, /compact, or a new session: when to reset Claude Code
Claude Code gives you two ways to trim a session and a third option to start over. Here is what /clear and /compact each do, and a simple rule for choosing.