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.

Quick Start
CLI Options
Commands
Documentation
License

Quick Start

git clone <repo-url>
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 <message>`	`!chat`, `!ask`	Talk to the AI
`!persona <text>`		Set a persona and reintroduce
`!custom <prompt>`		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 <place>`		Set your location for contextual answers
`!x <nick> <message>`		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 <#channel>`	Join a channel
`!part [#channel] [reason]`	Leave a channel

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

Documentation

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

License

MIT

Metadata

Release files for agentirc 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentirc 1.4.0
File	Size	Uploaded
agentirc-1.4.0.tar.gz	47.3 kB	Aug 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for agentirc 1.4.0
File	Interpreter	ABI	Platform	Reset
agentirc-1.4.0-py3-none-any.whl 28.6 kB Aug 7, 2026	Python 3	none	any	Details

Total release size: 76.0 kB

Release files / agentirc-1.4.0.tar.gz

Download URL	agentirc-1.4.0.tar.gz
Size	47.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`4da2a3d2381f869d5ebc2a244c51b67a1243bb49256bb38fc009c4e8ab973b5b`
BLAKE2b-256 checksum How to use checksums	`ba6e5f4d9baeb48b8511c6d9a2d5719d004dea76ab6c9daea6e2246cce3fce04`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/h1ddenpr0cess20/agentirc
Publishing commit: github.com/h1ddenpr0cess20/agentirc/tree/49a40d406a9bbc66b3bfb08d0f1d2f877ce332db

Workflow

Publishing configuration: github.com/h1ddenpr0cess20/agentirc/blob/49a40d406a9bbc66b3bfb08d0f1d2f877ce332db/.github/workflows/pypi-publish.yml
Publishing logs: github.com/h1ddenpr0cess20/agentirc/actions/runs/31137376931/attempts/1

Artifact

Subject: agentirc-1.4.0.tar.gz
SHA-256 checksum: 4da2a3d2381f869d5ebc2a244c51b67a1243bb49256bb38fc009c4e8ab973b5b Verifying attestations

Release files / agentirc-1.4.0-py3-none-any.whl

Download URL	agentirc-1.4.0-py3-none-any.whl
Size	28.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`818f1070027a56c8166ece3165be9e90f33e83a5efedb417bc0f41a823af7cee`
BLAKE2b-256 checksum How to use checksums	`2ec0aa089871e6e08ca65839ca8a41bd62d8439c83c5c15589dfd66d2fae9bca`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/h1ddenpr0cess20/agentirc
Publishing commit: github.com/h1ddenpr0cess20/agentirc/tree/49a40d406a9bbc66b3bfb08d0f1d2f877ce332db

Workflow

Publishing configuration: github.com/h1ddenpr0cess20/agentirc/blob/49a40d406a9bbc66b3bfb08d0f1d2f877ce332db/.github/workflows/pypi-publish.yml
Publishing logs: github.com/h1ddenpr0cess20/agentirc/actions/runs/31137376931/attempts/1

Artifact

Subject: agentirc-1.4.0-py3-none-any.whl
SHA-256 checksum: 818f1070027a56c8166ece3165be9e90f33e83a5efedb417bc0f41a823af7cee Verifying attestations