ii-irc

# ii-IRC: Event-Driven IRC for AI Agents

ii writes all channel activity to plain files. A watcher script monitors for mentions and triggers OpenClaw system events. Responses are sent by writing to a FIFO.

## Architecture

```
~/irc/
├── irc.sh              # Management script (start/stop/status/send)
├── watch-daemon.sh     # Mention watcher → openclaw system event
└── <server>/
    └── <channel>/
        ├── in          # FIFO - write here to send messages
        └── out         # Append-only log of all channel messages
```

## Quick Setup

### 1. Install ii

ii is in most package managers. On Arch: `pacman -S ii`. On Debian/Ubuntu: `apt install ii`. Or build from [suckless.org](https://tools.suckless.org/ii/).

### 2. Create scripts

Run the bundled setup script (creates `~/irc/irc.sh` and `~/irc/watch-daemon.sh`):

```bash
bash scripts/setup.sh --server irc.example.org --port 6667 --nick MyBot --channel "#mychannel"
```

Or create them manually — see `scripts/irc.sh.template` and `scripts/watch-daemon.sh.template`.

### 3. Create systemd user services (recommended)

For auto-start on boot:

```bash
mkdir -p ~/.config/systemd/user

# IRC connection service
cat > ~/.config/systemd/user/irc-bot.service << 'EOF'
[Unit]
Description=IRC connection (ii)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/ii -s SERVER -p PORT -n NICK -i %h/irc
ExecStartPost=/bin/bash -c 'sleep 3 && echo "/j CHANNEL" > %h/irc/SERVER/in'
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF

# Mention watcher service
cat > ~/.config/systemd/user/irc-watcher.service << 'EOF'
[Unit]
Description=IRC mention watcher
After=irc-bot.service
Wants=irc-bot.service

[Service]
Type=simple
ExecStart=%h/irc/watch-daemon.sh
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF

# Replace SERVER, PORT, NICK, CHANNEL in the service files, then:
systemctl --user daemon-reload
systemctl --user enable --now irc-bot.service irc-watche...