~/.ollim-bot/. The scheduler picks up changes every 10 seconds. No code changes required to add new instances.
Mechanisms
Routines
Recurring cron-scheduled prompts that define the bot’s daily rhythm.
Reminders
One-shot time-based nudges with optional follow-up chains.
Webhooks
External HTTP triggers with JSON Schema validation and prompt injection screening.
MCP tools
Agent-initiated actions within any session — embeds, pings, fork management.
Subagents
Specialized agents for delegated tasks like email triage and history review.
Interactive forks
User-initiated branched conversations for focused work.
Decision matrix
| Mechanism | Trigger | Recurrence | Session model | Best for |
|---|---|---|---|---|
| Routines | Cron schedule | Recurring | Background fork | Daily check-ins, weekly reviews, periodic monitoring |
| Reminders | Specific time | Once (chainable via follow_up_chain) | Background fork | Time-based nudges, progressive follow-up workflows |
| Webhooks | HTTP POST from external system | On-demand | Background fork | GitHub events, monitoring alerts, form submissions |
| MCP tools | Agent decision during conversation | Per-interaction | Current session | Structured embeds, user pings, fork management |
| Subagents | Delegated by main agent | Per-invocation | Background fork | Email triage, history review, responsiveness analysis |
| Interactive forks | /fork command or enter_fork tool | Per-session | Forked from main | Deep dives, research, tangents without context bloat |
Choosing between routines and reminders
Use routines when you want something to fire on a recurring schedule — every weekday at 9am, every Sunday evening. Routines persist until removed. Use reminders when you want a one-shot prompt at a specific time. For progressive workflows (e.g., “check if the user responded, then follow up”), setmax_chain and let the agent call follow_up_chain to schedule continuations.
Choosing between webhooks and routines
Both run as background forks. Use webhooks when the trigger comes from an external system (a GitHub push, a monitoring alert). Use routines when the trigger is time-based. Webhooks include 4-layer input security: JSON Schema validation, content fencing, Haiku screening of strings, and operational limits.Shared configuration
Routines, reminders, and webhooks all dispatch through the same background fork execution path (run_agent_background). They share these YAML frontmatter fields:
| Field | Type | Default | Description |
|---|---|---|---|
background | boolean | false | Run in a background fork instead of the main session (routines and reminders only — webhooks are always background) |
model | string | — | Override the default model (haiku, sonnet, opus) |
thinking | boolean | true | Enable extended thinking |
isolated | boolean | false | Run without main session history or fork state |
update_main_session | string | on_ping | always, on_ping, freely, or blocked — controls report_updates behavior |
allow_ping | boolean | true | Whether ping_user and discord_embed are available |
allowed_tools | list | — | Allowlist of tools — routines and reminders only (overrides defaults, mutually exclusive with disallowed_tools) |
disallowed_tools | list | — | Blocklist of tools — routines and reminders only (mutually exclusive with allowed_tools) |
Background fork execution
When a routine, reminder, or webhook fires withbackground: true, the scheduler:
- Creates a disposable forked session (or an isolated session if
isolated: true) - Injects a preamble with current ping budget, upcoming schedule, and refill timing
- Runs the prompt with the configured model and tool restrictions
- Discards the fork — text output is never shown directly
ping_user for plain text alerts, discord_embed for structured messages, and report_updates to queue a summary for the next main session interaction. If neither ping_user nor report_updates is called, the fork is silently discarded with zero context bloat.
Background forks run without holding the agent lock. When the user is mid-conversation, non-critical pings return errors and the agent falls back to
report_updates. Critical pings (critical: true) bypass all three checks — per-session limit, busy state, and ping budget. They are tracked in a separate critical_used daily counter but do not consume budget tokens.Next steps
MCP tools
Reference for all agent-initiated tools: discord_embed, ping_user, follow_up_chain, and more.
Subagents
How gmail-reader, history-reviewer, and responsiveness-reviewer work.
System prompt
How the system prompt is structured and what gets injected.
Adding integrations
How to add new Google services, MCP tools, or webhook specs.