> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Ping budget
> Control how often background forks can notify you with a budget that refills over time.
Background forks run autonomously, but unchecked notifications would
defeat the purpose of an ADHD-friendly bot. The ping budget limits
how many times background forks can ping you, with tokens that refill
over time — so proactive features stay helpful without becoming noisy.
## Overview
The ping budget applies **only to background forks**. Messages sent in
the main session or interactive forks are user-initiated and never
counted against the budget.
When a background fork calls `ping_user` or `discord_embed`, the budget
is checked first. If tokens are available, one is consumed and the
message goes through. If the budget is exhausted, the tool returns an
error to the agent (you are not notified) suggesting it use
`report_updates` to pass findings to the main session instead.
The budget file at `~/.ollim-bot/state/ping_budget.json` is ephemeral
state — it is written atomically but never committed to git.
## How the budget works
The ping budget holds a set number of tokens. Each non-critical
notification from a background fork consumes one token. Tokens refill
gradually over time — not on a timer, but calculated from elapsed time
whenever the budget is checked.
| Setting | Default | Description |
| ------------- | -------- | ---------------------------------- |
| `capacity` | `5` | Maximum tokens the budget can hold |
| `refill_rate` | `90` min | Time to regenerate one token |
With the defaults, up to 5 pings can fire in quick succession, then
one more becomes available every 90 minutes, capped at the capacity.
Daily usage counters (normal and critical) reset at midnight in your
**configured timezone** (`OLLIM_TIMEZONE`). If no timezone is set, the
system's local timezone is used.
## Critical bypass
Both `ping_user` and `discord_embed` accept a `critical` parameter.
When `critical=True`:
* The ping **bypasses all three checks** — per-session limit, busy
state, and ping budget. It is never blocked (unless `allow-ping`
is `false`).
* The `critical_used` daily counter is incremented for tracking, but
no budget token is consumed.
The agent is instructed to reserve `critical=True` for things you
would be devastated to miss — time-sensitive deadlines, health
routines, urgent accountability nudges.
The `allow-ping: false` setting on a background fork overrides
everything, including `critical=True`. When a fork author disables
pings, that intent is respected unconditionally.
## Quiet when busy
When you're mid-conversation, background forks automatically go quiet:
* **Non-critical** notifications are blocked — the agent reports
findings to the main session instead
* **Critical** notifications go through regardless
* Background forks still run on schedule; only their output delivery
is affected
A notification can be blocked for three reasons: the background fork
already sent one (each fork is limited to 1), you're mid-conversation,
or the budget is empty. A blocked notification does not consume a
budget token.
## How the agent decides
Each background fork sees the current budget status, upcoming
schedule, and refill timing before deciding whether to notify you.
The agent follows these guidelines:
* Send at most 1 notification per background fork
* Ask "would the user regret missing this?" before pinging
* Report to the main session for informational summaries and low-stakes check-ins
* Save pings for time-sensitive actions, accountability nudges, and health routines
* When budget is tight, prioritize tasks you would regret missing
The preamble shows a compact budget summary — `budget: 3/5 (next
refill in 42 min)` — alongside the forward schedule and refill
estimates. This gives the agent enough information to decide whether
spending a token now is worth it or whether a higher-priority task
fires soon.
See [Context flow](/architecture/context-flow) for details on the
context background forks receive.
## `/ping-budget` command
View or configure the ping budget from Discord.
```text theme={null}
/ping-budget
```
Returns the current budget status. Example output:
```text theme={null}
budget: 3/5 (next refill in 42 min). used today: 2. critical bypasses: 1 (urgent overrides, not deducted from budget).
```
The output includes:
* Available and total capacity
* Time until next refill (when below capacity)
* Daily usage count (when non-zero)
* Critical bypass count with an explanation that these are urgent
overrides not deducted from the regular budget (when non-zero)
```text theme={null}
/ping-budget capacity:8 refill_rate:60
```
| Parameter | Type | Description |
| ------------- | ------- | ---------------------------------- |
| `capacity` | integer | Maximum tokens the budget can hold |
| `refill_rate` | integer | Minutes per token refill |
Both parameters are optional. Omit both to view the current status.
## Next steps
How background forks run and when the budget applies.
Reference for `ping_user`, `discord_embed`, and `report_updates`.
How routines and reminders trigger background forks.
See how routines use conditional silence and budget-aware
patterns in practice.