Frugal

frugal

A cost-optimised agent router for Claude Code. Frugal teaches the main loop to send every sub-task to the cheapest execution strategy that can succeed, and to escalate only on verified failure:

deterministic tool → haiku worker → sonnet worker → main model → fable (escalation ceiling)

The expensive reasoning model plans and judges; commodity work (locating files, extracting data, mechanical edits) runs on cheap tiers. No framework, no runtime, no API keys: frugal is a plugin made of a routing skill, five agent definitions, and two small hooks. The harness does the rest.

Install

/plugin marketplace add ThomasLangbroek/frugal
/plugin install frugal@frugal-marketplace

How it works

The main model already reads every request, so it acts as the router at zero marginal cost. The routing skill gives it one decision table:

Task	Agent	Model
locate, grep, map structure, find usages	scout	Haiku
extract, classify, summarise one source	extractor	Haiku
mechanical edits from a complete spec	mechanic	Sonnet
implement one scoped task from an approved plan	builder	Sonnet
design, debugging, ambiguity, risk	main loop	whatever you run
beyond the main loop's tier, or isolated deep reviews	sage	Fable

Plus a tool-first rule: if grep, jq, git, terraform or any deterministic command solves the task, no model is called at all.

Escalation (verification first)

Workers do not self-grade their way up the ladder. Every worker ends with a fixed footer:

RESULT: <one line>
CHECKS-RUN: <commands run and outcomes, or "none">
UNCERTAINTIES: <or "none">
ESCALATE: yes|no - <reason>

The router then applies four rules:

1. If a deterministic check exists (tests, compiler, schema validation, terraform validate), run it. Pass = done. Fail = escalate one tier, maximum one retry, then the main loop takes over.
2. No check available: the main model spot-reads the result. It receives it anyway, so judging it costs almost nothing.
3. The worker's ESCALATE: yes is advisory input, never the sole trigger. Self-reported confidence from a cheap model is poorly calibrated; observable failure is not.
4. Never start at an expensive tier unless the decision table requires it. sage (Fable) is reached only via high-risk table rows or after escalation exhausts, one attempt, final.

Metrics and the cost report

A SubagentStop hook logs one jsonl line per worker run (agent, model, token usage, escalation flag) to ~/.claude/frugal/metrics.jsonl. Run:

/frugal:router-stats

to get cost per tier, escalation rate, and estimated savings versus running the same work on your session's actual main-loop model (recorded per run; older records without it are compared against the top tier). Prices live in scripts/stats.py (PRICES); update them when Anthropic pricing changes. Learning is deliberately offline: read the report, edit the decision table.

Enforcement

Routing policy in a skill is advisory: the model follows it well, but a prompt cannot forcibly prevent anything. Frugal therefore enforces on three levels, the first two active out of the box:

1. Policy injection. A SessionStart hook puts the routing policy in context at every session start; a UserPromptSubmit hook re-pins a one-line reminder on every prompt. No drift, nothing to invoke manually.
2. Inline-exploration budget. A PreToolUse guard counts search-type tool calls (Read, Grep, Glob, search-y Bash) in the main loop. Past the budget (default 5 per prompt) further ones are denied with a pointer to the cheap workers. The budget resets on any delegation or new prompt; worker agents are never throttled. Non-search commands (git, test runners, builds) are never blocked.
3. Expensive-tier guard (opt-in). hooks/guard_expensive.sh blocks sage spawns entirely. Wire it as a PreToolUse hook with matcher Agent in your settings.json if you want a hard ceiling.

Judgement lives in prompts; enforcement lives in hooks.

Knobs

Knob	Default	Effect
FRUGAL_INLINE_BUDGET	5	Inline search ops allowed per prompt before the guard denies
FRUGAL_ALLOW_INLINE=1	unset	Disables the inline-exploration guard for the session
FRUGAL_ALLOW_EXPENSIVE=1	unset	Allows sage spawns past the opt-in expensive-tier guard
FRUGAL_METRICS_PATH	~/.claude/frugal/metrics.jsonl	Where worker-run metrics are written
/frugal:models	agent defaults	Per-project model overrides, e.g. /frugal:models scout=sonnet
.claude/routing-overrides.md	none	Per-project routing rules; read first, always win