hermes-chatto-plugin

Hermes Chatto Plugin

A Chatto platform adapter plugin for Hermes Agent. Connects your self-hosted Chatto server to Hermes so you can interact with the agent through chat rooms and DMs.

Features

• WebSocket realtime — binary protobuf codec for Chatto's realtime protocol (no protobuf library needed — pure stdlib)
• ConnectRPC REST API — JSON over HTTP for outbound messages, room discovery, user lookup
• Thread support — GetThreadEvents for thread replies, auto-thread creation, proper threadRootEventId handling
• DM support — DMs always get a response, no threading in DM rooms
• Mention filtering — require_mention (default true) with free_response_channels for no-tag rooms
• Dynamic room discovery — auto-joins new rooms without gateway restart
• Event handling — message_posted, mention_notification, new_dm_notification, session_terminated (force reconnect), message_retracted, user_left_room, room_created, user_joined_room
• Presence broadcasting — periodic presence refresh
• Notification dismissal — marks notifications as read after processing
• Standalone cron delivery — works outside the gateway process

Installation

# Clone into your Hermes plugins directory
git clone https://github.com/jrimmer/hermes-chatto-plugin.git /tmp/chatto-plugin

# Copy the plugin into place
cp -r /tmp/chatto-plugin/plugins/platforms/chatto ~/.hermes/plugins/platforms/chatto

Or if you're using a profile:

cp -r /tmp/chatto-plugin/plugins/platforms/chatto ~/.hermes/profiles/<profile>/plugins/platforms/chatto

Configuration

Add your Chatto credentials to ~/.hermes/.env:

CHATTO_URL=https://chat.example.com
CHATTO_LOGIN=max
CHATTO_PASSWORD=your-password
CHATTO_HOME_CHANNEL=REljMv5Pgolo6Y9

Then enable the plugin in ~/.hermes/config.yaml:

plugins:
  enabled:
    - platforms/chatto

gateway:
  platforms:
    chatto:
      enabled: true
      extra:
        url: https://chat.example.com
        require_mention: true
        home_channel: REljMv5Pgolo6Y9
        free_response_channels: []

Restart the gateway:

hermes gateway restart

Configuration Options

Environment Variables

Variable	Required	Description
CHATTO_URL	Yes	Base URL of your Chatto server
CHATTO_LOGIN	Yes	Chatto username
CHATTO_PASSWORD	Yes	Chatto password
CHATTO_HOME_CHANNEL	No	Room ID for cron/notification delivery (defaults to first watched room)
CHATTO_CHANNELS	No	Comma-separated room IDs to watch (default: all joined rooms)
CHATTO_REQUIRE_MENTION	No	Only respond to @mentions in rooms (default: true). DMs always respond.
CHATTO_AUTO_THREAD	No	Auto-create threads for replies in rooms (default: true)
CHATTO_FREE_RESPONSE_CHANNELS	No	Comma-separated room IDs where bot responds without being tagged
CHATTO_ALLOWED_USERS	No	Comma-separated Chatto logins allowed to talk to the bot
CHATTO_ALLOW_ALL_USERS	No	Allow any Chatto user to talk to the bot (true/false)

YAML Config

Key	Default	Description
url	—	Chatto server URL
require_mention	true	Only respond to @mentions in public rooms
home_channel	first room	Room ID for cron delivery
free_response_channels	[]	Rooms where the bot responds without being tagged
channels	all joined	List of room IDs to watch

How It Works

The adapter connects to Chatto via two channels:

1. WebSocket (/api/realtime) — receives realtime events (messages, mentions, DMs, room changes) as binary protobuf frames
2. ConnectRPC REST (/api/connect/) — sends messages, fetches room events, joins rooms, manages presence

When a message is received:

1. The WebSocket frame is decoded as a protobuf envelope
2. If it's a message_posted event, the message body is fetched via REST (GetRoomEvents or GetThreadEvents for thread replies)
3. The message is dispatched to the Hermes agent
4. The agent's response is sent back via CreateMessage with proper threading

Tested Against

Chatto v0.4.19. Protocol version 1 (binary protobuf over WebSocket).

License

MIT