Soulshack User Guide

Soulshack is an advanced IRC chatbot powered by LLMs, designed to bridge traditional chat with modern AI capabilities.

Features

• Multi-Provider Support: Works with OpenAI, Anthropic, Google Gemini, and Ollama.
• Unified Tool System: Supports shell scripts, MCP servers, and native IRC tools.
• Secure: Full SSL/TLS and SASL authentication support.
• Session Management: Configurable history, context window, and session TTL.
• Streaming: Real-time responses with IRC-appropriate chunking.
• Passive Mode: Optional URL watching and analysis.
• Runtime Configuration: Manage settings via IRC commands.

Quickstart

Option 1: Docker

docker build . -t soulshack:dev

Option 2: Build from Source

Prerequisites: Go 1.23+

1. Clone and Build:

   git clone https://github.com/pkdindustries/soulshack.git
   cd soulshack
   go build -o soulshack cmd/soulshack/main.go
   

2. Run:

   Configuration File (Recommended)

   Local Binary:

   ./soulshack --config examples/chatbot.yml
   

   Docker:

   # Mount config file to container
   docker run -v $(pwd)/examples/chatbot.yml:/config.yml soulshack:dev \
     --config /config.yml
   

   All Flags (Kitchen Sink)

   Local Binary:

   ./soulshack \
     --nick soulshack \
     --server irc.example.com \
     --port 6697 \
     --tls \
     --channel '#soulshack' \
     --saslnick mybot \
     --saslpass mypassword \
     --admins "admin!*@*" \
     --model openai/gpt-5.1 \
     --openaikey "sk-..." \
     --maxtokens 4096 \
     --temperature 1 \
     --apitimeout 5m \
     --tool "examples/tools/datetime.sh" \
     --tool "irc__op" \
     --thinkingeffort off \
     --urlwatcher \
     --verbose
   

   Docker:

   docker run soulshack:dev \
     --nick soulshack \
     --server irc.example.com \
     --port 6697 \
     --tls \
     --channel '#soulshack' \
     --saslnick mybot \
     --saslpass mypassword \
     --admins "admin!*@*" \
     --model openai/gpt-5.1 \
     --openaikey "sk-..." \
     --maxtokens 4096 \
     --temperature 1 \
     --apitimeout 5m \
     --thinkingeffort off \
     --urlwatcher \
     --verbose
   # Note: Local file tools/scripts require volume mounts to work in Docker
   

   Ollama (Local)

   Local Binary:

   ./soulshack \
     --server irc.example.com \
     --channel '#soulshack' \
     --model ollama/qwen3:30b \
     --ollamaurl "http://localhost:11434"
   

   Docker:

   # Use --network host to access Ollama on localhost
   docker run --network host soulshack:dev \
     --server irc.example.com \
     --channel '#soulshack' \
     --model ollama/qwen3:30b \
     --ollamaurl "http://localhost:11434"
   

   Anthropic

   Local Binary:

   ./soulshack \
     --server irc.example.com \
     --channel '#soulshack' \
     --model anthropic/claude-opus-4.5 \
     --anthropickey "sk-ant-..."
   

   Docker:

   docker run soulshack:dev \
     --server irc.example.com \
     --channel '#soulshack' \
     --model anthropic/claude-opus-4.5 \
     --anthropickey "sk-ant-..."
   

Configuration Flags

YAML Configuration

Create a config.yml file:

server:
  nick: "soulshack"
  server: "irc.example.com"
  port: 6697
  channel: "#soulshack"
  tls: true

bot:
  admins: ["nick!user@host"]
  tools:
    - "examples/tools/datetime.sh"
    - "examples/mcp/filesystem.json"

Run with: ./soulshack --config config.yml

Commands

Built-in Tools

Soulshack comes with native IRC management tools (permissions apply):

• irc_op, irc_deop: Grant/revoke operator status.
• irc_kick, irc_ban, irc_unban: User management.
• irc_topic: Set channel topic.
• irc_invite: Invite users to channel.
• irc_mode_set, irc_mode_query: Manage channel modes.
• irc_names, irc_whois: User information.

Documentation

• Contributing: Guide for adding commands and tools.
• Architecture: High-level system overview.

Named as tribute to my old friend dayv, sp0t, who i think of often.