moai-adk

"Tokenomics is a harness designed to make token consumption economical."

MoAI-ADK is a Tokenomics Harness

MoAI-ADK (Agentic Development Kit) enables Claude Code to produce code, then makes that code reliable at predictable cost. A harness wraps the model from the outside. The model is a stochastic worker moving token by token — it remembers neither budget, nor quality bar, nor where the last session broke off. Cost ceilings, passing test suites, continuity that survives /clear — properties like these cannot be re-seeded by a prompt every turn; the system must enforce them from the outside.

Every design decision serves one goal: token economics — the same quality for fewer tokens, higher quality for the same tokens. Which model to use, how deeply to reason, how to spend context — none of this is left to chance turn by turn; the system decides.

It does not replace Claude Code. It only wraps, in structure, the parts Claude Code leaves to you — model routing, quality gates, cost control, session continuity. A single binary written in Go, it runs on macOS, Linux, and Windows with no extra dependencies.

Why Tokenomics

Token prices keep falling, but actual agent workflow spend rises. Agents spin through dozens to hundreds of steps to solve a single task, consuming proportionally more tokens. In usage-based pricing, this becomes the invoice; in subscription, it consumes the weekly quota shared by all models.

Cost is determined by assignment, not unit price

The DeepSWE leaderboard (113 tasks) demonstrates this problem. Even within the same Claude family and at the same max effort, per-task costs vary widely.

Sonnet 5 max is more expensive than Opus 4.8 max per task ($26.40 vs $13.22) while scoring lower (54% vs 59%). The cause is 268 steps — at max effort, retry loops explode. "Use a weaker model harder to save money" does not hold. It burns three times the steps, consuming more quota. Cost is determined by assigning the right model and reasoning depth to each task, not by unit price.

MoAI-ADK systematizes this assignment instead of leaving it to chance.

Three Axes of Economization

Routing — Assign the right model and reasoning depth to each task

Tier×Phase Matrix. Declaratively assign models and reasoning effort (effort) by work phase (plan / run / sync) and SPEC size (Tier S / M / L). Deploy high-reasoning models to planning phases that need deep inference, and light models to implementation phases with mechanical repetition. Maximize quality per cost.

No-Haiku 3-Tier Policy. Exclude Haiku from the routing model set, distributing work across a 3-tier structure (Sonnet / Opus / Fable). Assign Sonnet low effort to mechanical tasks to minimize step count, and deploy upper-tier models where reasoning matters.

Profile Matrix. A single per-agent profile matrix maps each retained agent to a {model, effort} pair. One profile axis — max / medium (default) / low, selected via llm.profile (moai init --profile, moai update --profile) — picks the active column; moai model profile resolves each agent's cell. The 10 grouped agents draw model+effort from the matrix (no Haiku anywhere), while Explore and user-defined agents inherit the session model.

CG Mode (Claude + GLM). moai cg is a hybrid mode combining Claude leader and GLM workers. Strategy, planning, and audits run on Claude; bulk implementation runs on GLM. 60-70% cost savings on implementation-heavy workloads.

Verification Economy — Diet context, persist evidence to disk

verify-diet. Redirect verbose verification output to disk files, leaving only exit code and bounded tail (max 50 lines) in context. This file-redirect contract maintains verification evidence integrity while reducing context consumption. Evidence persists under .moai/state/verify/<session>/.

Prompt Cache. When a request's prefix matches the previous request, reuse that section instead of reprocessing. Cached reads cost 0.1× the base input price. Minimize always-loaded instructions and the hit rate rises immediately. The statusline cache hit segment (♻️) shows real-time monitoring.

Context Diet. Apply /clear strategy. When SPEC phase completes, /clear and save progress to progress.md, then issue a paste-ready resume message. At context window thresholds (1M model 50% / 200K model 90%), automatic recommendations appear.

Budget Defense — Stop before overage, resume in next session

Token Circuit Breaker. When agent token usage hits hard-limit (default 90%), execute abort. Save progress to progress.md, issue paste-ready resume message, and never auto-/clear. The system only recommends /clear; the user decides and executes.

Statusline. Keep context usage rate (CW%), prompt cache hit rate, and rate limit depletion visible in terminal at all times. The (⚠️/clear) marker next to CW% appears at model-specific thresholds.

Infrastructure Sustains Tokenomics

Quality Structure — Prevent rework and debug loops (worst token waste)

SPEC 3-Phase Lifecycle. plan → run → sync. Tier S/M/L size classification determines verification depth and PR routing. GEARS format requirements + acceptance criteria judge completion by evidence.

TRUST 5 Quality Gates. Tested (85%+ coverage) · Readable · Unified · Secured · Trackable, applied to every change. Gates judge verification, not agents.

11-Agent Catalog. MoAI custom 10 + built-in Explore. Separate planning and auditing from the start so the authoring side cannot grade its own work.

Learning Loops — Token efficiency improves as loops run

/moai goal·/moai loop. Declare a completion condition and the session works until it is satisfied or the turn limit (default 30) is reached. /moai loop scans LSP diagnostics · AST-grep · linter in parallel, buckets issues by level, and runs until the queue drains.

Routing Ledger. Record routing decisions and gate evidence as privacy-preserving digests. Observations upgrade to rules.

4-Tier Learning Ladder. Observation (≥1) → Heuristic (≥3) → Rule (≥5) → Auto-update (≥10, user approval required); trust threshold 0.70. All applications revertible via moai harness rollback.

Decision Memory. Questions emerge where uncertainty is highest (p ≈ 0.5); recommendations follow observed statistical majority, not system defaults.

Extension Points — Duplicate proven patterns for project-specific reuse efficiency

Harness v4 Builder. Natural language request → domain·goal·constraint extraction → approval gate → project-specific agents·skills·commands·hooks scaffolding.

@MX Tags. Inline code annotations where AI agents exchange context, invariants, and danger zones.

worktree isolation. Attach isolated worktrees per SPEC for parallel development via /moai plan --worktree.

Quick Start

Install

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex

Build from source (Go 1.26+)

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build

Project Initialization

moai init my-project

Interactive wizard auto-detects language, framework, and methodology, selects model policy, and generates Claude Code integration files.

First Workflow

claude        # launch Claude Code inside the project

/moai plan "Add JWT login"      # author a SPEC
/moai run SPEC-AUTH-001         # TDD/DDD implementation
/moai sync SPEC-AUTH-001        # sync docs + create PR

Natural language works too. `/moai "fix the login bug