Token Efficiency

Ultra Claude burns more tokens than normal development. That's by design — dedicated Reviewers, Testers, and a shared Knowledge agent increase quality, but they cost context. The framework is built to make that trade-off worthwhile and keep usage under control.

Cost model

Token cost scales with the number of task teams, not with task size — every code task spins up an Executor + Reviewer + Tester team, while an ops task runs a solo Executor. That's why planning targets fewer, larger tasks (~10–40 files each) and caps plans at 4 tasks without your explicit agreement. There is no upfront token estimate — predicted numbers proved to be guesswork — so the framework spends its effort on the real levers instead: team count, per-task executor model choice, and the Project Manager's post-run report of what actually happened.

Why it's worth it

Normal Claude Code development is one agent doing everything — writing code, hoping it follows patterns, and trusting it works. Ultra Claude adds dedicated roles:

• Reviewer catches pattern violations and standards drift before code is merged
• Tester validates against product docs, not just "does it compile"
• Cache-first research serves current API docs so agents work with real signatures, not stale training data — and the cache persists across plans, so a second plan touching the same libraries pays almost nothing for knowledge

The extra tokens buy you code that follows your standards, passes real tests, and uses current library APIs. Without them, you spend the same tokens later fixing the bugs that review and testing would have caught.

How the framework saves tokens

Model assignment

The Executor's model is chosen per task during planning — Sonnet for mechanical, pattern-following work; Opus as the default for code delivery; Fable for the architectural hard end (requires your explicit approval — it burns usage at roughly 2× Opus). Every other role — Reviewer, Tester, Project Manager, researcher subagent — runs on Sonnet. This concentrates cost where capability matters most: writing code.

Waiting is free — the full team spawns upfront

All three team members spawn together at task start. That's affordable because a parked agent costs nothing: each agent arms one persistent inbox monitor and a "wait" is just yielding its turn — tokens are spent per wake, not per minute of idling. So instead of deferring the Tester to save imaginary idle burn, the framework puts its idle window to work: the Tester front-loads a TESTER TAKE (the acceptance-case list and unit-layer test contract) before the Executor plans, and drafts black-box acceptance tests while implementation runs. The Executor's "code complete" signal is fire-and-forget — no spawn handshake blocks the pipeline at its hottest point.

Signal file I/O overhead

The per-task signals.jsonl file adds ~1K–5K tokens of overhead per task across all signal reads and writes. Each signal append costs a single echo >> bash call (~50 tokens). Each agent arms one persistent tail -F inbox monitor at startup and never re-arms: it burns zero tokens while parked and costs one small re-invocation only when a signal relevant to it actually lands — no periodic wake-up churn, and the agent stays responsive to direct messages the whole time. Because the monitor follows the file directly, a silently-dropped SendMessage still wakes the agent (the append is what it watches). This is negligible compared to the cost of a stalled pipeline (thousands of wasted tokens across multiple idle agents waiting for messages that never arrive).

Cache-first research (Lead as Sage)

Research findings are committed as first-class project documentation under documentation/technology/research/, not invisible cache. The /uc:research skill checks a small JSON index via jq before spawning anything — fresh entries (per-file expires field, library 10d / patterns 90d / market 30d / historical frozen) return immediately with zero agent overhead. Cache misses dispatch the stateless researcher subagent in the background by default (one-shot: no name, explicit run_in_background: true — the conversation continues, and findings are relayed when the completion notification arrives; --sync blocks instead when the answer gates the very next step); it writes the target file, updates the index, and exits. No persistent knowledge teammate, no per-task duplicate lookups, and the knowledge base grows across plans.

Two spawn modes of the Agent tool

Both spawn paths use the single Agent tool; the parameters decide which entity you get. Teammate mode (name + run_in_background: true) is persistent, stateful, and tracked on the PM dashboard. One-shot mode (no name) is stateless and invisible to the team graph, and comes in two explicit flavors: sync (run_in_background: false — the result gates the next step) and fan-out (run_in_background: true — parallel workers collected via completion notifications). Background is the Claude Code default since v2.1.198, so Ultra Claude states run_in_background explicitly at every spawn site rather than relying on the default. The researcher uses one-shot fan-out by default — it fits the pattern "do this one thing, return the answer, die," and backgrounding it keeps the main conversation (or the Lead, mid-execution) responsive while it works; making it a persistent teammate would waste tokens on a lifecycle it doesn't need.

Ref.tools integration

External library documentation is fetched via Ref.tools MCP at ~500–5K tokens per query. The fallback (raw web search) costs 50K+ tokens for the same information. Combined with the cache, the per-lookup cost on a repeated topic drops to zero.

Checkpoint recovery

When a session dies mid-execution, checkpoints let you resume without re-running completed tasks. A 10-task plan interrupted after task 5 resumes from task 6 — the 600K tokens already spent on tasks 1–5 are not re-spent.

Concurrency limits

Parallel execution is capped at 1–4 task-teams based on plan size. This prevents token burn from too many agents running simultaneously while still allowing parallel progress.

Statusline cost awareness

The statusline shows a live cache indicator and response weight bar. The cache indicator (• green = warm, ○ red = cold) tracks the 5-minute Anthropic prompt cache TTL with a live countdown. The weight bar ($▁▂▃▅▇) combines context fill percentage, model type, and cache state into a single visual — it jumps in real time when the cache expires, showing the cost difference between cached and uncached responses.

Usage management

Usage limits are handled reactively — no question at plan start, no babysitting, and no wasted window. The limit itself is the pause; the machine-global limit sentinel is the resume.

1. Execution rides every 5-hour window to 100%. The old design stopped proactively at 90–95%, sacrificing ~10% of every window as a safety margin. Nothing proactively stops in-flight work anymore: when the limit hits, sessions park at their composer with full context — a free, uncoordinated pause.
2. The limit sentinel resumes everything automatically. One machine-global background process (scripts/limit-sentinel.sh, installed by /uc:setup — a script, not an agent) detects limit hits via a StopFailure hook, knows every account’s reset time, and at reset (+90s) wakes the whole fleet: durable RESUME signals plus tmux pane injection, including standalone (non-plan) sessions. No tokens are burned while parked, and no early wakes are wasted into a still-active limit.
3. At 90% the sentinel injects a soft-band advisory into the Lead pane: finish in-flight work, don’t start new tasks. That is the only proactive element left, and it costs one injected line. PM does not monitor usage at all — its background monitor is liveness-only (NUDGE candidates for yield-rule violations, verified before anyone is pinged), and it consumes the sentinel’s usage events passively for per-task budget tracking.

Per-task budget data (usage % at start/end of each task) is tracked in plan.json. If a weekly (7d) limit is hit you’re notified — a days-long park is a user decision. Opt out of the soft-band gating with an explicit “full speed” instruction; reset wakes always happen regardless.