Skip to main content

Tokenomics Overview

UPDATED 2026-09-29 6 min read EDIT ON GITHUB ↗

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.

Why Tokenomics

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.

  1. 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.
  2. Diet the context — minimize always-loaded instructions and measure prompt-cache hit rate.
  3. System-enforced budget — track token usage and stop gracefully before the threshold is exceeded.

The 3-Pillar Narrative

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.

The 4-Layer Tokenomics Structure

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

Layer A — Metering

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.

Layer B — Routing

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.

Layer C — Verify-diet

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.

Layer D — Budget defense

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.

Prompt Cache: Reusing the Same Instructions Cheaply

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 --> W

Because 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.

Per-Model Context Thresholds

The operational threshold at which the budget guard stops is model-specific. Larger windows tolerate higher utilization; smaller windows have less absolute headroom.

Model classWindowHandoff thresholdAbsolute ceiling
Opus 5.5 (1M)1,000,000 tokens50%~500,000 tokens
GLM-5.3 (1M)1,000,000 tokens50%~500,000 tokens
Fable / Sonnet 5.5 (1M)1,000,000 tokens50%~500,000 tokens
Sonnet 4.5 and earlier (200K)200,000 tokens90%~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.

CG retirement and migration

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.

Verified Facts and Roadmap

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.

Next Steps