Chattermax

A modern XMPP server written in Rust with a hook system for AI agent integration. The same binary also provides a CLI client mode for scriptable XMPP interactions.

Features

XMPP Server

• Direct messaging (1:1 chat)
• Group channels (MUC - Multi-User Chat)
• User presence (online/offline/away)
• Message archiving with history retrieval
• Service discovery for client capabilities
• TLS encryption support

Hook System

The hook system lets AI agents respond to chat events. Events flow through configurable filters, spawning commands that receive JSON on stdin and reply on stdout.

[[hooks]]
name = "ai-assistant"
command = "/usr/local/bin/my-ai-agent"
filters = [
  { field = "type", pattern = "message" },
  { field = "body", pattern = "^@bot\\s+" }
]

See Hook System Documentation for details.

CLI Client Mode

One-shot commands for scripting and automation:

# Send a message
chattermax send --to user@example.com --body "Hello!"

# Set presence
chattermax presence --status online --message "Available"

# Join a channel
chattermax join --room general@conference.example.com

Quick Start

Prerequisites

• Rust 1.75+ (2024 edition)
• SQLite 3.x (for development) OR PostgreSQL 12+ (for production)

Build

git clone https://github.com/terraboops/chattermax.git
cd chattermax
cargo build --release

Run Server

# Initialize database
./target/release/chattermax --init-db

# Create a user
./target/release/chattermax --add-user alice:password

# Start server
./target/release/chattermax

The server listens on 0.0.0.0:5222 by default.

Connect

Use any XMPP client with:

Setting	Value
Server	localhost
Port	5222
Username	alice
Password	password

Configuration

[server]
host = "0.0.0.0"
port = 5222
domain = "example.com"

[database]
path = "chattermax.db"

[tls]
cert_path = "/etc/chattermax/fullchain.pem"
key_path = "/etc/chattermax/privkey.pem"

# AI agent hook
[[hooks]]
name = "ai-assistant"
command = "/usr/local/bin/my-ai-agent"
filters = [
  { field = "body", pattern = "^@assistant\\s+" }
]

See Configuration Reference for all options.

Documentation

Document	Description
Getting Started	Installation and first steps
Hook System	AI agent integration guide
CLI Client	Command-line client usage
Architecture	System design and components
Configuration	All configuration options
PostgreSQL Backend	PostgreSQL deployment and configuration
Protocol Support	XMPP XEP coverage
Deployment	Production deployment guide

Tested Clients

Chattermax targets compatibility with major Android XMPP clients:

Client	Platform	Status
Conversations	Android	Primary target
Blabber.im	Android	Supported
Moxxy	Android	Supported
Gajim	Desktop	Supported
Psi	Desktop	Supported

XMPP Protocol Support

Required for Android Compatibility

XEP	Name	Status
XEP-0030	Service Discovery	Supported
XEP-0045	Multi-User Chat	Supported
XEP-0115	Entity Capabilities	Planned
XEP-0198	Stream Management	Planned
XEP-0280	Message Carbons	Planned
XEP-0313	Message Archive Management	Supported

See Protocol Support for full details.

Current Status

Chattermax is in MVP (v0.1.x) status, suitable for development and production deployment.

Implemented:

• Core messaging (1:1 and group)
• Message archiving (MAM)
• Service discovery
• SQLite storage
• PostgreSQL support
• Hook system for AI agents

In Progress:

• CLI client mode
• TLS encryption

Planned:

• Stream management (XEP-0198)
• Message carbons (XEP-0280)
• Entity capabilities (XEP-0115)

Use Cases

• AI Chat Assistants - Connect LLMs to XMPP via the hook system
• Chat Bots - Automate responses using CLI client or hooks
• Private Messaging - Self-hosted chat for teams or communities
• IoT Integration - Device notifications via XMPP

Contributing

Contributions welcome! See Contributing Guide and Code of Conduct.

License

Apache License 2.0. See LICENSE.

Author

Terra Tauri (me@terratauri.com)