> ## 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.

# Scheduling overview

> Proactive scheduling with routines and reminders — foreground, background, and how they differ.

ollim-bot doesn't wait to be asked. Its scheduling system runs
**routines** (recurring schedules) and **reminders** (one-shot or
chainable nudges) that fire automatically. Each one becomes an agent
prompt — the bot reads it, decides what to do, and optionally pings
you with findings.

Most routines and reminders run as
[background forks](/scheduling/background-forks) — disposable sessions
where the agent works silently and only reaches out when something
warrants attention, governed by a
[ping budget](/scheduling/ping-budget).

## Key features

<Columns cols={3}>
  <Card title="Routines" icon="rotate" href="/scheduling/routines">
    Recurring cron-based prompts that define the daily and weekly
    rhythm. Fire on schedule indefinitely.
  </Card>

  <Card title="Reminders" icon="bell" href="/scheduling/reminders">
    One-shot nudges that fire after a delay, then self-remove.
    Support follow-up chains via the agent.
  </Card>

  <Card title="Background forks" icon="code-branch" href="/scheduling/background-forks">
    Disposable sessions for routines and reminders. Text output
    is discarded — the agent pings or reports findings.
  </Card>

  <Card title="Ping budget" icon="gauge" href="/scheduling/ping-budget">
    Rate-limited ping budget that prevents background forks
    from over-pinging.
  </Card>

  <Card title="Forward schedule" icon="calendar-days" href="/scheduling/background-forks">
    Each background task sees upcoming tasks, budget status, and
    refill timing before deciding whether to ping.
  </Card>

  <Card title="Chain reminders" icon="link" href="/scheduling/reminders">
    Multi-step follow-ups where the agent schedules the next check.
    Chains end when the agent stops calling follow\_up\_chain.
  </Card>
</Columns>

<Note>
  Routines and reminders are markdown files with YAML frontmatter, stored
  in `~/.ollim-bot/routines/` and `~/.ollim-bot/reminders/`. The agent
  can create, edit, and remove these files directly — no CLI required.
  Changes are picked up within seconds, no restart needed.
</Note>

## Foreground vs background

Routines and reminders can run in two modes:

<Tabs>
  <Tab title="Foreground">
    The default for routines when `background` is not set or `false`.
    For reminders, foreground requires `foreground: true` via the `add_reminder` tool or `background: false` in the YAML file.
    The bot sends you a DM with the agent's response, just like a normal
    conversation.

    Foreground tasks pause interactive conversation while running.
    Use these for tasks that need your immediate attention or
    require back-and-forth.
  </Tab>

  <Tab title="Background">
    When `background: true` is set in the YAML frontmatter. The
    agent works silently in a disposable session. Its text output is
    discarded — it uses notifications or embeds to reach
    you, and can report findings back to the main session so the bot
    has context about what happened.

    Background tasks don't interrupt your conversation. They receive
    context about the ping budget status and upcoming schedule, so the
    agent can make informed decisions about whether to notify you or
    stay silent.

    See [Background forks](/scheduling/background-forks) for
    configuration options and [Context flow](/architecture/context-flow)
    for details on what context the agent receives.
  </Tab>
</Tabs>

## Routines vs reminders

|                | Routines                        | Reminders                         |
| -------------- | ------------------------------- | --------------------------------- |
| **Schedule**   | Cron expression (`0 9 * * 1-5`) | Specific date/time                |
| **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 via `add_reminder` MCP tool |
| **Background** | Optional (`background: true`)   | Default (`background: true`)      |

## Find what you need

| I want to...                                   | Go to                                            |
| ---------------------------------------------- | ------------------------------------------------ |
| Set up a recurring check-in or daily review    | [Routines](/scheduling/routines)                 |
| Set a one-shot nudge or follow-up chain        | [Reminders](/scheduling/reminders)               |
| Understand how background tasks run silently   | [Background forks](/scheduling/background-forks) |
| Control how often background tasks can ping me | [Ping budget](/scheduling/ping-budget)           |
| See annotated examples from a real setup       | [Real-world examples](/scheduling/examples)      |

## Next steps

<Columns cols={2}>
  <Card title="Routines" icon="rotate" href="/scheduling/routines">
    Cron syntax, YAML frontmatter fields, and routine examples.
  </Card>

  <Card title="Reminders" icon="bell" href="/scheduling/reminders">
    One-shot reminders, delay scheduling, and follow-up chains.
  </Card>

  <Card title="Background forks" icon="code-branch" href="/scheduling/background-forks">
    Isolated mode, model overrides, tool restrictions, and update
    modes.
  </Card>

  <Card title="Ping budget" icon="gauge" href="/scheduling/ping-budget">
    Refill-on-read bucket, capacity, refill rate, and critical
    bypass.
  </Card>

  <Card title="Real-world examples" icon="lightbulb" href="/scheduling/examples">
    Annotated routines and reminders from an actual data directory,
    with patterns for pipelines, chains, and behavioral design.
  </Card>
</Columns>