Blue — iMessage bot framework

Clean, Pythonic framework for building iMessage bots (inspired by Discord bot ergonomics). Ships with a simple CLI and a minimal example.

Requirements

• Python: >= 3.9

Install

python -m venv env
source env/bin/activate
pip install -U pip wheel
pip install -e .

Quick start

Run the included example bot in example.py:

python example.py

Minimal example:

from blue import Bot, command

bot = Bot("My Bot", debug=True)

@bot.on_message
@command("!ping")
def ping(message):
    return "Pong! 🏓"

if __name__ == "__main__":
    bot.run()

Environment

Set your BlueBubbles connection and optional bot host/port. The example uses python-dotenv to load a .env file automatically.

# .env (example)
BLUEBUBBLES_SERVER_URL=http://localhost:1234
BLUEBUBBLES_PASSWORD=your_password_here
BOT_PORT=8000
BOT_HOST=127.0.0.1

CLI

The blue CLI is installed via the project’s entry point.

• Create a new bot template:

  blue create "My Bot"
  # or specify a directory
  blue create "My Bot" -d ./bots

• Show version:

  blue version

The template includes main.py, config.py, .env.example, and a starter README.md.

Development

• Run example: python example.py
• Format/Lint: bring your preferred toolchain; no strict config is bundled.

Project metadata

• Package name: blue
• Python requires: >= 3.9
• Entry point: blue → blue.cli.main:main

License

MIT