Routines - ollim-bot

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.

routines/morning-task-review.md

---
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 to load at fire time
`reflect`	`bool`	`true`	Write a reflection trace 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 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 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

CLI
Agent

The ollim-bot routine subcommand manages routines from the terminal.Add a routine:

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>`	Model override
`--no-thinking`	Disable extended thinking
`--isolated`	Run with fresh context
`--update-main-session <mode>`	`always`, `on_ping`, `freely`, or `blocked`
`--no-ping`	Disable `ping_user` and `discord_embed`

List all routines:

ollim-bot routine list

Output:

  a1b2c3d4  [bg] cron '0 9 * * 1-5'    Morning task review
  e5f6a7b8  cron '0 20 * * *'            Evening wind-down

Cancel a routine:

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.

Foreground
Background

The routine fires and the agent sends you a DM with its response, like a normal conversation.

routines/evening-wind-down.md

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

routines/morning-task-review.md

---
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)

routines/morning-briefing.md

---
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)

routines/weekly-review.md

---
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)

routines/quiet-email-check.md

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

Reminders

One-shot and chainable reminders for non-recurring prompts.

Background forks

Deep dive into background fork configuration and behavior.

Ping budget

How notification rate limiting works for background routines.

Real-world examples

See how routines compose into a full daily rhythm with pipelines, chains, and conditional silence.

​Overview

​File format

​Frontmatter fields

​File naming

​Validation on write

​Managing routines

​Background vs foreground

​Cron expressions

​Examples

​Weekday morning briefing (background)

​Weekly review (foreground)

​Quiet background check (no pings)

​Next steps

Reminders

Background forks

Ping budget

Real-world examples

Overview

File format

Frontmatter fields

File naming

Validation on write

Managing routines

Background vs foreground

Cron expressions

Examples

Weekday morning briefing (background)

Weekly review (foreground)

Quiet background check (no pings)

Next steps