![\"frugal](\"assets/logo.png\"){kind=logo}
\n\n \n
Cloud cost awareness for coding agents.
\n\n\n ![\"npm\"](\"https://img.shields.io/npm/v/%40yuanbopang%2Ffrugal?color=cb3837&label=npm\")
![\"MIT\"](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
![\"CI\"](\"https://github.com/yuanboP/frugal/actions/workflows/test.yml/badge.svg\"){kind=icon}
\n ![\"22](\"https://img.shields.io/badge/services-22%20groups-blue\"){kind=icon}
![\"11+](\"https://img.shields.io/badge/hosts-11%2B-8A2BE2\"){kind=icon}
English | 简体中文
\n\n---\n\nAgents deploy to Vercel, spin up Neon databases, run E2B sandboxes, push\ncommits that trigger GitHub Actions — all metered — and non-technical users\nonly find out on the monthly bill. frugal makes the agent spend consciously:\nsurface free-tier numbers and fail-open vs hard-pause on first touch, optional\nusage digs, one-line notice before lasting paid resources, and tear down of\nwhat it left running. It never blocks the command.\n\nWorks across Claude Code, Codex, GitHub Copilot, Qoder, Gemini CLI, OpenCode,\npi, Cursor, Windsurf, Cline, and Kiro — one ruleset, one source of truth.\n\n### Why a plugin, not “just tell the model to be careful”?\n\nLLMs ship with **frozen training-cut knowledge** of free tiers, defaults, and\n“how this cloud bills.” Cloud pricing and fail-open traps move every quarter\n(Workflows per-step billing, Spend Management notify-only, free-tier cliffs).\nThe model still “remembers” last year’s story.\n\nfrugal keeps the numbers and tripwires **in the repo** — versioned, researched,\ntestable — and injects them into the agent loop on each session / pre-CLI hit.\nUpdate the package (or pull the repo) and the loop gets **current billing**,\nnot whatever the weights last memorized.\n\n## How it saves you money\n\nTwo layers, both context-cheap (~1.7 KB of rules per session + at most 5\nfull reminders per day — after that, new services still get a numbers-only\nline — never blocking), with intensity levels like a volume knob:\n\n| Level | Session + inject | When to use |\n|---|---|---|\n| **quiet** | Free-tier / key quota numbers only | Hate noise but still want numbers |\n| **normal** (default) | Numbers + one trap; dig optional | Most people |\n| **strict** | + real-bill context; confirm scary actions | Non-technical / vibe-coding |\n\n- **Session rules** (SessionStart): one short line on first touch, announce\n lasting paid resources, kill ephemeral things, escalate only for scary spend.\n- **Just-in-time data** (PreToolUse): `vercel` → short Vercel line,\n `wrangler r2` → R2, `git push` with workflows → Actions — once per provider\n per session. Horror-dollar amounts stay in **strict** (and the skill), not\n every deploy.\n\nThis is scoped to **normal usage that quietly runs up a bill** — wrong\ntier, a forgotten resource, a loop that hits a paid meter, a config default\nnobody checked. Not credential leaks or fraud; that's a security problem,\nnot a billing-awareness one. Real incidents from the 272-story X corpus\nthis plugin internalizes — and the tripwire that now fires first:\n\n| Real bill | What happened | frugal tripwire |\n|---|---|---|\n| **$36,000/mo** | Cloudflare queue re-enqueue loop (3.13B KV writes) | `wrangler` → \"NO hard cap anywhere on CF — guard recursion\" |\n| **$104,000** | Netlify viral-traffic bill (pre-reform) | `netlify` → credits system + hard-pause explained |\n| **$46,000** | viral traffic hit Vercel; Spend Management only emailed | `vercel` → Spend Management notifies at $200 — enable auto-pause |\n| **$25,672** | GCP spend blew past a $10 budget (alerts lag 24-48h) | rule: **alerts are not brakes** — pair with quota caps |\n| **~$700/mo** | agent push loop running full CI on macOS runners | `git push` with workflows → timeout-minutes + concurrency + macOS≈10x |\n| **$5,000/mo** | Firestore useEffect read loop at 100 users | `firebase` → per-READ billing + maxInstances + recursion check |\n| **$1,200** | Claude CLI silently billing API instead of subscription | `claude` with `ANTHROPIC_API_KEY` set → dual-rail warning |\n\n## What it does\n\n**1. Session rules** — injected at session start (mode-scaled).\n\n**2. In-the-moment reminders** — PreToolUse watches shell commands. Mode\npicks how loud each hit is — once per provider per session, never blocking:\n\n```\n# normal (default) — free-tier numbers + one trap; dig optional\nfrugal: Vercel — Hobby (non-commercial): 1M inv + 1M edge reqs, 360 GB-hr mem,\n100 GB transfer, 100 deploys/day — hard-pauses ~30d at quota. Pro fails open.\nSpend Management defaults to notify-only at $200 — enable its auto-pause for\na real stop. Optional: `vercel usage`.\n```\n\n`brief` always carries the decisive free-tier numbers (what agent needs to\nreason). Horror dollars stay in **strict**. Dig is optional (skip if no creds).\nDetection is sub-service aware: `wrangler r2`, `gh workflow run`, `git push`\nwith workflows, dual-rail agent CLI when an API key is in the env.\n\n**3. Researched quota data** — the reminders and the skill's cheat-sheet\ncarry real numbers (researched 2026-07, dual-engine: parallel Claude web\nresearch + grok CLI runs per provider, cross-checked against official\npricing pages). Full plan tables, overage prices, cost traps, and sources:\n[`skills/frugal/references/providers.md`](skills/frugal/references/providers.md).\nThe complete raw research — both engines' reports per provider plus the\nmerged machine-readable factsheets — is archived in\n[`research/`](research/).\n\nCovered: Vercel, Cloudflare (Workers/R2/KV/D1), Neon, Railway, Fly.io, E2B,\nBrowserbase, GitHub (Actions/Codespaces), Supabase, AWS/GCP/Azure,\nTerraform/Pulumi.\n\n**4. `/frugal`** — cheat-sheet + spend audit. Levels:\n`/frugal quiet|normal|strict|off`, persist with `/frugal default