Subagent
Breaks a window's cost down per subagent and flags right-sizing candidates.
Claude Code spawns subagents through the Task tool, and their turns land under the parent session. Folded into one parent total, a heavy research session’s subagent spend hides where the tokens actually went. On one real session TokenJam measured 66% of spend across ~147 subagents, invisible above the DB. Subagent breaks a window’s cost down per subagent and flags right-sizing candidates.
tj optimize subagentClaude Code only
The analyzer groups spans by (session_id, sub_agent_id). That sub_agent_id is populated only by the Claude Code backfill path, derived from the on-disk transcript. Spans from other runtimes (Codex, the Python SDK, generic OTLP) carry no subagent id and are excluded.
What it flags
Each (session, sub_agent_id) group with cost at or above $0.05 (a noise floor) is checked against two independent structural criteria:
| Flag | Criteria |
|---|---|
over_powered | Ran on an Opus-tier model, produced fewer than 2,000 output tokens, and made 5 or fewer tool calls. The Downsize heuristic scoped to one subagent. |
over_provisioned | Handed a large context (input plus cache-read tokens at or above 50,000) yet produced fewer than 2,000 output tokens. The prompt it was dispatched with is likely larger than the task needed. |
A single subagent can carry both flags. The analyzer reads aggregate token counts only, so no content capture is required.
How to read the output
The finding reports, for the window: how many subagents ran and across how many sessions; how much of the total cost ran inside subagents at all before any flagging (subagent_cost_usd / percent_of_cost); the spend concentrated in flagged candidates (flagged_cost_usd); the top subagents by cost; and the top flagged candidates with their flags. Rendering follows the same plan-tier convention as the rest of tj optimize — API plans see the dollar share, subscription and local plans see the token share.
Honesty caveat
This is a descriptive breakdown with candidate flags, not a savings promise. estimated_recoverable_usd is deliberately left unset; the analyzer surfaces the spend sitting in flagged subagents rather than assert a recovery. The confidence is heuristic, and the flagging caveat mirrors Downsize:
Candidate-flagging heuristic, not a quality judgment. Review the flagged subagents before changing how you dispatch them or which model they use.
It never claims the flagged subagent’s task would have succeeded on a cheaper model or with a smaller prompt. It claims only that the structural shape matches a class worth a closer look.
See also
- Downsize — the same heuristic scoped to whole sessions
- Cost visibility — where your quota goes and what you reclaimed