Lesson 6 of 7 · 15 min · Checked on 10 October 2026

Subagents, models and costs

By the end of this lesson you will be able to:

Create a read-only subagent and explain when it is worth using one
Choose the model by the task: the biggest for thinking, the smallest for volume
See how much you spent and avoid two agents writing to the same file
Experiment on a Git branch and merge it into the main one only when it is good

Tiago sells São Jorge cheese in a small online shop. The price of the aged cheese has gone up, and he asks the agent: “Look through all the files of the site for where the old price appears.”

The agent opens the 40 files, one by one. The answer is good, but the conversation is now full of pages Tiago will never look at again. As you saw in lesson 2/05, a full window makes the agent work worse for the rest of the afternoon.

The concept: a helper with its own sheet

A subagent is a second agent that the main one launches for a separate task. It has its own context window. It reads what it has to read and returns only the summary: “the old price appears in 3 files, on these lines”. Your conversation receives ten lines, not 40 files.

It is worth it when the task produces a lot of text that you will not reuse: searching, reading many files, reviewing, analysing error logs.

It is not free. Each subagent does its own work with the model, and that costs. The Codex documentation says these workflows use more tokens than a single agent.

How it is done today: a read-only reviewer

This is how it looks on 6 October 2026; your screen may differ. Look for the button with the same name.

Claude Code. Create the file .claude/agents/revisor.md before you open the agent (revisor means “reviewer”):

---
name: revisor
description: Reviews code and texts and points out problems, without changing anything.
tools: Read, Glob, Grep
---
You are a reviewer. Read the files you are given and return at most 10 lines with the problems found, each with the file name. Do not change anything.

The tools line gives it read tools only. Claude chooses on its own when to use a subagent, based on the description. To call it yourself, type @ and pick it from the list, or ask: “Use the revisor subagent to…”

Codex. Create .codex/agents/revisor.toml:

name = "revisor"
description = "Reviews code and texts and points out problems, without changing anything."
sandbox_mode = "read-only"
developer_instructions = """
You are a reviewer. Read the files you are given and return at most 10 lines with the problems found, each with the file name. Do not change anything.
"""

sandbox_mode = "read-only" stops it from writing. Codex only launches subagents when you ask, and /agent shows the ones that are running. As with hooks (lesson 2/03), it only reads the .codex/ folder of projects you trust.

Models: the biggest for thinking, the smallest for volume

Both tools let you choose the model and, in many cases, the reasoning effort. The rule is simple:

For thinking (planning, deciding, finding a hard bug): the bigger model, with more effort.
For volume (searching, renaming, summarising, repeated and clear tasks): a smaller model, with less effort. It is faster and spends less.

The Codex guide sums it up like this: stay with the lightest option that still gives you the quality you need. The Claude Code one suggests a small model for subagents with simple tasks.

In both, /model changes the session's model. In Claude Code, /effort changes the effort. In Codex, /model itself asks for the effort, when the model allows it. In a subagent, add the model line to the file; without it, it usually uses the session's model. Model names change several times a year: see the Current state page.

Tip

Start with less effort. If the answer is not enough, go up. Many everyday tasks go well without the maximum.

Seeing how much you spent

Claude Code: /usage shows the session's use and, on subscriptions, the plan's bars. The money value is an estimate; what counts is the usage page in the console.
Codex: /usage shows the account's use by day or by week; /status shows the session's.

If you pay by use, turn on the spending cap (lesson 1/06). Prices and limits: see the Current state page.

Watch out

Several subagents reading at the same time is safe. Several writing to the same file is not: one erases the other's work, or they end up in conflict. The Codex documentation asks for the same care. Use agents in parallel to read, search and review; to write, one at a time.

Git branches: experiment without breaking things

In lesson 1/05 you learned that each commit is a snapshot. A branch is a parallel line of snapshots. The main branch stays as it was; you experiment on another.

git branch                     # shows the branches; the * marks where you are
git switch -c desconto         # creates the branch desconto and switches to it
# ... the agent works, you run the tests, you make commits ...
git switch main                # goes back to the main one
git merge desconto             # merges the branch into the main one
git branch -d desconto         # deletes the branch, already merged

(desconto means “discount”.) If the experiment goes wrong, go back to the main branch and delete the branch without merging it: git branch -D desconto. The capital D forces the deletion, and this is not an undo: the commits on that branch are no longer at hand. First confirm with git status that there are no unsaved changes and, if anything is worth keeping, commit it or copy it out.

If your main branch is called master, write master where it says main. git branch tells you the name.

Tip

Ask the agent to work on a branch: “Create the branch desconto and work only on it. Do not merge.” You do the merge, after reading the diff and running the tests.

Exercise

In the folder experiencias/encomendas (“experiments/orders”), check with git status that there is nothing unsaved. Run git switch -c revisao (revisao means “review”).
Create the reviewer's file (Claude Code or Codex, as above).
Open the agent and ask: “Use the revisor subagent to review encomendas.py and test_encomendas.py. Show me what it returned and do not change anything.”
Run /usage and note the use.
Commit the reviewer's file. Run git switch main and then git merge revisao.

How I know it worked the reviewer returns a short list and your conversation shows only that summary. After git switch main, the reviewer's file disappears from the folder; after git merge revisao, it comes back.

If it didn't work

Claude Code cannot find the reviewer: the .claude/agents/ folder was created with the session open. Close and open the agent.
Codex cannot find the reviewer: the project is not marked as trusted, or the file has a TOML error. Close, fix and open again.
“pathspec 'main' did not match”: your main branch is called master. Check with git branch.
git switch refuses to change branch: there are unsaved changes. Commit first.

Sources:

Videos

**Como Usar Subagents no Claude Code**
Augusto Galego · 13 min · PT-BR · subtitles · Watch on YouTube
A tutorial in Portuguese on how to use subagents in Claude Code.

**Claude Code: The Advanced Guide (99% of Devs Skip These Features)**
Tech With Tim · 19 min · EN · subtitles · Watch on YouTube
In the specified section: custom subagents in Claude Code. The rest of the video covers other advanced features.

Test what you learned

1. You want to know in which files of the site the old price of the aged cheese appears. There are 40 files. What is the best request? “Use the revisor subagent to look for the old price in the 40 files and return only the list of files and lines.” “Launch 40 subagents, one per file, and each one fixes the price.” “Open the 40 files here and show me everything.”

2. You are going to rename a variable in 30 files, always the same way. Which model do you choose? It does not matter, they cost the same The biggest there is, so it does not fail A smaller, faster model, and you confirm with the tests

3. You want to try a new discount on the orders, but you are not sure you will keep it. What do you do first? Create a branch with git switch -c desconto and work there Copy the whole folder to another folder Change things directly on the main branch and see how it goes

Corrections to this lesson (1)

10 October 2026: Second external review: `git branch -D` is not an undo; before deleting the branch, check `git status` and keep whatever is worth keeping.