> ## 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. # Routines > Create recurring cron-scheduled prompts that define the bot's daily rhythm. Routines are recurring cron-scheduled prompts that define the bot's daily and weekly rhythm. Each routine is a markdown file with YAML frontmatter, stored in `~/.ollim-bot/routines/`. The scheduler picks them up automatically and fires them on their cron schedule. ## Overview A routine tells ollim-bot to run a prompt on a recurring schedule. Routines can run in the foreground (sending a DM) or in the background (running silently in a background fork, only notifying you when the agent decides to). The agent also has direct file access to create and edit routines itself. The scheduler polls the routines directory every 10 seconds, so changes take effect almost immediately — no restart required. ## File format Each routine is a `.md` file in `~/.ollim-bot/routines/`. 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. ```yaml title="routines/morning-task-review.md" theme={null} --- id: "a1b2c3d4" cron: "0 9 * * 1-5" description: "Morning task review" background: true --- Review my Google Tasks and Calendar for today. Summarize what's on my plate and flag anything urgent. ``` 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 | | `cron` | `str` | — | 5-field cron expression | | `description` | `str` | `""` | Short summary for `routine list` | | `background` | `bool` | `false` | Run in a background fork | | `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](/extending/skills) to load at fire time | | `reflect` | `bool` | `true` | Write a [reflection trace](/scheduling/background-forks#reflections) when the background fork finishes (background only) | ### File naming Filenames are slugified from the message text (lowercase, hyphens, max 50 characters). The `id` field in the YAML frontmatter is authoritative — filenames are for human readability only. Collisions append `-2`, `-3`, etc. ### Validation on write Routine writes and edits pass through the [`routine_validator` hook](/extending/hooks#routine-validator) before landing on disk. It blocks files missing `id`, `cron`, or valid frontmatter, and warns on unscoped tool permissions or dangerous delegation/write combinations. For quality issues the validator can't catch — a routine that pings at bad times, reports inaccurate data, or relies on conversation history as ground truth — invoke the bundled [`/improve-routine`](/extending/skills#bundled-skills) skill. It diagnoses failures in plan mode, proposes fixes grounded in the source, and verifies the changes with critic subagents before signing off. ## Managing routines The `ollim-bot routine` subcommand manages routines from the terminal. **Add a routine:** ```bash theme={null} ollim-bot routine add \ --message "Review my Google Tasks and flag overdue items" \ --cron "0 9 * * 1-5" \ --description "Morning task review" \ --background ``` Additional flags for background routines: | Flag | Description | | ------------------------------ | ------------------------------------------- | | `--model ` | Model override | | `--no-thinking` | Disable extended thinking | | `--isolated` | Run with fresh context | | `--update-main-session ` | `always`, `on_ping`, `freely`, or `blocked` | | `--no-ping` | Disable `ping_user` and `discord_embed` | **List all routines:** ```bash theme={null} ollim-bot routine list ``` Output: ```text theme={null} a1b2c3d4 [bg] cron '0 9 * * 1-5' Morning task review e5f6a7b8 cron '0 20 * * *' Evening wind-down ``` **Cancel a routine:** ```bash theme={null} ollim-bot routine cancel a1b2c3d4 ``` The agent has direct file access to `~/.ollim-bot/routines/` and can create, edit, or delete routine files. You can ask the agent in conversation: * "Set up a morning routine that checks my calendar at 9am" * "Change my daily review to run at 8:30 instead" * "Delete the weekend check-in routine" The agent writes the markdown file directly. Changes are picked up by the scheduler within 10 seconds. ## Background vs foreground By default, routines run in the **foreground** — the agent sends you a DM when the routine fires, running the prompt in the main session context. Set `background: true` to run the routine silently in a background fork. Text output is discarded — the agent must use `ping_user` or `discord_embed` to reach you. The routine fires and the agent sends you a DM with its response, like a normal conversation. ```yaml title="routines/evening-wind-down.md" theme={null} --- id: "e5f6a7b8" cron: "0 20 * * *" description: "Evening wind-down" --- What did I accomplish today? Anything I should move to tomorrow? ``` The routine runs in a forked session. Background routines support additional configuration for model, thinking, isolation, and tool restrictions. ```yaml title="routines/morning-task-review.md" theme={null} --- id: "a1b2c3d4" cron: "0 9 * * 1-5" description: "Morning task review" background: true isolated: true model: "haiku" --- Review my Google Tasks and Calendar for today. Summarize what's on my plate and flag anything urgent. ``` Use `isolated: true` for routines that don't need the main session's conversation history, like email triage or calendar summaries. This keeps the fork lightweight. ## Cron expressions Routines use standard 5-field cron syntax: `minute hour day month weekday`. Day-of-week uses `0` for Sunday. | Expression | Schedule | | ---------------- | ------------------------------- | | `0 9 * * 1-5` | 9:00 AM, Monday through Friday | | `0 20 * * *` | 8:00 PM, every day | | `30 8 * * 1` | 8:30 AM every Monday | | `0 */4 * * *` | Every 4 hours | | `0 9,13 * * 1-5` | 9:00 AM and 1:00 PM on weekdays | The CLI validates that cron expressions contain exactly 5 fields. ## Examples ### Weekday morning briefing (background) ```yaml title="routines/morning-briefing.md" theme={null} --- id: "c3d4e5f6" cron: "0 9 * * 1-5" description: "Morning briefing" background: true isolated: true --- Check my Google Calendar and Tasks for today. Send me an embed summarizing my schedule and any overdue tasks. ``` ### Weekly review (foreground) ```yaml title="routines/weekly-review.md" theme={null} --- id: "f7a8b9c0" cron: "0 18 * * 5" description: "Friday weekly review" --- Let's do a weekly review. What did I accomplish this week? What's carrying over to next week? ``` ### Quiet background check (no pings) ```yaml title="routines/quiet-email-check.md" theme={null} --- id: "d1e2f3a4" cron: "0 */3 * * *" description: "Email check" background: true isolated: true allow-ping: false allowed-tools: - "Bash(ollim-bot gmail *)" update-main-session: "always" --- Check for new important emails. Save a summary to pending updates. ``` ## Next steps One-shot and chainable reminders for non-recurring prompts. Deep dive into background fork configuration and behavior. How notification rate limiting works for background routines. See how routines compose into a full daily rhythm with pipelines, chains, and conditional silence.