max-chain set can spawn follow-ups via
the follow_up_chain MCP tool, letting the agent continue a task across
multiple steps.
Overview
A reminder tells ollim-bot to run a prompt at a specific future time. When created, you specify either a delay in minutes or an absolute time, and the scheduler computes when to fire. Like routines, reminders can run in the foreground (sending you a DM) or in the background (running silently in a fork). Reminders default to background mode. Reminders are stored as markdown files in~/.ollim-bot/reminders/. The
scheduler polls this directory every 10 seconds. After a reminder fires,
it is removed automatically (unless it chains into a follow-up).
The agent manages reminders through three MCP tools — add_reminder,
list_reminders, and cancel_reminder. You can also ask the agent in
natural conversation and it calls the right tool. After creating a
reminder, the agent confirms the scheduled time in one line (e.g.
“reminder set for 3:00 PM”).
File format
Each reminder is a.md file in ~/.ollim-bot/reminders/. The message
field is the markdown body after the closing ---; all other fields go
in the YAML frontmatter. Only non-default fields are written to the
frontmatter.
reminders/check-on-deployment.md
The
message field does not appear in the frontmatter — it is the
markdown body below the closing ---.Frontmatter fields
| Field | Type | Default | Description |
|---|---|---|---|
id | str | — | Auto-generated 8-char hex ID |
run-at | str | — | ISO datetime (computed from delay) |
description | str | "" | Short summary for reminder list |
background | bool | true | Run in a background fork |
chain-depth | int | 0 | Current position in a chain |
max-chain | int | 0 | Max follow-up depth (0 = plain one-shot) |
chain-parent | str | null | null | ID of the chain root |
model | str | null | Model override (background only) |
thinking | bool | true | Extended thinking (background only) |
isolated | bool | false | Fresh context, not forked (background only) |
update-main-session | str | "on_ping" | Sync mode: always / on_ping / freely / blocked |
allow-ping | bool | true | Allow pings and embeds (background only) |
allowed-tools | list[str] | null | Additional tools merged with default background tools (background only) |
skills | list[str] | null | Skills to load at fire time |
File naming
Filenames are slugified from the message text (lowercase, hyphens, max 50 characters). Theid field in the YAML frontmatter is authoritative
— filenames are for human readability only. Collisions append -2,
-3, etc.
Managing reminders
The agent uses three MCP tools to manage reminders. You interact through natural conversation — the agent picks the right tool.- “Remind me in 30 minutes to check on the deployment”
- “Set a reminder for 3pm to check my email”
- “What reminders do I have?”
- “Cancel the deployment reminder”
| Tool | What it does |
|---|---|
add_reminder | Schedule a reminder by delay (delay_minutes) or absolute time (run_at) |
list_reminders | Show all pending reminders with IDs, times, and descriptions |
cancel_reminder | Cancel a pending reminder by ID |
Follow-up chains
A plain reminder (max-chain: 0) fires once and is removed. A
chainable reminder (max-chain: N) can spawn follow-ups: when the
agent runs the reminder, it can call the follow_up_chain MCP tool to
schedule a continuation at chain-depth + 1.
Chains end when:
- The agent decides not to call
follow_up_chain(task complete, nothing to report) chain-depthreachesmax-chain— the agent receives an error with recovery guidance: “follow-up limit reached — this was the last check. If the task still needs attention, ping the user now.” (seefollow_up_chain)
Chain behavior
When a chain reminder fires, the agent is instructed to briefly acknowledge the follow-up nature in any pings — phrasing like “checking in again” or “follow-up on earlier” — so you know the notification is an intentional continuation, not a duplicate. On the final check (last link in the chain), the agent applies a regret heuristic: it pings only if the task is still unresolved and you would regret missing it. Otherwise, it reports findings to the main session viareport_updates. This prevents unnecessary
notifications at the end of a chain while still escalating when it
matters.
reminders/check-email-response.md
chain-parent and
increments chain-depth. Chain reminders also inherit tool restrictions and skills
from the parent.
Background vs foreground
By default, reminders run in the background — silently in a disposable fork. Text output is discarded — the agent must useping_user or discord_embed to reach you.
Set foreground: true when calling add_reminder (or background: false
in the YAML file) to run the reminder in the foreground instead. Use
foreground only when you want to watch the agent’s tool actions stream in
real time. For notifications, alerts, and nudges, background with
ping_user is the right choice — replying to a background ping starts an
interactive fork if you want to discuss the result.
- Background (default)
- Foreground
The reminder runs in a forked session. Background reminders support
additional configuration for model, thinking, isolation, and tool
restrictions.
reminders/check-deployment.md
Overdue reminders
When a reminder’s scheduled time has already passed by the time the scheduler processes it — for example, after a restart — the reminder fires immediately with an overdue signal injected into the prompt:Examples
Simple one-shot reminder (foreground)
reminders/take-a-break.md
Background monitoring with chain
reminders/wait-for-ci.md
Quiet background check (no pings)
reminders/inbox-scan.md
Next steps
Routines
Recurring cron-based schedules for daily and weekly prompts.
Background forks
Deep dive into background fork configuration and behavior.
Ping budget
How notification rate limiting works for background tasks.
Real-world examples
One-shot, future-dated, and chain reminder examples from
an actual data directory.