# irc-bots

A collection of [Sopel](https://sopel.chat/) IRC bots for self-hosted servers.

| Bot | Purpose | Doc |
|-----|---------|-----|
| [alfred](alfred/) | Server management, bot control, file hosting, soju bouncer | [docs/alfred.md](docs/alfred.md) |
| [osterman](osterman/) | Channel moderation, auto-modes, idle tracking | [docs/osterman.md](docs/osterman.md) |
| [daffy](daffy/) | Duck hunting game | [docs/daffy.md](docs/daffy.md) |
| [contessa](contessa/) | Recipe suggestions | [docs/contessa.md](docs/contessa.md) |
| [shireen](shireen/) | News headlines and weather | [docs/shireen.md](docs/shireen.md) |
| [daft](daft/) | YouTube playlist manager | [docs/daft.md](docs/daft.md) |
| [herald](herald/) | Owner-follow bot and keyword responder | [docs/herald.md](docs/herald.md) |
| [salvador](salvador/) | Image-to-mIRC-art renderer | [docs/salvador.md](docs/salvador.md) |

## Requirements

- Python 3.9+
- [Sopel](https://sopel.chat/) 8.x

```
pip install sopel
```

Bot-specific dependencies:

| Bot | Extra |
|-----|-------|
| alfred | `pip install requests` |
| salvador | `pip install Pillow` |

All others use only the standard library.

## Install

1. Clone or copy this repo.

2. Copy the example config for the bot you want and fill in your details:
   ```
   cp alfred/alfred.cfg ~/.config/sopel/alfred.cfg
   $EDITOR ~/.config/sopel/alfred.cfg
   ```
   Set `nick`, `host`, `port`, `owner`, and any `[section]` paths.
   The `extra` key must point to the bot's directory (e.g. `/path/to/irc-bots/alfred`).

3. Create any required data directories:
   ```
   mkdir -p /var/log/<botname>
   # contessa: place recipes.json at the path set in [contessa] recipes_path
   # shireen:  data.json is created automatically on first run
   # osterman: db.json and track.db are created automatically on first run
   # daffy:    scores.db is created automatically on first run
   ```

4. Start the bot:
   ```
   sopel --config ~/.config/sopel/<botname>.cfg
   ```

5. (Optional) Register as a service. Example OpenRC init script:
   ```sh
   #!/sbin/openrc-run
   supervisor=supervise-daemon
   command="/usr/bin/sopel"
   command_args="--config /home/user/.config/sopel/<botname>.cfg"
   command_user="user"
   output_log="/var/log/<botname>/daemon.log"
   error_log="/var/log/<botname>/daemon.log"
   depend() { need net; }
   ```

## Notes

- All bots use `!` as the command prefix by default (set `prefix` in config).
- All bots share `!join`, `!part`, `!chans`, and `!help` as owner-only admin commands.
  When multiple bots are in the same channel and the owner types one of these, all bots act - that's intentional.
- **osterman** uses short-form aliases (`!b`, `!k`, `!v`, etc.) that are unique to it.
  No other bot in this collection uses conflicting short forms.

## License

MIT - see [LICENSE](LICENSE).