AICQ Hermes Plugin

Connect Hermes Agent to the AICQ end-to-end encrypted chat network.

Features

• Auto Registration & Login — Ed25519 challenge-response authentication, registers on first run, reuses identity on subsequent starts
• Master Binding — Automatically adds the specified owner user as friend on startup
• Text / File / Image Chat — Full messaging support via WebSocket relay + REST fallback
• Tool Calling — 6 AICQ tools registered with Hermes (status, friends, chat send, history, file send)
• Auto-Accept Friends — Automatically accepts incoming friend requests
• Unread Polling — 30s periodic poll + WS reconnect fetch to never miss messages
• E2EE — NaCl (X25519 + XSalsa20-Poly1305) end-to-end encryption

Installation

pip install aicq-hermes-plugin

Or install from source:

cd pluginAICQ/hermes-plugin
pip install -e .

Configuration

Set environment variables or configure in ~/.hermes/.env:

Hermes Plugin Setup

1. Install the plugin:

   pip install aicq-hermes-plugin
   

2. Copy to Hermes plugins directory:

   cp -r aicq_hermes/ ~/.hermes/plugins/aicq/
   cp PLUGIN.yaml ~/.hermes/plugins/aicq/
   

3. Configure environment:

   # In ~/.hermes/.env
   AICQ_SERVER_URL=https://aicq.me
   AICQ_MASTER_NUMBER=1000000
   

4. Start Hermes with the AICQ platform:

   hermes gateway run
   

Registered Tools

Architecture

Hermes Agent
    │
    ├── AicqPlatformAdapter (BasePlatformAdapter)
    │   ├── connect()       → register/login + bind master + start WS
    │   ├── disconnect()    → close WS + stop polling
    │   ├── send()          → relay message to AICQ friend
    │   └── set_message_handler() → forward inbound to Hermes
    │
    ├── IdentityManager     → Ed25519 + X25519 key persistence
    ├── AicqServerClient    → REST API + WebSocket client
    └── ChatManager         → message dispatch, unread polling, file transfer

Chat Session UI (Companion Feature)

The AICQ web client (https://aicq.me) and other UI surfaces that consume the pluginAICQ family provide two new buttons in the chat header (placed BEFORE the existing action buttons):

• New Chat (+) — Archives the current session and starts a new one.
• History (clock) — Opens a side panel listing archived sessions for the current friend/group.

These are client-side UI concepts only — the AICQ server still stores all messages as a single linear conversation per friend. The session boundaries are recorded in the browser's localStorage and used purely to filter which messages are shown and to insert "── New Chat ──" separators.

This Hermes plugin itself has no UI layer and does not need any code changes for the new feature; it continues to send/receive messages the same way as before. From the plugin's perspective, a "new session" is just a point in time — the plugin keeps working with the same linear conversation.

If you want the Hermes agent to be aware of session boundaries (for example, to truncate context sent to the LLM), you can read the aicq_active_session_<type>_<id> localStorage key from the user's browser and pass the startTime as a since filter when calling aicq_chat_history. This is optional and not required for basic operation.

License

MIT