Agentirc

agentirc

An AI-powered IRC agent built on a minimal async IRC bot framework. Supports multiple LLM providers (OpenAI, xAI, LM Studio) with per-user conversation history, tool use, and encrypted persistence.

Table of Contents

• [Quick Start](#quick-start)
• [CLI Options](#cli-options)
• [Commands](#commands)
• [Documentation](#documentation)
• [License](#license)

Quick Start

git clone 
cd agentirc
cp .env.example .env
# Edit .env with your IRC server, nick, and at least one API provider
pip install .
agentirc

Or with Docker:

cp .env.example .env
# Edit .env
docker compose up -d

> Requirements: Python 3.10+, httpx, and optionally cryptography for encrypted history persistence.

CLI Options

agentirc [options]

| Flag | Description | |---|---| | --env-file PATH | Path to .env file (default: .env) | | --debug | Enable debug logging | | --host HOST | IRC server hostname (overrides IRC_HOST) | | --port PORT | IRC server port (overrides IRC_PORT) | | --nick NICK | Bot nickname (overrides IRC_NICK) | | --channels CHANS | Comma-separated channels (overrides IRC_CHANNELS) | | --tls | Connect with TLS (overrides IRC_USE_TLS) | | --model MODEL | Default model (overrides DEFAULT_MODEL) | | --init | Write a starter .env to the current directory and exit | | --generate-key | Generate a Fernet encryption key and exit |

CLI flags override their corresponding environment variables.

Commands

User Commands

| Command | Aliases | Description | |---|---|---| | !ai | !chat, !ask | Talk to the AI | | !persona | | Set a persona and reintroduce | | !custom | | Set a custom system prompt | | !reset | | Reset conversation to defaults | | !stock | | Reset conversation with no system prompt | | !mymodel [name] | | Show or set your model | | !location | | Set your location for contextual answers | | !x | | Talk as another user |

Admin Commands

| Command | Description | |---|---| | !model [name\|reset] | Show/set global default model | | !tools [on\|off\|toggle\|status] | Enable/disable tool use | | !verbose [on\|off\|toggle] | Toggle verbose mode | | !clear | Clear all conversation state | | !country [on\|off\|status] | Toggle search country filtering | | !join | Join a channel | | !part [#channel] [reason] | Leave a channel |

Built-in IRC commands (!ping, !time, !help) are also available.

Documentation

• [docs/configuration.md](docs/configuration.md) -- IRC and AI provider configuration
• [docs/commands.md](docs/commands.md) -- command registry and decorator API
• [docs/extending.md](docs/extending.md) -- subclassing IRCBot, event hooks
• [docs/ai-agent.md](docs/ai-agent.md) -- AI agent architecture, providers, tools, and history
• [docs/ai-output-disclaimer.md](docs/ai-output-disclaimer.md) -- AI output disclaimer and conditions of use
• [docs/not-a-companion.md](docs/not-a-companion.md) -- project scope and intended use

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: h1ddenpr0cess20
• Source: h1ddenpr0cess20/agentirc
• License: MIT

Install and usage instructions live in the source repository linked above.