Tokenomics Overview
Tokenomics (Token Economics) is the first pillar of MoAI-ADK v3.0. Even as per-token prices fall, agentic development consumes tokens at scale, so what determines cost is not the model price but how tokens are managed. This page overviews the tokenomics architecture and links to the deep-dive pages for each sub-topic.
As multiple agents run, contexts grow longer, and reasoning deepens, a single session’s token consumption increases sharply. When token-price declines cannot keep pace with token-usage growth, how the harness measures, routes, diets, and defends tokens becomes the core axis of cost competitiveness.
MoAI-ADK’s answer has three parts.
- Set the right model and reasoning depth for the session — the main session’s model and effort carry over to every subagent, so one well-chosen session is the whole assignment.
- Diet the context — minimize always-loaded instructions and measure prompt-cache hit rate.
- System-enforced budget — track token usage and stop gracefully before the threshold is exceeded.
v3.0 product differentiation consists of three core values. Tokenomics is the first, tightly connected to the other two.
Tokenomics (this page) — meter, route, diet, defend.
Autonomous Continuation Loops — when to stop, when to continue. Covered in the Autonomous Continuation Loops page.
Agentic Harness — which agent, at which profile, how it evolves. Covered in the 3-Tier Architecture, Profile Matrix, and Harness Self-Evolution pages.
Tokenomics consists of four layers. Each layer operates independently while complementing the others.
flowchart TD
A["Layer A — Metering
per-SPEC token accounting"]
B["Layer B — Routing
session-level model/effort"]
C["Layer C — Verify-diet
verbatim evidence to file, summary to context"]
D["Layer D — Budget defense
90% hard-limit graceful stop"]
A --> B
B --> C
C --> D Every agent call’s token usage is accounted at the per-SPEC level. The token column in moai spec audit output and the token-accounting section in progress.md are this layer’s outputs. Without knowing what consumed tokens, optimization is impossible.
The session’s model and reasoning depth (effort) are chosen — and since v3.2 the unit of routing is the session, not the agent. The main session’s model and effort are inherited by every subagent; the session effort is adjusted with /effort and ultrathink, and the profile wizard’s session model policy sets the default effort fallback for when no depth is chosen. There is no per-agent assignment table to maintain anymore. MoAI-ADK v3.0 excludes Haiku from the routing model set, and the 3-tier structure keyed to task character — Sonnet for single-shot work, Opus across the agentic ladder, with the higher effort levels concentrated on judgment work (auditing, advising, coordinating) — remains the judgment standard for choosing a session model. The rationale for this design and the inheritance rule are covered in the 3-Tier Agent Architecture, Profile Matrix, and Model Policy pages.
Long verification-command output is redirected to disk files, and only the exit code and a bounded tail (max 50 lines) remain in context. This file-redirect contract reduces context consumption while maintaining verification-evidence integrity. Dieting is not limited to verification output — minimizing always-loaded instructions and raising the prompt-cache hit rate also belong to this layer. For the detailed mechanism, see the Token Budget Management and Graceful Stop page.
When an agent’s token usage reaches the hard-limit (default 90%), a graceful abort is performed. Progress is saved to progress.md, a paste-ready resume message is emitted, and auto-/clear is never performed. For the detailed procedure, see the Token Budget Management and Graceful Stop page.
A cost structure often overlooked in tokenomics is the prompt cache — a feature that briefly stores previously sent input. Anthropic’s prompt caching works as a prefix match over the front of the rendered request (in the order tools → system → messages). The first time, that prefix must be written to the cache at 1.25× cost, but subsequent turns reusing the same prefix read it at 0.1× cost. This is a structure that can make a single turn’s input nearly 10× cheaper.
There are two traps here.
First, the cache lifetime is 5 minutes. But this 5 minutes is not “expires after 5 minutes” — it is “expires when an idle gap longer than 5 minutes occurs.” When the wait at a user gate stretches on, the cache expires, and the next turn must re-write the entire prefix at 1.25×. So a question asked late costs more.
Second, a cache cannot be read while it is being written. When multiple agents sharing the same definition are launched at once, the simultaneously departing requests do not wait for the first to finish writing to the cache, so each re-writes the prefix cold.
flowchart TD
T1["Turn 1
instructions/rules prefix
sent for the first time"]
W["Cache write
1.25x cost"]
T2["Turn 2 to N
same prefix reused"]
H["Cache hit
0.1x cost"]
GAP["Idle gap over 5 min
user-gate wait etc."]
MISS["Cache expires
re-write at 1.25x"]
T1 --> W
W --> T2
T2 --> H
H --> T2
T2 --> GAP
GAP --> MISS
MISS --> WBecause of this structure, MoAI-ADK consciously adjusts execution order. User gates are asked early when the context is small; when launching multiple agents of the same kind in parallel, one is spawned first to warm the cache before the rest follow (stagger-spawn); session-start instruction files are not edited mid-session but deferred to the end of the task. The cache does not change gate semantics — approval gates remain mandatory, and cache-aware execution only adjusts when and in what order those gates are asked.
The operational threshold at which the budget guard stops is model-specific. Larger windows tolerate higher utilization; smaller windows have less absolute headroom.
| Model class | Window | Handoff threshold | Absolute ceiling |
|---|---|---|---|
| Opus 5.5 (1M) | 1,000,000 tokens | 50% | ~500,000 tokens |
| GLM-5.3 (1M) | 1,000,000 tokens | 50% | ~500,000 tokens |
| Fable / Sonnet 5.5 (1M) | 1,000,000 tokens | 50% | ~500,000 tokens |
| Sonnet 4.5 and earlier (200K) | 200,000 tokens | 90% | ~180,000 tokens |
The 1M-context models (Opus 5.5, GLM-5.3) recommend handoff at 50%. A wider window does not mean using it to the end — folding earlier to protect cache and headroom is the more stable choice. Watch the statusline context gauge (CW%) and prepare a /clear as you approach the threshold. For the detailed procedure and handoff-message structure, see the Token Budget Management and Graceful Stop page.
moai cg has been retired. It exits with a migration diagnostic without starting Claude or GLM. It is not an alias for moai cc. Projects with llm.team_mode: cg must make an explicit migration choice before launching a session. CG retirement and migration
This writes llm.team_mode: claude, llm.gateway.teammate_mode: in-process, and llm.gateway.teammate_provider: inherit. It removes the old hybrid role assignment; it does not preserve a Claude leader with GLM teammate panes.
The claude-glm target describes a Claude leader with GLM teammates in tmux. Its apply and launch paths are currently unavailable because the TEAMMATE integration gate has not passed. Preview is available. Installing tmux or setting verified: true does not open this gate.
The implementation status of the content on this page is clearly distinguished.
Implemented (shipped) — all 4 layers (A/B/C/D), session-inheritance model policy (the session’s model·effort inherited by subagents; the session model policy as effort fallback), verify-diet file-redirect contract, graceful-abort mechanism.
Design-stage (roadmap) — the GLM backend effort overlay’s wire effectiveness is a verification item requiring live GLM session outbound observation. The Profile Matrix page states this distinction explicitly.
- Token Budget Management and Graceful Stop — Layer D deep-dive (per-model thresholds, paste-ready resume structure)
- 3-Tier Agent Architecture — harness architecture foundation
- Profile Matrix — what replaced the matrix, and the session-inheritance rule