osterman
Channel moderation bot. Manages bans, kicks, mutes, auto-modes, content filters, and idle tracking.
Dependencies
No external libraries required.
Plugins
| File | Role |
|---|
protect.py | Setup, passive protection: flood, caps, repeat, badword, clone, join flood |
commands.py | All user-facing moderation and config commands |
tracking.py | SQLite event log, greeting, !seen, !info, !log |
idle.py | Idle detection tick, !afk, !idle |
help.py | Three-level help system |
Message routing
| Output type | Delivery |
|---|
!seen, !idle <nick> results | Channel message |
!info, !log results | PM to nick |
!ban list, !config, !filter list, !badword list | PM to nick |
| All other command feedback (errors, confirmations) | IRC NOTICE to nick |
| Greetings, idle warns, bad word warn | IRC NOTICE to nick |
Help system
!help list topics
!help <topic> list commands for a topic
!help <topic> <cmd> description and usage for a command
!help <cmd> description and usage (topic not required)
Topics: mod, config, track, idle, admin
Commands
Moderation (owner / ACL / op)
| Command | Short | Description |
|---|
!kick <nick> [reason] | !k | Kick |
| `!ban <nick\ | mask> [reason]` | !b | Ban + kick |
!ban list | !b list | View channel ban list (PM) |
| `!bankick <nick\ | mask> [reason]` | !bk | Ban + kick (explicit) |
| `!unban <nick\ | mask>` | !ub | Remove ban |
| `!tempban <nick\ | mask> <min> [reason]` | !tb | Timed ban (auto-lifts) |
| `!mute <nick\ | mask>` | !mu | Quiet (+q) |
| `!unmute <nick\ | mask>` | !umu | Unquiet (-q) |
!voice <nick> | !v | Give voice (+v) |
!devoice <nick> | !dv | Remove voice |
!op <nick> | !o | Give op (+o) |
!deop <nick> | !do | Remove op |
!halfop <nick> | !hop | Give halfop (+h) |
!dehalfop <nick> | !dhop | Remove halfop |
| `!lock [m\ | i]` | !lk | Lock channel (+mi, +m, or +i) |
| `!unlock [m\ | i]` | !ulk | Unlock channel |
Auto-modes (owner / ACL / op, per channel)
| Command | Short | Description |
|---|
| `!autoop <add\ | del\ | list> [nick\ | mask]` | !ao | Auto +o on join |
| `!autovoice <add\ | del\ | list> [nick\ | mask]` | !av | Auto +v on join |
| `!autohalfop <add\ | del\ | list> [nick\ | mask]` | !ahop | Auto +h on join |
Config / lists (owner / ACL)
| Command | Short | Description |
|---|
| `!blacklist <add\ | del\ | list> [mask]` | !bl | Global ban list (all channels) |
| `!whitelist <add\ | del\ | list> [mask]` | !wl | Global bypass list |
| `!except <add\ | del\ | list> [mask]` | !ex | Per-channel bypass list |
| `!acl <add\ | del\ | list> [nick]` | (none) | Trusted nicks (can use mod commands) |
| `!filter <add\ | del\ | list> [pattern]` | !f | Per-channel regex content filter |
| `!badword <add\ | del\ | list> [word]` | !bw | Per-channel word block list |
!set <key> <value> | !s | Set a config value (in channel: per-channel; in PM: global) |
!config [#channel] | !cfg | Show channel config (PM) |
| `!idle <on\ | off>` | !id | Toggle idle detection |
Tracking
| Command | Auth | Description |
|---|
!seen <nick> | anyone | Last time nick was seen in this channel. Responds in channel. Owner/ACL may call from PM for cross-channel lookup. |
!info <nick> | anyone | Nick summary scoped to this channel (PM). Owner/ACL may call from PM for global lookup. |
!idle <nick> | anyone | How long nick has been idle in this channel. Responds in channel. |
!log <nick> [n] | owner / ACL | Full event log for nick (PM) |
!afk | anyone | Reset your idle timer |
Admin (owner)
| Command | Short | Description |
|---|
!join <#channel> | !j | Join a channel |
!part [#channel] | !p | Leave a channel |
!chans | !c | List channels |
Configurable settings (!set <key> <value>)
| Key | Default | Description |
|---|
flood_threshold | 5 | Messages before flood action |
flood_window_sec | 10 | Flood detection window (seconds) |
caps_filter | 1 | Enable caps filter (0/1) |
caps_percent | 70 | Caps percentage threshold |
caps_min_len | 10 | Minimum message length to check |
repeat_filter | 1 | Enable repeat filter (0/1) |
repeat_threshold | 3 | Repeated messages before action |
repeat_window_sec | 30 | Repeat detection window (seconds) |
clone_limit | 2 | Max connections from same host |
join_flood_filter | 1 | Enable join flood filter (0/1) |
join_flood_count | 5 | Joins before action |
join_flood_window | 10 | Join flood window (seconds) |
nick_flood_filter | 1 | Enable nick flood filter (0/1) |
nick_flood_count | 3 | Nick changes before action |
nick_flood_window | 60 | Nick flood window (seconds) |
badword_action | kick | Action on badword: kick or warn |
tempban_max_min | 60 | Max duration for !tempban (minutes) |
idle_warn_min | 45 | Minutes idle before warning |
idle_kick_min | 60 | Minutes idle before kick |
log_limit | 6 | Default number of events shown by !log |
greet | 1 | Send join greeting (0/1) |
Config keys
| Key | Description |
|---|
[osterman] db_path | Path to JSON database file |