~/.ollim-bot/routines/ and ~/.ollim-bot/reminders/. The agent
can create, edit, and remove these files directly — no CLI required.
A scheduler polls both directories every 10 seconds, registering new
jobs and pruning stale ones.
Most scheduled tasks run as
background forks — disposable sessions
where the agent works silently and only reaches out when something
warrants attention, governed by a
ping budget.
Key features
Routines
Recurring cron-based prompts that define the daily and weekly
rhythm. Fire on schedule indefinitely.
Reminders
One-shot nudges that fire after a delay, then self-remove.
Support follow-up chains via the agent.
Background forks
Disposable sessions for scheduled tasks. Text output is
discarded — the agent pings or reports findings.
Ping budget
Rate-limited ping budget that prevents scheduled tasks
from over-pinging.
Forward schedule
Each background task sees upcoming tasks, budget status, and
refill timing before deciding whether to ping.
Chain reminders
Multi-step follow-ups where the agent schedules the next check.
Chains end when the agent stops calling follow_up_chain.
How it works
The scheduler is powered by APScheduler (AsyncIOScheduler) running in the configured timezone (OLLIM_TIMEZONE, defaults to system local).
It starts in on_ready alongside the Discord client.
Polling loop
A sync job runs every 10 seconds and:- Reads all
.mdfiles from~/.ollim-bot/routines/and~/.ollim-bot/reminders/ - Registers new APScheduler jobs for any files not yet tracked
- Removes jobs for files that have been deleted
CronTrigger (fires on schedule, persists
indefinitely). Reminders get a DateTrigger (fires once at the
specified time, then the file is removed).
Foreground vs background
Scheduled tasks can run in two modes:- Foreground
- Background
The default when
background is not set or false. The
scheduler calls send_agent_dm, which acquires the agent lock
and sends the prompt directly to the main session. The response
streams to your DM.Foreground tasks block interactive conversation while running.
Use these for tasks that need your immediate attention or
require back-and-forth.Prompt tags: [routine:ID] or [reminder:ID]BG preamble
Every background task receives a preamble injected before its prompt. The preamble includes:| Section | Content |
|---|---|
| Ping instructions | Available tools based on allow_ping |
| Update mode | report_updates behavior per update_main_session |
| Busy state | Non-critical pings suppressed mid-conversation |
| Ping budget | Remaining pings and refill timing |
| Forward schedule | Upcoming bg tasks (3h window or 3+ tasks) |
| Tool restrictions | allowed_tools / disallowed_tools constraints |
Fork timeout
A separate job runs every 60 seconds to check interactive fork idle time. If a fork has been idle past its timeout, the agent is prompted to exit — either by saving context back, reporting updates, or discarding the fork. A second warning escalates to a mandatory exit.Routines vs reminders
| Routines | Reminders | |
|---|---|---|
| Schedule | Cron expression (0 9 * * 1-5) | ISO datetime |
| Recurrence | Fires indefinitely | Fires once, self-removes |
| Chaining | No | max_chain enables follow-ups |
| Storage | routines/<slug>.md | reminders/<slug>.md |
| Created by | Agent or ollim-bot routine | Agent or ollim-bot reminder |
| Background | Optional (background: true) | Optional (background: true) |
model, thinking,
isolated, update_main_session, allow_ping, allowed_tools,
and disallowed_tools.
Next steps
Routines
Cron syntax, YAML frontmatter fields, and routine examples.
Reminders
One-shot reminders, delay scheduling, and follow-up chains.
Background forks
Isolated mode, model overrides, tool restrictions, and update
modes.
Ping budget
Refill-on-read bucket, capacity, refill rate, and critical
bypass.
Real-world examples
Annotated routines and reminders from an actual data directory,
with patterns for pipelines, chains, and behavioral design.