turborg

A Python framework for chat-network agents — an IRC bouncer + browser UI + bot orchestrator in one process. Optional LLM hookup for AI features.

from turborg.core import Agent, OutboundEnvelope
from turborg.connectors.irc import IRCConnector, IRCSettings

agent = Agent()
agent.add_connector(IRCConnector(IRCSettings(hostname="irc.libera.chat", nick="myturborg")))

@agent.on_command("ping")
async def ping(envelope):
    return OutboundEnvelope.reply(envelope, "pong")

agent.run()

That's a working IRC bot — no LLM required. Add a WebGateway and a Bouncer and you've also got a browser-side IRC client and a HexChat/irssi tunnel through the same process.

What turborg gives you

• A real IRC connector, not a toy — TLS, SASL PLAIN, NickServ identify, IRCv3 server-time, full WHOIS / NAMES / MODE handling, and tracking of every channel you're in. See docs/connectors/irc.md.
• A built-in IRC bouncer. Local clients (HexChat, irssi, mIRC) connect to the bot's loopback port, authenticate with a password, and tunnel through the bot's upstream session. The bot stays in control while a human can lurk and chat from their own client.
• A WebSocket gateway + reference web UI. A vanilla-JS single-page client at / with channel sidebar, member list, slash commands, autocomplete, IndexedDB-backed per-channel scrollback that survives reloads, browser notifications, and clear UX for kicks/bans. SaaS deployments can swap in their own polished UI; the protocol is documented and stable.
• A normalized Envelope so the same handler that runs on IRC will also run on Discord / Telegram / Web when those connectors land.
• Optional LLM, not the centerpiece. If you set an API key, !ask is wired in. If you don't, the rest of the bot doesn't care.

The design separates how the bot talks to a network (the connector) from how it thinks (any LLM, or none) from what it does (your handlers).

For the long-term vision — hive.xshellz.com, a shared-intelligence cloud any turborg instance can attach to — see docs/hive.md.

Status

v0.6.0 — alpha. The IRC connector, the bouncer, and the WebSocket gateway with reference UI are production-grade and well-tested (≥95% coverage gate enforced in CI). Other connectors are roadmap.

LLM providers are optional. turborg runs perfectly fine as a pure command-driven bot without any LLM. When you do want one, both Anthropic (default, with prompt caching) and OpenAI ship as extras — see docs/llm-providers.md.

Install

pip install turborg          # or: uv add turborg
pip install turborg[web]     # if you want the WebSocket gateway / reference UI

Configure via environment variables (everything is TURBORG_*-prefixed) or a .env file. The most common minimum:

TURBORG_IRC_HOSTNAME=irc.libera.chat
TURBORG_IRC_NICK=myturborg
TURBORG_IRC_CHANNELS='["#turborg-test"]'

See docs/configuration.md for the full list — including SASL, NickServ identify, the bouncer, the web gateway, idle-shutdown, rate limits, logging.

Quickstart

The full 5-minute tutorial is at docs/quickstart.md. The 30-second version:

pip install turborg
export TURBORG_IRC_HOSTNAME=irc.libera.chat
export TURBORG_IRC_NICK=myturborg
export TURBORG_IRC_CHANNELS='["#turborg-test"]'
turborg run

You're online. To enable the AI command, also set TURBORG_ANTHROPIC_API_KEY (or use the OpenAI extra). To attach HexChat through the built-in bouncer, set TURBORG_IRC_BOUNCER_PASSWORD. To open the reference web UI at http://127.0.0.1:8765/, set TURBORG_WEB_PASSWORD. Each is independent — pick what you need.

Run with Docker

cp .env.example .env       # fill in TURBORG_IRC_* (and optionally LLM / web / bouncer)
docker compose up

Or without compose:

docker run --env-file .env turborg/turborg:latest

Mount your own bot script with -v "$PWD/mybot.py:/app/mybot.py". The image is multi-stage, ~150 MB, and runs as a non-root user.

Documentation

• Quickstart — get a bot online in 5 minutes
• Architecture — the agent / connector / LLM / Envelope model
• IRC connector — bouncer, SASL, web gateway, channel state, and every IRC-specific design decision
• Configuration — every environment variable, every default
• LLM providers (optional) — Anthropic (default), OpenAI, custom
• Writing a connector — add Discord, Telegram, your own
• Hive — the future shared-intelligence cloud

Examples

• examples/minimal_irc_bot.py — the smallest possible bot (!ping → pong), no LLM
• examples/claude_powered_irc.py — !ask <question> proxies to Claude

Project layout

turborg/
├── src/turborg/
│   ├── core/          Agent, envelope, event bus, command registry
│   ├── connectors/    Connector ABC + per-protocol implementations
│   │   └── irc/       IRC connector + bouncer + protocol parser
│   ├── web/           WebSocket gateway + reference HTML/JS UI
│   ├── llm/           LLM provider ABC + Anthropic / OpenAI adapters
│   ├── hive/          Hive client extension hook (noop default)
│   ├── config/        pydantic-settings config
│   └── cli.py         turborg CLI entry point
├── tests/             unit + integration suites (≥95% coverage gate)
├── examples/          runnable example bots
└── docs/              full documentation

Testing

uv sync --extra dev
uv run pytest                                    # tests + coverage gate
uv run ruff check . && uv run ruff format --check .
uv run mypy src/turborg                          # strict mode

CI runs the same four gates and enforces ≥95% branch coverage.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, branching strategy, and PR rules. By submitting a contribution you agree to the Contributor License Agreement — the cla-assistant bot will guide you on first PR.

License

Apache License 2.0 — see TRADEMARKS.md for the trademark policy on the names "turborg" and "xshellz".

Security

Found a vulnerability? Please do not open a public issue. See SECURITY.md for the responsible-disclosure process.

Style

• Conventional Commits for PR titles (feat:, fix:, docs:, refactor:, chore:)
• Squash-merge to main; linear history
• 100-char line limit, ruff-formatted, mypy-strict
• pytest with branch coverage; fail under 95%

Part of the xshellz ecosystem. The future hosted hive lives at hive.xshellz.com.