__
|__|_______ ____ _____ __ _ ________
| |\_ __ \_/ ___\ \__ \ \ \/ \/ /\____ \
| | | | \/\ \___ / __ \_\ / | |_) )
|__| |__| \___ )(____ / \/\_/ | __/
\/ \/ |__|
WARNING: This documentation is incomplete, and a constant WIP as new features and changes are rolled in regularly.
An easy to setup OpenAI API (Ollama, Llamacpp, etc) connected IRC bot with easily extensible plugin functionality.
Ircawp is under heavy development and may undergo significant changes. I'm already planning a refactor to make it easier to port to other services, like Discord.
It's the name of an old bot we had on IRC in the late 1990s. Back then it was a more straightforward bot that would handle channel operations, bans, etc. Then it became a fun Markov chain based babbler that would actually learn from the inputs people would feed it.
Eventually it's "brain" would get corrupted and we'd have to reset it.
Hopefully down the line this LLM-based bot will, too, be able to do something similar where the bot will learn from our bizarre shit and regurgitate even weirder stuff.
But for now, the standard LLM weirdness is good enough for me! ;)
- Designed to work on lower-end hardware first. (I personally deploy this on a small AMD Ryzen 5 5625U based media box that sits on a shelf.)
- Request queue that processes requests in the order received.
- OpenAI backend (compatiable with Ollama)
- Easy plugin support to add new
/slashcommands with arguments; return images and text.- Includes weather and a host of chatbot 'personalities' to ask the advice of.
- Supports media image attachments from Slack for the LLM, or passed to plugins.
- SDXS image generation (insanely fast!); renders on the CPU by default, but even on that meager Ryzen 5 CPU it can generate about an image a second. Sure, they're not fantastic and they're 512x512, but c'mon, man, they're practically free. 😉
- ZImage Turbo image generation (also fast!), but renders on the GPU -- very high quality.
- Tested with Python 3.11
- Deployed on a small box with 64gb of RAM (it's overkill; 32gb is recommended though).
-
Run
setup.shto setup a venv, install dependencies, create config files, and download models. -
You'll need to setup a Slack application. Doing that is beyond the scope of this meager README.
-
Modify .env with your Slack API credentials.
- The
promptstring in the config has some interpolated variables available for dynamic prompt content, including{today}for today's date. Add your own as needed.
- Run
bot.pyto start the bot. If all your configs and models are in place, and your creds are in.env, it should just work. - Use
cli.pyto query the bot from the command line. This is useful for debugging and manually testing plugins.
The bot supports several special prefixes at the start of messages to modify behavior:
Start your message with + to continue the previous conversation with full context:
user: What's the capital of France?
bot: Paris is the capital of France.
user: +What's its population?
bot: Paris has a population of about 2.1 million people.
user: +Tell me more about it
bot: Paris is known for the Eiffel Tower, the Louvre...
How it works:
- Every message without
+starts a fresh conversation (the default behavior) - Messages with
+continue from the previous conversation, maintaining full context - The conversation is global - anyone in the channel can continue with
+ - Media attachments (images) are preserved in the conversation history
- Plugin responses are also stored, so you can ask follow-up questions about plugin output
Examples:
user: Explain quantum physics
bot: [detailed explanation]
user: +Can you simplify that? [continues - bot remembers the physics topic]
bot: [simpler explanation]
user: What's the weather? [no + - starts fresh, physics forgotten]
bot: [weather info]
user: +What about tomorrow? [continues - bot remembers weather context]
bot: [tomorrow's forecast]
user: /weather 06457 [plugin command]
bot: Weather for Middletown: Broken Clouds at 40F...
user: +What should I wear? [continues - bot remembers the weather]
bot: I'd recommend layers since it's 40F and cloudy...
Using + as a plugin argument:
You can also use + as an argument to a plugin command to use the most recent response as the plugin's input:
user: /weather Hartford
bot: Weather for Hartford: Sunny at 72F...
user: /img + [generates image using the weather description]
bot: [image of sunny Hartford weather]
user: /summarize https://example.com
bot: [summary of the webpage]
user: /askjesus + [asks Jesus about the summary]
bot: [Jesus's perspective on the webpage content]
!- Skip the system prompt (raw LLM response)^- Prepend the last generated image to your message@- Use an alternate neutral system prompt
The bot responds to /command style slash commands, if the first character is a slash. These are defined in the config.yml file, with the appropriate Python modules implementing them placed in the plugins directory.
Execute commands like so: @ircawp /mycommand query value.
A base set of plugins are included, including but not limited to:
/?and/help- dumps all the registered slash commands/reverse- reverses the text you give it (a trivial demo!)/weather- queries OpenWeatherMap for current weather conditions. Supports ZIP codes, city names, and "City, State" format (e.g.@ircawp /weather 90210or@ircawp /weather Hartford, CT). Can optionally generate a weather scene image./askjesus- ask Jesus for advice (e.g.@ircawp /askjesus should I buy a new car?) -- and other characters!/summarize- summarizes a webpage given a URL/geolocate- runs rudimentary a geolocation prompt on a provided image
Creating a plugin is straightforward. Here's the basic structure:
from app.backends.Ircawp_Backend import Ircawp_Backend
from app.media_backends.MediaBackend import MediaBackend
from .__PluginBase import PluginBase
def my_function(
prompt: str,
media: list,
backend: Ircawp_Backend,
media_backend: MediaBackend = None,
) -> tuple[str, str, bool, dict]:
"""
Your plugin logic here.
Returns:
tuple: (response_text, media_path, skip_imagegen, metadata_dict)
"""
response = f"You said: {prompt}"
return response, "", True, {}
plugin = PluginBase(
name="My Plugin",
description="What shows up in /help output",
triggers=["mycommand", "mycmd"], # /mycommand or /mycmd will trigger this
system_prompt="",
emoji_prefix="🎯",
msg_empty_query="No input provided",
msg_exception_prefix="MY PLUGIN ERROR",
main=my_function,
use_imagegen=False,
prompt_required=True,
media_required=False,
)Key components:
- main function: Must accept
(prompt, media, backend, media_backend)and return(response_text, media_path, skip_imagegen, metadata_dict) - triggers: List of command names (without the
/) that invoke your plugin - description: Displayed in
/helpoutput - prompt_required: Set to
Falseif the plugin works without arguments - media_required: Set to
Trueif the plugin needs an image attachment - use_imagegen: Set to
Trueif you want automatic image generation for the response
All *.py files in /app/plugins/ are automatically loaded at runtime. See 8ball.py, weather.py, or other plugins for complete examples.
-
You will need to judge for yourself whether your hardware available is good enough to run an LLM chat bot. By default this runs on the CPU, and I get some reasonable speeds. But you have to understand that this is a very computationally expensive process and it is not streaming the response. So you have to wait for the entire inference to complete before the bot posts it back to the channel. This can be between a few seconds, or a few minutes, depending on your hardware and the size of the model you're using.
-
This bot was designed for small-scale use by a handful of people. It will queue up requests and respond to them in order. If you have a large channel with a lot of people eager to talk to the bot, you may want to consider a different solution. Or maybe not. I don't know. I'm not your dad. (Unless you're my kid, in which case, I'm going out for a pack of cigs. Don't wait up.)
-
This software could probably be written much more efficiently, faster, etc. Feel free to fork; maybe ping me if you do and maybe I'll steal some of your ideas.
-
This software is provided as-is, with no warranty or guarantee of any kind. Use at your own risk.
- Bug tickets are fine, but this project is not currently accepting outside contributions. Ideas are fine to run by me, as long as you don't expect me to agree and implement it. I mean, if it's good, I might. I already implemented some surprise ideas last night. Who knows?
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
© Network47.org, 2025, 2026