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.

Install

hermes plugins install jrimmer/hermes-chatto-plugin

Or with the full URL:

hermes plugins install https://github.com/jrimmer/hermes-chatto-plugin.git

Then add your Chatto credentials to ~/.hermes/.env:

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

Enable the plugin (if not auto-enabled during install):

hermes plugins enable chatto-platform

Restart the gateway:

hermes gateway restart

Configuration

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 (optional)

You can also configure via ~/.hermes/config.yaml instead of env vars:

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

Features

• WebSocket realtime — binary protobuf codec for Chatto's realtime protocol (no protobuf library needed)
• 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 (watches room_created / user_joined_room events)
• Event handling — message_posted, mention_notification, new_dm_notification, session_terminated (force reconnect), message_retracted, user_left_room
• Presence broadcasting — periodic presence refresh
• Standalone cron delivery — works outside the gateway process

How It Works

The adapter connects to Chatto via two channels:

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

When a message is received, the WebSocket frame is decoded, the message body is fetched via REST, dispatched to the Hermes agent, and the response is sent back via CreateMessage with proper threading.

Tested Against

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

License

MIT