> ## 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.
# Extend ollim-bot
> When to use routines, reminders, webhooks, skills, MCP tools, or subagents.
ollim-bot has seven extensibility mechanisms. Most are **file-based** — markdown files with YAML frontmatter that the agent creates and manages directly. No code changes required. Adding new MCP tools, Google services, or CLI commands requires **forking the repo** and editing Python source.
## 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.
Recurring cron-scheduled prompts that define the bot's daily rhythm.
One-shot time-based nudges with optional follow-up chains.
External HTTP triggers with JSON Schema validation and prompt injection screening.
Reusable instruction sets loaded into routines and reminders at fire time.
Specialized agents for email triage, history review, and more.
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.
Reference for all twelve built-in tools — embeds, pings, file sending, forks, reminders, and chains.
How to add Google services, MCP tools, CLI commands, and webhook specs.
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](/extending/subagents#developer-reference) 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"), set `max-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](/development/system-prompt) when the instructions should apply to every interaction, not just specific routines.
### Head-to-head comparisons
Both run as background forks, but they serve different timing needs.
| 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/.md` | `~/.ollim-bot/reminders/.md` |
Use **routines** for anything that repeats on a schedule. Use **reminders** for one-shot nudges — and set `max-chain` when the agent should follow up if the first nudge wasn't enough.
Both run as background forks with the same configuration options, but the trigger source differs.
| Aspect | Webhooks | Routines |
| -------------- | -------------------------------------------------------------------------- | --------------------------------- |
| **Trigger** | HTTP POST from external system | Cron schedule (time-based) |
| **Input data** | JSON payload injected into prompt | No external input |
| **Security** | 4-layer: JSON Schema, content fencing, Haiku screening, operational limits | None needed (internal trigger) |
| **Auth** | Bearer token (constant-time comparison) | None |
| **Best for** | GitHub events, monitoring alerts, form submissions | Daily check-ins, periodic reviews |
| **Storage** | `~/.ollim-bot/webhooks/.md` | `~/.ollim-bot/routines/.md` |
Use **webhooks** when an external system should trigger the bot. Use **routines** when the trigger is purely time-based.
Both inject instructions into the agent's context, but at different times and scopes.
| Aspect | Skills | System prompt |
| --------------------- | --------------------------------------------------------- | -------------------------------------------- |
| **Loaded when** | At fire time, only for jobs that reference them | Every interaction |
| **Scope** | Per-routine/reminder (via `skills` YAML field) | Global — all sessions |
| **Dynamic context** | `` !`command` `` markers expand at fire time | Static text |
| **Tool dependencies** | `allowed-tools` in SKILL.md merged into job's tool set | N/A |
| **Context cost** | Only when loaded — zero cost for jobs that don't use them | Always present |
| **Best for** | Reusable instruction sets shared across multiple jobs | Instructions that apply to every interaction |
Use **skills** when instructions are specific to certain routines or reminders — they keep the system prompt lean. Use **system prompt customization** when the instructions should apply universally.
Not sure which mechanism fits? Describe what you want to the bot — it can look up its
own docs and recommend the right approach:
> "I want to get a nudge when I've been sitting for too long, but only during work hours,
> and it should back off if I just finished a workout. Check your docs and set it up."
## 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 |
Routines, reminders, webhooks, and skills are all markdown files with YAML frontmatter stored in `~/.ollim-bot/`. The agent can create and manage them directly using Glob, Read, Write, and Edit tools — no CLI required.
## Next steps
Create reusable instruction sets for routines and reminders.
How the five specialized subagents handle documentation, email, history, and more.
Reference for all agent-initiated tools: discord\_embed, ping\_user, follow\_up\_chain, and more.
Full YAML frontmatter specs for routines, reminders, webhooks, and skills.