Decision matrix
| Mechanism | Trigger | Session model | Best for | Requires |
|---|---|---|---|---|
| Routines | Cron schedule | Background fork | Daily check-ins, weekly reviews, periodic monitoring | File |
| Reminders | Specific time | Background fork | Time-based nudges, progressive follow-up workflows | File |
| Webhooks | HTTP POST | Background fork | GitHub events, monitoring alerts, form submissions | File |
| Skills | Referenced by routine/reminder | Injected into host session | Reusable instruction sets, shared workflows | File |
| Subagents | Delegated by main agent | Background fork | Email triage, history review, responsiveness analysis | File |
| Interactive forks | /fork command or enter_fork tool | Forked from main | Deep dives, research, tangents without context bloat | — |
| MCP tools | Agent decision during conversation | Current session | Structured embeds, user pings, fork management | Code |
File-based mechanisms
Routines, reminders, webhooks, skills, and subagents are all markdown files with YAML frontmatter. The scheduler picks up routine, reminder, and webhook changes every 10 seconds. Subagent specs are installed to~/.ollim-bot/.claude/agents/ at startup and discovered by the SDK via setting_sources=["project"]. You can create any of these by talking to the bot, using the CLI, or writing files directly.
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.
Skills
Reusable instruction sets loaded into routines and reminders at fire time.
Subagents
Specialized agents for email triage, history review, and more.
Interactive forks
User-initiated branched conversations for focused work.
Code extension
Adding new MCP tools, Google services, or CLI commands requires modifying the Python source. Fork the repo, make your changes, and pull upstream updates when needed.Discord tools
Reference for all twelve built-in tools — embeds, pings, file sending, forks, reminders, and chains.
Adding integrations
How to add Google services, MCP tools, CLI commands, and webhook specs.
System prompt
How the system prompt is structured and what gets injected.
You can override a built-in subagent’s prompt without code changes — drop a
.md file with the same filename into ~/.ollim-bot/.claude/agents/. See Subagents for the spec format.Choosing a mechanism
Routines vs 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.
Webhooks vs 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.Skills vs system prompt customization
Use skills when you want a reusable set of instructions that multiple routines or reminders can reference — skills are loaded on demand, so they don’t bloat the system prompt. Use system prompt customization when the instructions should apply to every interaction, not just specific routines.Head-to-head comparisons
- Routines vs Reminders
- Webhooks vs Routines
- Skills vs System prompt
Both run as background forks, but they serve different timing needs.
Use routines for anything that repeats on a schedule. Use reminders for one-shot nudges — and set
| Aspect | Routines | Reminders |
|---|---|---|
| Trigger | Cron expression (recurring) | Specific datetime (one-shot) |
| Persistence | Fires forever until removed | Fires once, then done |
| Follow-up | Next occurrence is automatic | max-chain + follow_up_chain for progressive checks |
| Best for | Daily rhythms, weekly reviews, periodic monitoring | ”Remind me at 3pm”, deadline nudges, progressive follow-up workflows |
| Storage | ~/.ollim-bot/routines/<slug>.md | ~/.ollim-bot/reminders/<slug>.md |
max-chain when the agent should follow up if the first nudge wasn’t enough.Shared configuration
Routines, reminders, and webhooks share these YAML frontmatter fields for background execution:| Field | Type | Default | Description |
|---|---|---|---|
background | boolean | false (routines), true (reminders) | 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 (merged with default bg tools) |
skills | list | — | Skill names to load at fire time — routines and reminders only |
Next steps
Skills
Create reusable instruction sets for routines and reminders.
Subagents
How the five specialized subagents handle documentation, email, history, and more.
Discord tools
Reference for all agent-initiated tools: discord_embed, ping_user, follow_up_chain, and more.
File formats
Full YAML frontmatter specs for routines, reminders, webhooks, and skills.