Added timers module.

Command-Reference.md

@@ -34,3 +34,18 @@ For more information, see [Custom Commands](Custom-Commands).
 | `!listquotes` | | Send a link to the quotes list page. |
 
 For more information, see [Quotes](Quotes).
+
+## Timers
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `!addtimer` | | Create a new empty timer with an optional name. |
+| `!settimermessage` | | Set the message text for a timer. |
+| `!settimerinterval` | | Set the interval (simple duration or cron expression). |
+| `!settimerlines` | | Set minimum chat lines between firings. |
+| `!enabletimer` | | Enable a timer. |
+| `!disabletimer` | | Disable a timer. |
+| `!deletetimer` | | Permanently delete a timer. |
+| `!listtimers` | | Send a link to the timer list page. |
+
+For more information, see [Timers](Timers).

Home.md

@@ -6,6 +6,7 @@ Owlbot is a modular, event-driven toolkit for extending [Owncast](https://owncas
 
 - **[Custom commands](Custom-Commands)**: Moderators can create, edit, and delete chat commands at runtime without code changes or restarts. Responses support dynamic placeholders like `$(user)`, `$(count)`, `$(rand)`, `$(countdown)`, and positional arguments.
 - **[Quotes](Quotes)**: Codify the streamer's hot takes, wild claims, and memorable one-liners said live on air. Moderators add quotes, and anyone can recall them at random or look up a specific quote by ID.
+- **[Timers](Timers)**: Set up recurring chat messages that fire on a simple duration or cron schedule. An optional minimum chat line threshold keeps timers from firing into an empty chat.
 
 Owlbot's core is a framework for building and running modules. If the included modules don't cover your use case, you can write your own:
 

Timers.md

@@ -0,0 +1,124 @@
+# Timers
+
+The `timers` module lets moderators create recurring chat messages that fire on a configurable interval with an optional minimum chat activity threshold.
+
+This module is included with Owlbot and enabled by default.
+
+## Quick Start
+
+Create a timer, set its message and interval, then enable it:
+
+```
+!addtimer hydrate
+!settimermessage hydrate Remember to stay hydrated!
+!settimerinterval hydrate 30m
+!enabletimer hydrate
+```
+
+The bot will now send "Remember to stay hydrated!" every 30 minutes.
+
+## Commands
+
+| Command | Aliases | Usage | Permission | Description |
+|---------|---------|-------|------------|-------------|
+| `!addtimer` | | `!addtimer [name]` | Moderator | Create a new empty timer with an optional name. |
+| `!settimermessage` | | `!settimermessage <id\|name> <message>` | Moderator | Set the message text for a timer. |
+| `!settimerinterval` | | `!settimerinterval <id\|name> <interval>` | Moderator | Set the interval (simple duration or cron expression). |
+| `!settimerlines` | | `!settimerlines <id\|name> <count>` | Moderator | Set minimum chat lines between firings. 0 to disable. |
+| `!enabletimer` | | `!enabletimer <id\|name>` | Moderator | Enable a timer. |
+| `!disabletimer` | | `!disabletimer <id\|name>` | Moderator | Disable a timer. |
+| `!deletetimer` | | `!deletetimer <id\|name>` | Moderator | Permanently delete a timer. |
+| `!listtimers` | | `!listtimers` | Moderator | Send a link to the timer list web page. |
+
+## Timer Identification
+
+Every timer has a numeric ID assigned when it is created. Timers can also have an optional name (must start with a letter or underscore, followed by letters, numbers, or underscores, max 32 characters). All commands accept either the numeric ID or the name to identify a timer.
+
+## Intervals
+
+Timers support two types of intervals:
+
+### Simple Durations
+
+A single token combining hours, minutes, and/or seconds. Minimum interval is 30 seconds.
+
+| Example | Duration |
+|---------|----------|
+| `30s` | 30 seconds |
+| `5m` | 5 minutes |
+| `1h` | 1 hour |
+| `1h30m` | 1 hour 30 minutes |
+| `2h30m` | 2 hours 30 minutes |
+
+```
+!settimerinterval hydrate 15m
+```
+
+### Cron Expressions
+
+Standard 5-field cron expressions for precise scheduling. Minimum gap between firings is 1 minute. Uses the [croniter](https://github.com/kiorky/croniter) library for parsing.
+
+| Example | Schedule |
+|---------|----------|
+| `*/15 * * * *` | Every 15 minutes |
+| `0 * * * *` | Every hour on the hour |
+| `0 */2 * * *` | Every 2 hours |
+| `30 20 * * *` | Daily at 8:30 PM UTC |
+
+```
+!settimerinterval hydrate */15 * * * *
+```
+
+The interval type is auto-detected: values with spaces are parsed as cron, values without spaces are parsed as simple durations.
+
+## Minimum Chat Lines
+
+Timers can require a minimum number of chat messages between firings. This prevents timers from firing into an empty chat when no one is talking.
+
+```
+!settimerlines hydrate 5
+```
+
+With this setting, the hydrate timer will only fire if at least 5 chat messages have been sent since it last fired, even if the interval has elapsed. Set to 0 to disable the threshold:
+
+```
+!settimerlines hydrate 0
+```
+
+Bot messages and hidden messages (removed by moderation) are not counted toward the threshold.
+
+## Web UI
+
+The module serves a timer list page at `/owlbot/timers/list` showing all timers in a table with their ID, name, message, interval, minimum lines, status, and last fired time. The `!listtimers` command sends a link to this page in chat.
+
+## Examples
+
+```
+# Create a timer with a name
+!addtimer hydrate
+!settimermessage hydrate Remember to stay hydrated!
+!settimerinterval hydrate 30m
+!enabletimer hydrate
+
+# Create a timer without a name (uses ID)
+!addtimer
+!settimermessage 2 Follow us on social media!
+!settimerinterval 2 1h
+!settimerlines 2 10
+!enabletimer 2
+
+# Use a cron expression for precise scheduling
+!addtimer hourly_reminder
+!settimermessage hourly_reminder Check out our merch store!
+!settimerinterval hourly_reminder 0 * * * *
+!enabletimer hourly_reminder
+
+# Disable a timer
+!disabletimer hydrate
+
+# Delete a timer
+!deletetimer hydrate
+
+# View all timers on the web page
+!listtimers
+```

_Sidebar.md

@@ -8,6 +8,7 @@
 **Included Modules**
 * [Custom Commands](Custom-Commands)
 * [Quotes](Quotes)
+* [Timers](Timers)
 
 ---