# Quota Rules

> A quota rule watches one quota gauge of a provider (an account, a window, a threshold) and acts on its own when the condition is met: block some launches, send a launch to another account, launch on another provider, model or effort, run one of your triggers, or move the agents already running to another account.

- Area: Desktop app
- Plans: All plans
- Last checked against the product: 2026-09-29
- Web page: https://agentsroom.dev/docs/quota-rules

## What it does

A quota rule watches one quota gauge of a provider (an account, a window, a threshold) and acts on its own when the condition is met: block some launches, send a launch to another account, launch on another provider, model or effort, run one of your triggers, or move the agents already running to another account. Examples: "at 99 % of the Claude session, keep scheduled agents from starting", "at 90 %, run new agents on a more economical model", "when the week reaches 90 %, run the cleanup brief", "when Claude reaches 99 % on any gauge, start new agents on Codex". Rules run while AgentsRoom is open. Since 2026-09-23 they are also what drives [Account Auto-Switch](https://agentsroom.dev/docs/account-auto-switch.md): the old global switch became rules.

## Where to find it

- Footer **usage** badge > **Usage** panel > **Quota management** card in the right column, just under the **Temporary launch override** card (since 2026-09-25 the panel has two columns: the gauges on the left, every action on the right). It reads "Set up a rule: block, redirect or trigger on a quota." when you have none, "N in force" otherwise, with a dot when a rule is acting right now.
- Clicking it opens the **Quota rules** window (**Quota automation**), with **New rule**, the list of rules and the editor.
- Settings > AI providers & accounts, last row of the **Multiple Accounts** section: a **Quota rules** shortcut with the same "N in force" badge and a **Manage rules** button opening the same window (since 2026-09-28: a user looking for why accounts do not switch on their own looks in Settings first). The Settings search finds it ("quota", "rule", "switch").

## How to use it

1. Open **Quota management** and pick a template under **Start from a template**: **Use another provider** (Claude at 99 % on any gauge, new launches go to Codex; shown as "Claude → Codex"), **Use a lighter model** (90 %, change model or effort), **Use another account** (95 %, redirect the launch), **Run a recovery trigger** (90 %, run a trigger). Each card shows the real condition sentence of the rule it creates. Or press **New rule**.
2. The editor draws the rule the way the list does, as a diagram you click: the **Quota to watch** box, an arrow carrying the threshold, and the **Then** box. Clicking one opens a small panel holding only that part's settings, so nothing else is on screen while you set it (since 2026-09-29; the old editor opened on a grid of providers and showed every field at once).
3. **Quota to watch**: the provider, the **Account** (**Most constrained** looks at whichever account is closest to the wall, or one named account) and the **Model group** when the provider publishes a separate quota per group of models (Antigravity: **Gemini Models** and **Claude and GPT models**; Claude: a model's own weekly gauge; Codex: a model family; Cursor: **Included usage**, **Auto usage**, **API usage**), **All groups** by default.
4. The arrow: **Threshold** from 1 to 100 % with **reaches** or **drops under**, and the **Window** (**Any gauge**, **Session**, **Day**, **Week**, **Month**; every new rule, blank or from a template, starts on **Any gauge**).
5. The two rare conditions are dashed **+** chips under the diagram instead of fields: **Only near the reset** (**Any time**, 10 min, 30 min, 60 min, 3 h) fires in the last minutes of the window, and **Second condition** (**Required**) asks a second window to hold too, since "20 % left" means little if the week is at 95 %. Once added they show as labels on the arrow.
6. **Then**: pick the action, fill what it needs (**Which launches**, **Account to use**, **Launch on** with model and effort, **Project** and **Trigger**), and **Save**. The name is optional.
7. Under the diagram, the rule is written out as a sentence, then the line **Right now:** says what it would do with the current reading (**Will not fire, 42%**, **Firing now, 99%**, **No reading yet**); a rule still missing something says so there too. Each row of the list carries the same status.

The actions:
- **Block a launch**: stops launches of that provider before they consume quota. **Which launches**: **Every launch**, **Scheduled agents**, **Webhook calls** or **Manual launches**. A blocked agent prints a red line "Quota rule "X": launch blocked" in its terminal; a blocked trigger does not open an empty tab and notifies you instead.
- **Redirect a launch**: sends the launch to another account of the same provider. Only the account changes; provider, model and conversation stay.
- **Change provider, model or effort**: new launches run on the chosen provider, model and reasoning effort while the condition holds. Saved agent settings are untouched. Picking another CLI shows **Different CLI: launches only**: an agent already running never changes CLI.
- **Run a trigger**: starts an existing trigger of a project, once per quota window.
- **Move running agents**: switches the agents running on that account to another signed-in account, same provider, same conversation (see [Account Auto-Switch](https://agentsroom.dev/docs/account-auto-switch.md)).

**Which models** (block, redirect and change actions, shown when the provider publishes model groups): **Those of the reached gauge**, the default of a new rule, only touches the launches whose model draws from the gauge that met the threshold: with Antigravity's **Claude and GPT models** gauge at 100 % and **Gemini Models** at 0 %, an agent on a Gemini model starts normally and only the Claude or GPT agents are blocked, redirected or moved to another model. **All models** touches every launch of the provider, which is how rules written before 2026-09-29 behave. To give each group its own fallback, write one rule per group: for example **Claude and GPT models** at 95 % runs its agents on Claude, **Gemini Models** at 95 % runs them on Codex.

Priority: rules apply in list order. At launch the first satisfied rule wins, whatever its action. From two rules each row shows **Priority N**; drag a row to reorder. Each row also has its enable switch, **Edit** and **Delete**.

## Settings

- `quotaRules` (global, edited from the **Quota rules** window): the array of rules, in priority order. Each rule holds a condition (provider, account, optional model group `pool`, window `any`, `session`, `daily`, `weekly` or `monthly`, comparator, percent, optional reset window and second condition) and an action (kind `block-launch`, `reroute-account`, `adjust-launch`, `run-trigger` or `switch-running`, launch scope, `launchModels` `pool` or `all`, target account, provider, model, effort, project, trigger, and for `adjust-launch` an optional `modelMap`: one row per source model family with its own target model and effort, the action's model and effort being the "Other models" default). Empty means no rule.
- `usageAlerts` (global, Settings > Notifications > **Usage alerts**): its channels (card in the app, desktop notification, phone) are the ones a rule uses to tell you it acted.

## Agent tools (MCP)

- `quota_rules_list`: every rule in priority order, with a one-line summary, plus the account ids each provider can target and the model groups known per provider (Antigravity `gemini` / `claude-gpt`, Cursor `included` / `auto` / `api`).
- `quota_rules_save`: create one rule, or change only the fields passed on an existing one (`ruleId`); `position` moves it in the priority order. Every field is checked (provider with a quota, model group, gauge, percent, account, required destination) and the rule is re-armed for its window, like an edit made in the editor. `condition.pool` picks a model group, `action.launchModels` (`pool` or `all`) the launches concerned, `action.modelMap` (adjust-launch) one target per source model family (`[{ source: "fable", targetModel: "gpt-6-astra", targetEffort: "xhigh" }, …]`, a row without target keeps that family on its provider, `null` removes the table).
- `quota_rules_delete`: remove one rule.
- `settings_get` / `settings_set` still read or rewrite the whole `quotaRules` array, without the checks.
- `usage_overview`: the per-account quota bars a rule reads; each bar carries the `pool` id a rule takes as `condition.pool` (null for a gauge of the whole account).

## Providers

Only providers that publish a quota can be watched: Claude, Codex, Grok, Kimi, Cursor, Antigravity and OpenCode (its plans OpenCode Go and Z.AI Coding Plan). Cursor and Antigravity have one gauge for the whole machine (the CLI's own sign-in), not one per account, so a rule can watch them but has no second account to move their agents to. The editor names the remaining CLIs ("… publishes no quota level: it cannot be watched."): they have no gauge, so no rule can react to them.

A block only concerns the provider of the condition: "Claude full" never blocks Codex launches; write two rules for both. **Redirect a launch** and **Move running agents** need another account of the same provider, so in practice Claude, Codex or Grok. To cascade between providers (Claude full, then Codex, then another), chain **Change provider, model or effort** rules in the order you want them tried.

## Mobile

Edited from the phone since 2026-09-24: Activity > **Usage** segment > **Quota management** card opens the full-screen rules list and editor (the desktop executes what the phone edits), including the **By source model** table since 2026-09-29. Since 2026-09-28 a **Quota rules** card in Settings > Usage lands on that same segment. The phone keeps its own form, section by section: the clickable diagram is on the desktop only, and both edit the same rules. An agent launched directly from the phone still does not go through the launch-time actions (block, redirect, change model).

## Limits

- The desktop app must be open: it reads the gauges and runs the actions.
- A rule acts once per quota window, then re-arms at the reset. Editing a rule re-arms it. With **Any gauge**, the rule reads the most constrained gauge that meets the threshold (including the several per-model weekly gauges some providers publish), and two independent gauges can each fire it once.
- The **Use another provider** template acts at launch only: agents already running stay on their CLI.
- A redirect or a model change applies to the launch only; nothing is written on the agent.
- A manual account pin on an agent stays above every rule.
- **Warn me** is no longer offered for new rules: notifications belong to [Usage Alerts](https://agentsroom.dev/docs/usage-limit-alerts.md). Older **Warn me** rules still work and stay editable.
- Precision is that of the usage scan, so an action starts shortly after the threshold, not at the exact second. Every gauge is read on Windows too: Grok, Cursor, Kimi and OpenCode through their usage API, Antigravity through `agy`, Kimi and Grok falling back to the usage terminal when their API gives nothing.
- Model groups: AgentsRoom tells which group a launch draws from by its model. Antigravity's own default model (no model picked) is a Gemini model, so it counts in **Gemini Models**. On Claude and Codex, a launch on the CLI's default model counts in every group, on the safe side. The Usage panel hides an Antigravity group still at 0 % everywhere, so a rule on that group shows **No reading yet** until the group is used.
- **Move running agents** always moves every agent running on the saturated account, whatever its model group.
- OpenCode: a rule can watch one plan (**OpenCode Go** or **Z.AI Coding Plan**) or **Most constrained**. At launch AgentsRoom does not know which plan the agent will use, so a block or model change set on one plan applies to every OpenCode launch.

## Common questions

- **A rule sent every launch away from Grok, then an agent started on Grok anyway although it was still at 100 %.** Fixed on 2026-09-27: when a gauge can no longer be read before its reset (the provider's sign-in expired because no agent ran), rules keep judging on the last reading until the reset time, since usage cannot go down before then. A gauge with no known reset time is not held.
- **The editor only shows three boxes, where are the fields?** Click one: the quota box, the threshold on the arrow and the action box each open their own panel. **Only near the reset** and **Second condition** are the **+** chips under the diagram. Nothing was removed on 2026-09-29, only put behind the part it belongs to.
- **Where did the account auto-switch toggle go?** It became quota rules on 2026-09-23. If it was on, AgentsRoom created two rules per provider with a spare account, "Keep working when an account runs out (Session)" and "(Week)", at 99 % with **Move running agents**. Edit, disable or delete them like any rule.
- **Can I watch Cursor or Antigravity?** Yes, since their gauge appeared in the Usage panel. It is one gauge per machine, so "move running agents" and "use another account" have no other account to pick for them.
- **Does a scheduled or team launch respect the rules?** Yes. A scheduled trigger is stopped before any agent starts. A trigger that runs a team is judged on the provider and account of the team's first agent, and every agent of that run keeps the run's origin (scheduled or webhook) for the **Which launches** scope; a blocked team run stops with "Quota rule "X": run stopped".
- **Two rules match, which one wins?** The higher one in the list. Drag to change the order.
- **Will a 90 % rule fire every ten minutes?** No, once per window.
- **What does "Any gauge" watch?** Every gauge of the chosen account (session, day, week, month, per-model weeks): the rule fires as soon as one of them reaches the threshold. Pick a single window when only one matters.
- **Where did the Pause scheduled agents template go?** It is no longer among the template cards; build the same rule with **New rule**, **Block a launch** and **Which launches** set to **Scheduled agents**.
- **Does "Claude full" block my Codex agents?** No, only launches of the watched provider.
- **When Claude overflows to Codex, can Fable go to GPT-6 Astra and Sonnet to GPT-6 Luna instead of one model for everything?** Yes, since 2026-09-29. In **Change provider, model or effort**, set **Target model** to **By source model**: one row per model of the watched provider (Fable, Opus, Sonnet, Haiku), each with its target model and reasoning effort on the fallback provider, pre-filled by capability tier (Fable to Astra, Opus to Sol, Sonnet to Luna). **Other models** is the default row, **Do not redirect** keeps a model on its provider, and a version alias such as Opus 5.5 follows the Opus row. **Same model for all** is the previous behaviour, and rules written before keep it.
- **Antigravity: my Claude and GPT gauge is full but Gemini still has room. Will a rule also reroute my Gemini agents?** Not with **Which models** set to **Those of the reached gauge** (the default of a new rule): only the agents on a Claude or GPT model are rerouted. Pick the group under **Model group** to give each group its own fallback. A rule written before 2026-09-29 keeps **All models** until you change it.

## Related

- [Account Auto-Switch](https://agentsroom.dev/docs/account-auto-switch.md): the **Move running agents** action and the account pool it uses.
- [Usage Alerts](https://agentsroom.dev/docs/usage-limit-alerts.md): notifications at a threshold, the channels a rule reuses.
- [Multiple Accounts](https://agentsroom.dev/docs/multi-account.md): the accounts a redirect or a switch chooses from.
- [Claude Code Token Usage](https://agentsroom.dev/docs/claude-code-token-usage.md): the Usage panel that hosts **Quota management**.
- [Scheduled Tasks](https://agentsroom.dev/docs/scheduled-tasks.md): the triggers a rule can block or run.
- [Webhook Triggers](https://agentsroom.dev/docs/webhook-triggers.md): the **Webhook calls** launch scope.