Token efficiency
Everything GAIA adds to a session takes up part of Claude’s context window, the fixed amount of text Claude can hold at once. GAIA keeps that part small on purpose. Its rules, skills, and instruction files are cut down to what improves how Claude works. Each instruction lives in one place instead of being repeated across files, and is checked against the code it describes to keep it accurate. Most of it loads only when a task needs it, which leaves more of the window for your work.
The usage figures on this page were measured in a new GAIA 2.0.0 project on Opus 5.5. Percentages are of a 1M-token context window.
At session start
Section titled “At session start”GAIA adds 8,365 tokens to a session before you type anything: 0.84% of the window.
| What loads in every session | Tokens |
|---|---|
| Rules that apply everywhere (8 files) | 4,309 |
| Session-start text from GAIA’s hooks | 1,403 |
The root CLAUDE.md | 1,108 |
| Skill and command descriptions | 806 |
| Agent descriptions (9) | 739 |
| Total | 8,365 (0.84%) |
The session-start text was measured in a session on a feature branch. On the default branch, the instructions for working on a branch are left out, so the total is lower. The session-start text is added when a session starts, and again after /clear or compaction.
A session started from frontend/ begins at about 11.1k tokens (1.11%). Claude Code still loads everything above, and adds frontend/CLAUDE.md (about 1,040) and the descriptions of the 13 frontend skills (1,676).
Your own setup adds to this: MCP servers, plugins, and your global ~/.claude/CLAUDE.md load in every project, with or without GAIA.
A typical task
Section titled “A typical task”Most rules apply only to certain paths, and load only when Claude works on a file they cover. A task that edits one component and one route loaded 10 of the 21 path-scoped rules:
| What the task loaded | Tokens |
|---|---|
| Root rules for specific paths (3 of 8) | 3,655 |
| Frontend rules (7 of 13) | 5,282 |
| Frontend skill descriptions (13) | 2,001 |
frontend/CLAUDE.md | 917 |
| Added by the task | 11,855 (1.19%) |
With the startup load, the session held 20,220 tokens of GAIA (2.02%). If every path-scoped rule loaded, root rules would add up to 9.1k and frontend rules up to 13.4k.
Skills
Section titled “Skills”Until a skill is used, it costs only its description. When it is used, Claude reads its SKILL.md, and reads its extra files only if the task needs them.
| Skill | Description | SKILL.md | Extra files | Most when used |
|---|---|---|---|---|
new-component | 167 | 1,434 | none | 1,434 (0.14%) |
tdd | 75 | 4,282 | 416 (3 files) | 4,698 (0.47%) |
tdd-react | 173 | 303 | 7,491 (1 file) | 7,794 (0.78%) |
react-code | 207 | 5,880 | 9,061 (4 files) | 14,941 (1.49%) |
For the larger skills, a description costs 1% to 2% of the full skill. A small skill like new-component costs more by share (12%), but little in tokens.
Hooks run outside the conversation. Most add nothing unless they block something, and then they add only the message they print. Two add text when you reach a point that needs it: the instructions for working on a branch when you move onto a branch or worktree, and the checkpoint instructions when the context gets heavy (see Context bands).
Deterministic scripts
Section titled “Deterministic scripts”Much of GAIA’s checking, counting, and grading is done by deterministic scripts: they follow fixed rules, so the same input always gives the same result. A script’s work costs no Claude tokens. Only its short result reaches Claude. GAIA uses scripts wherever an answer has to come out the same every time, and leaves the parts that need judgment to Claude. For example:
- Gates are hooks that allow or block a commit or a risky command by fixed rules, so Claude cannot talk its way past one. See the gate reference.
- The audit runs React Doctor (opens in a new tab), Knip (opens in a new tab), and a dependency advisory check next to its reviewers, and a script checks every repair before it is kept. See the Code Audit Team.
/gaia-fitnessgrades your Claude setup with a fixed list of rules. Its advisory notes never change the grade.- Scaffolders create new components, hooks, routes, and services with GAIA’s bundled
gaia scaffoldcommand, from the project’s templates. - Cost lines are added up by a script from GAIA’s usage records, never estimated by Claude.
When the audit keeps finding the same kind of problem, /gaia-codify proposes a guard for it, such as a check, a skill, or a rule, and adds it once you approve.
The audit
Section titled “The audit”The audit loop runs its review rounds in sub-agents, outside your main session. Each sub-agent has its own context window, and your session gets back only a short report.
| Audit | Your session receives | Largest sub-agent context |
|---|---|---|
| Three full rounds, two fixes, and two light reviews (17 sub-agents) | about 690 to 1,240 (0.07% to 0.12%) | 181k |
Your session receives less than 1% of what the largest sub-agent holds.
Each reviewer also starts small. In a first-round audit of a frontend change on a new project, code-audit-frontend starts with about 26.7k tokens of context (2.7% of a 1M-token window), each rule specialist with about 5.9k (0.6%), and audit-loop-unit with about 22.7k (2.3%). These figures are medians of five runs on Claude Code 2.1.305, recorded in wiki/concepts/Code Review Audit Agent.md.
A light review keeps small changes cheap for the reviewers: in the same audit, a light reviewer peaked at about 12k tokens of context and used about 17k tokens of input in total.
A full re-review costs about the same as the first full review, even when the change is small. In the same audit, a 24-line fix to a 706-line feature got a second full round that used 105% of the first round’s input, and its reviewer peaked at 89k tokens against 90k in round one. Most of a full review’s cost is the reviewer’s fixed load of instructions and rules, not the size of the change.
What an audit costs in billed tokens is a separate question from how much of your context it takes. See Cost and usage ledger.
Context bands
Section titled “Context bands”Claude cannot see how full its own context is. Claude Code reports it only to the statusline, so GAIA’s statusline saves each reading, and a hook checks it after every tool call. When the context reaches one of four bands, the hook tells Claude. GAIA asks you to clear long before Claude Code’s own automatic compaction, which only starts when the context window is nearly full:
| Band | On a 1M-token window | On a 200K-token window | What happens |
|---|---|---|---|
| Yellow | 250K tokens (25%) | 60K tokens (30%) | The statusline turns yellow. |
| Red | 300K tokens (30%) | 100K tokens (50%) | The statusline turns red. Claude saves its place and asks. |
| 🔥 | 375K tokens (37.5%) | 125K tokens (62.5%) | The statusline shows 🔥. Claude asks again and recommends clearing. |
| 💀 | 450K tokens (45%) | 150K tokens (75%) | The statusline shows 💀. Claude asks again and recommends clearing. |
The red band sits at 300,000 tokens or half the window, whichever is smaller. 🔥 is 1.25 times red and 💀 is 1.5 times red. To ask even earlier, you can lower the red band for your machine. The setting lives in .gaia/local/protected/checkpoint-override.json, and Claude cannot edit it, so only you can set it. Run this yourself in a terminal from the root of your main copy of the repo (this example sets red at 100,000 tokens):
mkdir -p .gaia/local/protectedecho '{"version":1,"context_checkpoint":{"ask_tokens":100000}}' > .gaia/local/protected/checkpoint-override.jsonThe file can only lower the band, never raise it.
What Claude does at each band, and how to clear and pick up where you left off, is on Resuming long work.
Sub-agents
Section titled “Sub-agents”Long workflows hand work to sub-agents, and the bands apply to the ones that do long stretches of work. You don’t see this and have nothing to do; it is here so you know why a long plan does not degrade as it goes.
A sub-agent has no statusline, so a separate hook reads its context from its own transcript after each of its tool calls. It uses the same red, 🔥, and 💀 bands as your session, on the same window size. When a sub-agent reaches one:
- Red: it stops at the next clean point, with no tool call running and no file half-edited.
- 🔥: it stops before starting any new piece of work.
- 💀: it stops right away.
Before it stops, it writes a short handoff (the goal, what is done, what is next, and any half-finished work) and leaves its edits uncommitted. The workflow that started it checks the handoff and starts a fresh sub-agent with the same instructions, plus the handoff as progress notes. The handoff cannot widen the task: the new sub-agent keeps the original scope and permissions. A task can hand off twice. If it would need a third, the workflow stops and tells you, with every handoff it wrote, so you can decide how to continue.
This covers the sub-agents that do long stretches of work: the planner in /gaia-plan and each task’s sub-agent when a plan is carried out. The audit loop gets the same effect another way: it runs a few rounds at a time, each batch in a fresh sub-agent. Short, single-purpose sub-agents, such as reviewers, finish well inside their context and need neither.
Why so early?
Section titled “Why so early?”Models get less reliable as their context grows long, long before the window is full. They recall and use information less accurately, especially information in the middle of a long context. Researchers call this context rot. Chroma’s Context Rot (opens in a new tab) study tested 18 models and found that performance drops as input grows, even on simple tasks. See also Lost in the Middle (opens in a new tab) (Liu et al.) and Anthropic’s Effective context engineering for AI agents (opens in a new tab).
A long session also costs more. Claude Code sends the whole conversation with every request, so each step in a full session is billed for everything before it, even at the cached rate (opens in a new tab). A fresh session that resumes from a short saved state is both sharper and cheaper. GAIA’s band values are tuned estimates, not measured limits.
Why not wait for auto-compaction?
Section titled “Why not wait for auto-compaction?”Claude Code compacts a session on its own when the context fills: it replaces the conversation with a summary and carries on. By default that happens at the model’s context limit, or at about 967K tokens on a 1M-token window. See Default auto-compact thresholds (opens in a new tab). Clearing at the red band beats waiting for it in three ways:
- The summary is written late. By the time compaction runs, the session is far past the point where context rot sets in. The model writes the summary from that long context, so it can miss or blur details that mattered.
- What carries over is chosen. At the red band, Claude saves a short state of at most 4 KB: the goal, open decisions, what is done, and the one next step. A compaction summary is the model’s condensed version of the whole conversation.
- It costs less. Every turn before compaction is billed for the full history, and compaction itself is a request over that whole history (opens in a new tab). Claude Code’s own docs note that when you want a fresh start,
/clearcosts nothing.