Giving styles
Choose how to give: a fixed amount, expiring credit, a share, everything spare with a ceiling, idle time or a boost, then preview it.
A giving style is the rule that decides when a source may give and how much. You pick one style per source, the worker works it out on your machine before each task, and a task never starts unless its worst-case cost fits within every limit that applies. The protections underneath every style cannot be switched off.
The styles
- A fixed amount (
fixed) - The default for API keys. Give up to a set amount per day, week or month, for example $5 a month. It is a hard ceiling, checked before every task, and it is not paced, so the amount can be given as soon as work is available. Set it with
--fixed 5and--period, or as a percentage of a budget with--fixed 10% --of 50. - Use up expiring credit (
expiring) - For promo or prepaid API credit with an end date. Tell it the balance, the date it expires and a floor to keep. The worker paces giving evenly from the day you set the balance to the end of the expiry day, so nothing is wasted and nothing arrives in a burst, and it stops at the floor. If you move the date earlier the pace speeds up on the next check.
--expiring 30 --by 2026-11-30 --floor 2. - A steady share (
share) - Give a percentage of a budget each period, spread evenly through the period.
--share 10% --of 100 --period monthgives up to $10 a month, no faster than the month passes. - Everything spare (
all) - Give whenever the source is free, down to a minimum keep-back that can never be lowered below 5%. An API key must have a ceiling (
--ceiling 20, per month unless you add--ceiling-period), so "everything" is always bounded. For a local model it behaves like idle time with no hours limit. - Idle time (
idle) - The default for local models. Run only when the machine has been idle for a while (10 minutes by default), is plugged in and is not hot, optionally only in certain hours (
--nightsis 22:00 to 07:00). It stops and releases the task the moment you are back. If the machine's idle, power or temperature state cannot be read, it does not run. - A one-off boost (
sparetokens boost) - "Give $5 now" or "run for the next 2 hours". A boost replaces the schedule and the style for a while, then expires by itself. It never replaces the protections, a keep-back or a ceiling.
sparetokens boost anthropic 5(valid 24 hours) orsparetokens boost mac 2h;--cancelends one early. - Only what would expire (
leftovers) - Give in the last hours before an allowance that resets (default 6 hours before the reset), always keeping a share back for yourself (default 15%). It needs a fresh reading of the remaining allowance and gives nothing without one. It is available only for a provider whose terms allow automated use of that allowance. Consumer subscription logins, such as Claude and ChatGPT plans, do not, so this style is not offered for them.
sparetokens giverefuses it and says why.
Tasks go to the source that suits them, so a source never wastes effort on work it fails.
Which style should I choose?
Start from what you have. You can change style any time with sparetokens give, and sparetokens preview shows the effect first.
| If you have | Choose | Why |
|---|---|---|
| An API key and no particular plan | fixed | The simplest and the default. A hard ceiling per day, week or month, checked before every task. |
| Promo or prepaid credit with an end date | expiring | Paced evenly to the date so nothing is wasted and nothing arrives in a burst. Early in the window there is little room, so a fixed amount can be easier for a first run. |
| A monthly budget and a wish to give a little of it | share | A steady percentage, spread through the period. |
| Plenty to spare and a clear upper limit | all with --ceiling | Gives whenever the source is free, down to a keep-back of at least 5%, never past the ceiling. |
| A Mac or Linux machine with a local model | idle | Runs only when the machine is idle, plugged in and cool, and stops the moment you return. Add --nights for 22:00 to 07:00. |
| A weekend you want to push | boost | "Give $5 now" or "run for 2 hours". It expires by itself and never replaces the protections. |
| A provider that allows automated use of a resetting allowance | leftovers | Gives in the last hours before a reset. Not offered for consumer subscription logins. |
New to all this? The API credit guide and the local model guide walk through the first rule and its preview step by step. Unfamiliar words are in the glossary.
Setting a style
Use sparetokens give. It writes the readable file rules.toml in your config directory, checks it, and says what it saved. A short name such as openai, anthropic, xai, openrouter or mac creates the source if it does not exist yet.
sparetokens give anthropic --fixed 5 --key-ref env:ANTHROPIC_API_KEY
sparetokens give promo --provider anthropic-api --expiring 30 --by 2026-11-30 --floor 2
sparetokens give xai --all --ceiling 20 --nights
sparetokens give mac --idle --nights
sparetokens boost anthropic 5
sparetokens preview promo
sparetokens status
The rules file
The same rules can be written by hand or by an agent. A key is only ever referenced by name (key_ref), never written into the file, and a value shaped like a key is refused.
# ~/.config/sparetokens/rules.toml
[source.work-api]
provider = "anthropic-api"
key_ref = "env:ANTHROPIC_API_KEY" # a name, never the key
style = "expiring"
balance_usd = 30
expires = "2026-11-30"
floor_usd = 2
[source.mac-ollama]
style = "idle"
idle_minutes = 10
hours = "22:00-07:00"
plugged_in_only = true
Settings by style:
- fixed:
amount_usd,amount_tokensoramount_pct(withbudget_usdorbudget_tokens), andperiod(day, week or month). - expiring:
balance_usd,expires(a date),floor_usd, and optionallybalance_as_of, the date the balance was true. Without it the worker remembers when it first saw the balance. - share:
share_pct,periodandbudget_usdorbudget_tokens. - all:
ceiling_usd(required for API keys),keep_back_pct(5 or more), optionallybalance_usdandfloor_usd. - idle:
idle_minutes,plugged_in_only. - leftovers:
window_hours,keep_back_pct,window. - any style:
hours(only between these local times),quiet_hours(never between these),ceiling_usdwithceiling_period, and the source settingsprovider,key_ref,enabled,model,per_task_usd,per_day_usd,per_task_tokens,per_day_tokens,max_turnsandtimeout_s.
Mistakes are reported with the source and the setting, for example "[source.xai]: everything spare on an API key needs a ceiling". A source defined in config.json can have its rules set in rules.toml under the same name; rules.toml wins.
How rules combine
Within one source, the strictest limit wins. The layers are checked in this order and the first one that says no gives the reason you see:
- The always-on protections.
- Your keep-back, ceilings and the floor of expiring credit.
- The schedule: hours and quiet hours.
- The style, which decides how much, inside all of the above.
For example, everything spare with a $20 monthly ceiling and nights only gives everything spare at night, up to $20.
Across sources, the worker spends what expires first. Sources are offered work in this order: capacity that disappears soonest (an allowance close to its reset, where a provider allows it), then expiring credit paced to its date (soonest date first), then free local capacity, then paid budgets.
Seeing what it will do
sparetokens status says in one plain sentence per source what will happen next and why, in the order work is offered, for example "Promo: ahead of the pace that uses this credit by its date (2026-11-30), next task in 1 h 48 min." or "Mac: giving runs 22:00-07:00, next start in 10 h 0 min." sparetokens status --json gives the same for agents: for each source its state (giving, waiting, stopped, paused, manual or off), will_run, sentence, reason, the layer that blocked it, next_change_in_s, headroom_usd and any boost.
Previewing a rule
sparetokens preview SOURCE simulates the last 7 days under the source's rule and prints what would have been given, what expired unused and what you kept. Your own usage is not recorded by the worker, so the preview runs on an example week and says so on the first line; it also shows what your local ledger recorded as actually given in the last 7 days. The example week is the same one the setup rule studio uses: weekday work hours heavy, evenings light, weekends light, nights quiet. Add --json for agents.
Defaults in setup
sparetokens setup offers a safe default for each kind of source, and pressing Enter keeps it:
- API keys: a fixed amount of $2 per week (alternative: $10 per month, or manual). Use
sparetokens giveto switch to expiring credit, a share or everything spare with a ceiling. - Local models: idle time, after 10 idle minutes and while plugged in.
API keys stay off unless you choose them, so pressing Enter all the way through spends nothing.
Choosing models
Per source, choose the best available, the cheapest that qualifies, or specific models. sparetokens config models NAME shows which task types each model unlocks and why it does not unlock the others. Best and cheapest are heuristics from tier and price ceiling, not benchmarks.
sparetokens config set-models work-api --mode best
The older rule types set with sparetokens config set-rule (fixed_budget, percentage, idle_only, use_it_or_lose_it) keep working.
How remaining capacity is counted
- Allowances that reset: only for a provider whose terms allow automated use. The reading must be fresh (under 30 minutes old) or nothing is given.
- API keys: there is no allowance. Your fixed amount, credit balance or ceiling is the limit.
- Local models: capacity is time, so the worker tracks wall-clock seconds and idle state.
Edit this page on GitHub: available when the repository opens.