Skip to main content
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.
SettingDefaultDescription
capacity5Maximum tokens the budget can hold
refill_rate90 minTime 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 for details on the context background forks receive.

​
/ping-budget command

View or configure the ping budget from Discord. 
/ping-budget
Returns the current budget status. Example output:
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)

​
Next steps

Background forks

How background forks run and when the budget applies.

Discord tools

Reference for ping_user, discord_embed, and report_updates.

Scheduling overview

How routines and reminders trigger background forks.

Real-world examples

See how routines use conditional silence and budget-aware patterns in practice.