TierDecay MCP server

TierDecay

The per-repo learning layer for AI coding model routers. It learns which of your recurring task classes can safely run on a cheaper tier — and hands that to the router you already use.

Native routers decide from population-wide signals. TierDecay adds the one signal they cannot see: your repo's own history of what passed where. One posterior, one deterministic engine, every agent: Claude Code, Codex, Antigravity, Cursor, Gemini CLI, and any MCP client.

---

The problem

Model routing is now built in: Cursor's router picks a model per request, Claude Code binds subagents to models and effort levels, Aider splits architect and editor. These routers decide from the request text and from signals pooled across every user. None of them remembers that in your repo add-migration-store has passed on the fast tier five times in a row — or that fix-flaky-test-jest failed there twice. On task 500 they know as little about your repo as on task 1.

Where TierDecay fits

	Native router (Cursor Auto, Claude Code subagents, …)	TierDecay
Learns from	the request, pooled usage across users	your repo's ledger: predicted vs. executed tier per task class
Decides	which model serves this request	which tier a recurring class has earned, with what evidence
Safety	provider heuristics	quarantine on any failure, sticky floors, confidence-gated decay, recertification on model/effort change
Output	a model call	a routing table and Agent Skills for the native router (tierdecay export)

TierDecay does not proxy or replace the router. It is three Markdown files, a protocol, and an optional deterministic advisor that turns your history into per-class routes the router can follow.

One brain, every agent

The same ledger and playbook drive every client; what changes is how each tool is told. Where a tool has native subagents, TierDecay binds its tiers to them; everywhere else it falls back to phases in one conversation.

Client	Tier binding	Delegation	Shared skills	State-write guard	MCP advisor	Install
Claude Code	alias × effort (opus/sonnet, low→xhigh)	4 subagents	✅	✅ PreToolUse hook	✅ claude mcp add	plugin or install.sh claude
OpenAI Codex	session model × model_reasoning_effort	4 roles (.codex/agents/)	✅ .agents/skills/	✅ hook on apply_patch/Bash	✅ .codex/config.toml	install.sh codex
Google Antigravity	pro / flash × Planning / Fast	4 subagents (.agents/agents/)	✅ .agents/skills/	protocol + VERIFY + doctor	✅ .agents/mcp_config.json	install.sh antigravity
Cursor	Auto goals (Cost / Balance / Intelligence)	single agent	export --format skills	protocol + VERIFY	✅	install.sh cursor
Gemini CLI	Pro / Flash	single agent	—	protocol + VERIFY	✅	install.sh gemini
Aider · Cline · Goose · Windsurf	architect/editor, Plan/Act, planner, picker	phases	—	protocol + VERIFY	client-dependent	install.sh <tool>
Any MCP client	—	—	—	read-only by default	✅ tierdecay mcp	npm i -g github:alebgl77/tierdecay

"✅ MCP advisor" means the client can run a local stdio MCP server; TierDecay speaks both the stateless 2026-07-28 protocol (server/discover, per-request version) and the initialize handshake of 2025-11-25 and earlier, so current and older clients connect without configuration.

The idea

Routing should learn from your repo. TierDecay is three markdown files and a protocol — no proxy, no daemon, no SDK:

File	Role	Analogy
SPEC (rubric)	How to route a task you've never seen	Cold-start prior
LEDGER	Predicted vs. executed tier, per task class	Empirical posterior
PLAYBOOK	High-tier solutions compiled into low-tier instructions	Compilation target

When an expensive model solves a hard problem, the orchestrator distills the decisions (invariants, ordering, the trap) into a ≤15-line playbook entry. The next occurrence of that problem class is probed one tier lower with the entry in context. Enough passing probes — 3, 4, or 5 depending on the class's risk, the smallest counts that give 80% confidence in a 50/60/70% pass rate — and the class's default tier drops. A model or effort change sends the class back to re-certify. The router learns your repo's difficulty distribution, and only as fast as the evidence allows.

How it works

Routing a task

flowchart TD
    A([New task]) --> S{Critical or risk 3?}
    S -- yes --> X[T3 safety]
    S -- no --> Q{Class quarantined?}
    Q -- yes --> X
    Q -- no --> B{Live playbook<br/>entry?}
    B -- "yes, other epoch" --> R[RECERTIFY at provenance<br/>model or effort changed]
    B -- yes --> E[PROBE: one tier below provenance<br/>entry quoted in the brief]
    B -- no --> D{Class in<br/>ledger PRIORS?}
    D -- yes --> C[Use empirical default tier<br/><i>skip scoring entirely</i>]
    D -- no --> F[Score the 4-axis rubric<br/>ambiguity · depth · blast radius · risk]
    F --> G{Sum}
    G -- "0–3" --> T1[T1 — cheap executor]
    G -- "4–6" --> T2[T2 — heavy executor]
    G -- "≥7 or any axis scores 3" --> T3[T3 — frontier specs<br/>T2 implements · T3 reviews]
    E -- pass --> H[hits +1<br/>3/4/5 hits by risk ⇒ tier drops]
    E -- fail --> I[Entry quarantined<br/>sticky floor · next route T3]

Sticky floors apply to every fallback and probe. T1 is the execution floor.

One task, end to end

sequenceDiagram
    autonumber
    participant O as Orchestrator (T3)
    participant S as Scout (T0)
    participant E as Executor (T1/T2)
    participant R as Reviewer (T3)
    participant L as Ledger + Playbook
    O->>S: recon mission
    S-->>O: recon report (≤400 words)
    O->>L: pre-check live playbook, then PRIORS
    O->>E: self-contained brief<br/>(objective · files · acceptance)
    E-->>O: diff + report + PLAYBOOK feedback
    O->>R: critical diff? REVIEW
    R-->>O: APPROVE / BLOCK + minimal fix
    O->>L: log row · distill pattern · update hits

Life of a problem class

stateDiagram-v2
    [*] --> Scored: first occurrence (rubric)
    Scored --> Distilled: T2/T3 success on a recurring class
    Distilled --> Probing: next occurrence → tier −1
    Probing --> Decayed: 3/4/5 probe hits (risk 0/1/2)
    Probing --> Quarantined: probe fails (sticky floor)
    Decayed --> Probing: probe the next tier down
    Quarantined --> Distilled: entry revised by orchestrator
    Scored --> Raised: 2 escalations → default tier +1
    Decayed --> Recertifying: model or effort changed
    Recertifying --> Probing: pass at provenance

The economics

Let n ≥ 0 be the number of future reuses after the initial high-tier solve, C_hi ≥ 0 the fully loaded cost of one occurrence routed at the high tier, C_lo ≥ 0 the expected fully loaded cost of one reuse attempt beginning at the low tier (including routing, verification, failures, and escalations), and C_distill ≥ 0 the one-time distillation cost after the initial solve. All costs must use the same units.

static routing:   S(n) = (n + 1) · C_hi
tier decay:       T(n) = C_hi + C_distill + n · C_lo
cost gap:         Δ = C_hi - C_lo

For Δ > 0, weak break-even (T(n) ≤ S(n)) occurs at n ≥ ceil(C_distill / Δ); strict savings (T(n) < S(n)) occur at n ≥ floor(C_distill / Δ) + 1. Equality occurs only when C_distill / Δ is an integer (at that value of n); otherwise the weak threshold already yields strict savings. Strict savings are impossible when Δ ≤ 0. If Δ < 0, weak break-even is equality and occurs only at n = 0 when C_distill = 0. If Δ = 0, equality holds for every n when C_distill = 0; otherwise there is no weak break-even.

Measured: pilot v1

benchmarks/pilot-v1 ran 36 real executor runs (Opus and Sonnet) on a controlled fixture with hidden acceptance tests: three recurring classes, three instances each, plus three distillation runs. This is a small controlled pilot; the protocol result below is a replay of its recorded outcomes, not an observed production-workload saving.

Route	Accepted	Cost per task (warm cache)
always frontier (opus)	9 / 9	0.180 USD
always fast tier (sonnet)	15 / 15	0.117 USD
TierDecay probe (sonnet + distilled entry)	12 / 12	0.111 USD

Two comparisons answer different questions:

• Fast tier without a playbook vs frontier: 0.66× warm-cache cost per task (task-paired 95% interval 0.63–0.69; nine tasks), with all attempts accepted.
• Protocol replay vs always-frontier: 24% lower modeled cost on those recorded outcomes, including distillation. The rubric selects the first instance's tier and later instances are probed. This does not establish an advantage over always-fast or a native router.

The distilled entry itself added no significant saving over a cold fast-tier attempt (0.97×, interval 0.90–1.05); 11 of 12 probes flagged a step of it as inaccurate or inapplicable. Read: on classes the cheap tier can already do, the value is the routing; the playbook matters where the cheap tier fails without it — a regime this pilot did not reach. One fixture, small n, one author: the limitations are spelled out.

Illustration

Illustration only, not benchmark evidence: let C_hi = 1, C_lo = 0.2, and C_distill = 0.1, and assume every low-tier probe succeeds without failure or escalation cost.

Occurrence	1 (initial)	2 (first reuse)	3	4	5
Static marginal	1.0×	1.0×	1.0×	1.0×	1.0×
Static cumulative	1.0×	2.0×	3.0×	4.0×	5.0×
TierDecay marginal	1.1× (solve+distill)	0.2× (probe)	0.2× (probe)	0.2× (decayed)	0.2×
TierDecay cumulative	1.1×	1.3×	1.5×	1.7×	1.9×

Here Δ = 0.8, so both thresholds are n ≥ 1: the first reuse recovers the overhead for this illustration only. Failures or escalations would raise the realized cumulative cost above the table.

Health metric: the executed column of your ledger should drift toward T1 over time for recurring classes. That drift is the product.

Deterministic engine, CLI, and MCP server

An optional local Node.js engine reads the same Markdown ledger and playbook. No runtime dependencies, network calls, or daemon. Routing decisions use no clock or random source. The only learned-state write is a validated, locked, atomic ledger append; lock expiry uses wall-clock time. Skills export writes derived files and removes its stale generated instructions.

tierdecay status                    # per class: route, hits vs. required, what the orchestrator owes
tierdecay doctor                    # health gate for CI: parse, cap, permissions, epochs; exit 1 on failure
tierdecay export --format codex     # routing table per client: claude | codex | antigravity | cursor | json
tierdecay export --format skills --out .agents/skills   # live entries as Agent Skills
tierdecay route --request request.json --policy shadow  # one decision, with the optimized recommendation
tierdecay observe --observation row.json --append .tierdecay/ledger.md   # lock · validate · fsync · rename
tierdecay bench --scenario outcomes.jsonl --config cfg.json --permutations 50   # order robustness
tierdecay mcp                       # the same logic as MCP tools over stdio (read-only by default)

(node bin/tierdecay.js … from a checkout; npm install -g github:alebgl77/tierdecay#v0.5.0 or the Claude Code plugin puts tierdecay on the PATH.) The MCP server exposes tierdecay_route, tierdecay_rubric, tierdecay_playbook, tierdecay_status, tierdecay_export, tierdecay_doctor, and tierdecay_validate_observation; tierdecay_record exists only with --allow-ledger-append true. shadow keeps the protocol's decision effective; optimize must be enabled explicitly with a calibrated economic configuration and fails closed to T3 until its statistical cells have enough samples. bench replays measured or hypothetical outcomes under seeded permutations with in-memory playbook evolution, because self-improving systems are path dependent and one replay order can flatter or hide a policy. See the router contract, JSON schemas, the pilot, and the synthetic regression fixture. No universal savings claim.

Generated from scripts/build-diagrams.js; CI fails if the SVGs drift from the generator.

Running in production (Linux)

Need	What ships
CI gate	action.yml: uses: alebgl77/tierdecay@v0.5.0 runs doctor, writes a job summary, fails the step on any failing check
Containers	Dockerfile: distroless nonroot, base images pinned by digest, runs with --read-only --network none
Concurrency	ledger appends take an exclusive lock, re-validate, fsync, and rename; stale locks are broken after 30 s
Supply chain	releases are cut by CI from a tag on main after the full matrix passes; archive + CycloneDX SBOM + SHA256SUMS
Operations	stable exit codes, bash completion, canonical JSON output, deterministic routing decisions

Full guide: docs/PRODUCTION.md.

Why it doesn't rot

Self-modifying instruction systems have one canonical failure mode: self-poisoning. TierDecay ships with the antibodies:

Failure mode	Defense
Executor writes garbage into the playbook	Only the orchestrator writes config paths; VERIFY rejects any executor diff touching them — and the Claude Code adapter blocks it in-tool (guard hook + ask-gated writes)
A bad pattern silently spreads	Any acceptance failure while an entry was referenced → instant QUARANTINE
Playbook grows into context rot	Hard cap 150 lines; eviction = lowest hits, oldest first
Over-eager downgrading	Downgrade needs 3 / 4 / 5 consecutive probe passes by risk (80% Clopper–Pearson); risk-3 work never decays; a failed probe sets a sticky floor
A new model or effort level silently invalidates history	Entries carry their binding epoch:; a mismatch forces recertification at provenance before any further descent
A lucky task order flatters the router	tierdecay bench replays under seeded permutations and reports the spread
Over-eager distillation	One-offs are never distilled; "a wrong pattern costs more than no pattern"
Rubric drifts from reality	It can't — it's only the cold-start prior; the ledger posterior overrides it both directions

Quick start

Claude Code — plugin (recommended):

/plugin marketplace add alebgl77/tierdecay
/plugin install tierdecay@tierdecay
/tierdecay:init          # in each project you opt in

See plugins/tierdecay. Every other CLI — and Claude Code without the plugin — uses the installer below.

For production, use only the latest tagged release. main is unreleased development and is intended for evaluation and contribution, not production use. Download both tierdecay-<version>.tar.gz along with tierdecay-<version>.cdx.json and SHA256SUMS from the release into the same directory, then verify the archive before extracting or running its installer:

# Linux
sha256sum --check SHA256SUMS
# macOS
shasum -a 256 -c SHA256SUMS
tar -xzf tierdecay-<version>.tar.gz

Proceed only when the checksum command reports OK. Replace <version> below with the release version you downloaded.

Prerequisites: one of the supported CLIs, and bash to run the installer — already present on macOS and Linux; on Windows use Git Bash or WSL. No service runtime, package manager, or API key is required. The Claude Code and Codex adapters require node for their local state-write guard hooks. The optional router requires Node.js 18+ for every adapter; the Markdown protocol itself does not. Nothing is installed globally: the installer only copies files into the repo you point it at.

cd your-project        # the repo you want to equip — NOT the tierdecay checkout
/path/to/tierdecay-<version>/install.sh auto
# or pick one explicitly:
/path/to/tierdecay-<version>/install.sh <claude|codex|antigravity|agents|cursor|gemini|aider|cline|goose|windsurf>