> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# IRC Channel

> Classic IRC protocol with TLS support

The IRC channel connects NullClaw to IRC servers using the classic IRC protocol with optional TLS encryption.

## Features

* TLS/SSL support for secure connections
* SASL PLAIN authentication
* NickServ identification
* Multi-channel support
* Nick collision handling
* Allowlist-based access control
* Plain text output (no markdown)
* Channel and DM support

## Configuration

Add IRC to your `config.json`:

```json theme={null}
{
  "channels": {
    "irc": {
      "accounts": {
        "main": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "nullclaw_bot",
          "username": "nullclaw",
          "channels": ["#bots", "#nullclaw"],
          "allow_from": ["alice", "bob"],
          "tls": true,
          "server_password": null,
          "nickserv_password": null,
          "sasl_password": null
        }
      }
    }
  }
}
```

### Configuration Options

<ParamField path="host" type="string" required>
  IRC server hostname (e.g., `irc.libera.chat`, `irc.oftc.net`)
</ParamField>

<ParamField path="port" type="integer" required>
  IRC server port. Common values:

  * `6697` — TLS/SSL (recommended)
  * `6667` — Plain text
  * `7000` — Alternative TLS port
</ParamField>

<ParamField path="nick" type="string" required>
  Bot's nickname. If taken, NullClaw appends `_` automatically.
</ParamField>

<ParamField path="username" type="string" default="nick">
  IRC username (ident). Defaults to nickname if not specified.
</ParamField>

<ParamField path="channels" type="string[]" required>
  List of channels to join (e.g., `["#bots", "#general"]`). Must include `#` prefix.
</ParamField>

<ParamField path="allow_from" type="string[]" default="[]">
  List of allowed IRC nicks. Empty list = deny all. Use `"*"` to allow everyone (not recommended).

  Case-insensitive matching.
</ParamField>

<ParamField path="tls" type="boolean" default="true">
  Enable TLS/SSL encryption. Highly recommended for security.
</ParamField>

<ParamField path="server_password" type="string" default="null">
  Server password (sent with PASS command). Required by some servers.
</ParamField>

<ParamField path="nickserv_password" type="string" default="null">
  NickServ identification password. Used to authenticate registered nicks.
</ParamField>

<ParamField path="sasl_password" type="string" default="null">
  SASL PLAIN authentication password. More secure than NickServ for supported servers.
</ParamField>

<ParamField path="account_id" type="string" default="default">
  Account identifier for multi-account setups
</ParamField>

## Setup Guide

<Steps>
  <Step title="Choose an IRC Server">
    Popular IRC networks:

    * **Libera.Chat** (`irc.libera.chat:6697`) — FOSS projects
    * **OFTC** (`irc.oftc.net:6697`) — Community support
    * **EFnet** (`irc.efnet.org:6697`) — Original IRC network
    * **Rizon** (`irc.rizon.net:6697`) — Anime/gaming communities
  </Step>

  <Step title="Register Your Nickname (Optional)">
    Connect with an IRC client and register:

    ```
    /msg NickServ REGISTER <password> <email>
    /msg NickServ VERIFY REGISTER <nick> <code>
    ```

    This prevents others from using your bot's nick.
  </Step>

  <Step title="Configure NullClaw">
    Add IRC to `~/.nullclaw/config.json`:

    ```json theme={null}
    {
      "channels": {
        "irc": {
          "accounts": {
            "main": {
              "host": "irc.libera.chat",
              "port": 6697,
              "nick": "nullclaw_bot",
              "channels": ["#bots"],
              "allow_from": ["your_nick"],
              "tls": true,
              "nickserv_password": "your_password"
            }
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Join Test Channels">
    Start with low-traffic channels:

    * `#bots` — Test bots here first
    * `##test` — General testing
    * Your own channel: `/join #nullclaw_test`
  </Step>

  <Step title="Start NullClaw">
    Run `nullclaw` and the bot will:

    1. Connect to the IRC server
    2. Authenticate (if configured)
    3. Join specified channels
    4. Respond to messages from allowed nicks
  </Step>
</Steps>

## Authentication Methods

### SASL PLAIN (Recommended)

```json theme={null}
{
  "host": "irc.libera.chat",
  "port": 6697,
  "nick": "nullclaw_bot",
  "sasl_password": "your_password",
  "tls": true
}
```

SASL authenticates before joining channels, preventing impersonation.

### NickServ Identification

```json theme={null}
{
  "host": "irc.libera.chat",
  "port": 6697,
  "nick": "nullclaw_bot",
  "nickserv_password": "your_password",
  "tls": true
}
```

Bot identifies after connecting via:

```
/msg NickServ IDENTIFY <password>
```

### Server Password

```json theme={null}
{
  "host": "irc.example.com",
  "port": 6667,
  "server_password": "server_pass"
}
```

Some servers require a password on connection.

## TLS Configuration

### Secure Connection (Recommended)

```json theme={null}
{
  "host": "irc.libera.chat",
  "port": 6697,
  "tls": true
}
```

Use port 6697 for TLS.

### Plain Text Connection

```json theme={null}
{
  "host": "irc.example.com",
  "port": 6667,
  "tls": false
}
```

Not recommended unless necessary.

## Message Format

IRC output is plain text only (no markdown, no code fences):

* No triple backticks
* No tables
* No HTML/XML tags
* Single blank line separates blocks
* Short lines, concise responses

The channel automatically injects this context for the LLM:

```
[context: you are responding over IRC. Plain text only. No markdown, 
no tables, no XML/HTML tags. Never use triple backtick code fences. 
Use a single blank line to separate blocks instead. Be terse and concise. 
Use short lines. Avoid walls of text.]
```

## Message Limits

IRC enforces a 512 byte limit per message (including protocol overhead). NullClaw:

* Reserves 64 bytes for sender prefix (`:nick!user@host`)
* Splits at \~448 bytes safe boundary
* Respects UTF-8 character boundaries

## Nick Collision Handling

If the nickname is already in use:

1. NullClaw appends `_`: `nullclaw_bot` → `nullclaw_bot_`
2. Retries up to 5 times: `nullclaw_bot__`, `nullclaw_bot___`, etc.
3. Fails after 5 attempts

To avoid collisions, register your nick with NickServ.

## Channel vs DM Behavior

### Channel Messages

Bot replies in the channel:

```
<alice> @nullclaw_bot hello
<nullclaw_bot> Hi alice! How can I help?
```

### Direct Messages

Bot replies via DM:

```
/msg nullclaw_bot hello
<nullclaw_bot> Hi! How can I help?
```

## Multiple Servers

Connect to multiple IRC networks:

```json theme={null}
{
  "channels": {
    "irc": {
      "accounts": {
        "libera": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "nullclaw",
          "channels": ["#bots"]
        },
        "oftc": {
          "host": "irc.oftc.net",
          "port": 6697,
          "nick": "nullclaw",
          "channels": ["#test"]
        }
      }
    }
  }
}
```

## Service Bot Filtering

NullClaw automatically ignores messages from IRC service bots:

* NickServ
* ChanServ
* BotServ
* MemoServ

## Troubleshooting

### Connection Refused

1. Verify host and port are correct
2. Check firewall/proxy settings
3. Try alternative ports: 6697, 6667, 7000
4. Test with standard IRC client first

### Nickname Already in Use

1. Choose a unique nickname
2. Register your nick with NickServ
3. Configure `nickserv_password` or `sasl_password`
4. Kill ghost sessions: `/msg NickServ GHOST <nick> <password>`

### Authentication Failed

1. Verify password is correct
2. Check that nick is registered
3. For SASL: ensure server supports SASL PLAIN
4. For NickServ: wait for `NickServ IDENTIFY` confirmation
5. Check logs: `nullclaw --log-level debug`

### Bot Not Responding

1. Verify sender nick is in `allow_from`
2. Check bot has joined the channel: `/whois nullclaw_bot`
3. Ensure channel allows bots (check channel modes)
4. Test with DM first to isolate channel issues

### TLS Handshake Failed

1. Verify server supports TLS on the specified port
2. Try a different TLS port (6697, 7000)
3. Check for certificate issues
4. Fallback to plain text temporarily for debugging:
   ```json theme={null}
   {
     "port": 6667,
     "tls": false
   }
   ```

### Message Truncation

1. This is normal — IRC has a 512 byte limit
2. NullClaw automatically splits messages
3. Adjust agent prompt to be more concise for IRC

## Source Code

Implementation: `src/channels/irc.zig`