Fix claude-bot replying to Hermes's own messages, route Hermes through LiteLLM

Critical bug: claude-bot only ignored its OWN messages and text explicitly
addressed to @hermes — it did not ignore Hermes's own replies appearing in
the room. A single @hermes mention cascaded into claude-bot replying to
Hermes's thread messages ('Hermes says: ...'), which could itself cascade
further. Fixed with an OTHER_AGENT_USER_IDS allowlist of sender IDs to
always ignore, not just a text-prefix check.

Also point Hermes's model provider at the local litellm gateway
(OPENAI_BASE_URL/OPENAI_API_KEY) instead of OpenRouter directly, matching
claude-agent's own chat path — one place to hold the OpenRouter credential.
This does NOT grant Hermes access to the Claude subscription; that's an
Anthropic-side restriction unrelated to which proxy sits in front of it,
already proven earlier in this session.

Separately (not a code fix): the 'Billing or credits exhausted: HTTP 402'
error Hermes hit is real — the OpenRouter account currently has 0 credits.

.env.example

@@ -30,6 +30,10 @@ MATRIX_CONTROL_ROOM_ID=
 # Required: without it the bot can't tell its own messages apart from real ones and would
 # reply to itself in a loop, so it refuses to start.
 MATRIX_BOT_USER_ID=
+# Comma-separated Matrix IDs of OTHER agents sharing the control room (currently just
+# @hermes:...) — without this, claude-bot treats every message another bot posts as
+# fresh chat input and replies to it, which that bot may then react to in turn.
+OTHER_AGENT_USER_IDS=@hermes:matrix.apps.williamturner.eu
 # Comma-separated "owner/repo" list the chat router is allowed to open code-change PRs
 # against. A plain chat message mentioning a repo NOT in this list is treated as chat,
 # never as a code task — the router only matches confidently against known repos.
@@ -40,6 +44,17 @@ OPENROUTER_API_KEY=
 # Any random string; also used as litellm's general_settings.master_key.
 LITELLM_MASTER_KEY=
 
+# --- hermes (autonomous agent with its own native Matrix presence) ---
+# Your own Matrix ID — Hermes only responds to this user, and only when @mentioned
+# in a shared room (e.g. "@hermes <task>" in the control room).
+MATRIX_HUMAN_USER_ID=@william:matrix.apps.williamturner.eu
+# Access token for the @hermes bot account (register it the same way as claude-bot —
+# see README — then log in as it via /_matrix/client/v3/login to get this token).
+HERMES_MATRIX_ACCESS_TOKEN=
+# Any random string — bearer key for Hermes's own OpenAI-compatible API server
+# (internal network only, not published anywhere).
+HERMES_API_SERVER_KEY=
+
 # --- portainer (GitOps redeploy) ---
 PORTAINER_STACK_WEBHOOK_URL=
 

agent/src/matrixBot.js

@@ -11,6 +11,15 @@ const GITEA_URL = process.env.GITEA_URL;
 // to the endpoint itself. This is also the only reliable way to filter the bot's own
 // messages now that there's no command prefix to naturally exclude them by.
 const BOT_USER_ID = process.env.MATRIX_BOT_USER_ID;
+// Other agents sharing this room (currently just Hermes) — their own messages must be
+// ignored the same way claude-bot ignores its own, or claude-bot's classifier treats
+// every message another bot posts as fresh chat input and replies to it, which that
+// bot may then react to in turn. Found the hard way: a single @hermes mention cascaded
+// into claude-bot replying to Hermes's own thread messages ("Hermes says: ...").
+const OTHER_AGENT_USER_IDS = (process.env.OTHER_AGENT_USER_IDS || "")
+  .split(",")
+  .map((id) => id.trim())
+  .filter(Boolean);
 const KNOWN_REPOS = (process.env.KNOWN_REPOS || "")
   .split(",")
   .map((r) => r.trim())
@@ -47,8 +56,13 @@ export async function startMatrixBot() {
   client.on("room.message", async (roomId, event) => {
     if (roomId !== CONTROL_ROOM_ID) return;
     if (event.sender === BOT_USER_ID) return;
+    if (OTHER_AGENT_USER_IDS.includes(event.sender)) return;
     const body = event.content?.body;
     if (!body) return;
+    // Messages explicitly addressed to another agent in this room (currently just
+    // @hermes) are that agent's to answer — without this, claude-bot's classifier would
+    // also see and reply to them, since it otherwise treats every message as its own.
+    if (/^@hermes\b/i.test(body.trim())) return;
 
     try {
       const decision = await routeMessage(body, KNOWN_REPOS);
@@ -63,6 +77,7 @@ export async function startMatrixBot() {
       }
 
       const reply = await chatReply(body);
+      console.log("chat reply sent, length:", reply.length);
       await client.sendText(roomId, truncate(reply));
     } catch (err) {
       console.error("message handling failed", err);

docker-compose.yml

@@ -61,6 +61,46 @@ services:
     # Internal only — no Traefik labels. No reason to expose an LLM gateway holding a
     # master key and OAuth-forwarding config to the public internet.
 
+  hermes:
+    # Pinned to a specific dated release, not :latest — same rationale as litellm above.
+    image: nousresearch/hermes-agent:v2026.8.19
+    container_name: hermes
+    restart: unless-stopped
+    environment:
+      HERMES_UID: "1000"
+      HERMES_GID: "1000"
+      # Internal container address, not the public HTTPS one — same docker network as
+      # matrix-homeserver, no reason to round-trip through Traefik/TLS for this.
+      MATRIX_HOMESERVER: http://matrix-homeserver:8008
+      MATRIX_ACCESS_TOKEN: ${HERMES_MATRIX_ACCESS_TOKEN}
+      # Only you can trigger it; and only with an explicit @hermes mention in shared
+      # rooms (DMs to it would respond unprompted, per Hermes's own default behavior).
+      MATRIX_ALLOWED_USERS: ${MATRIX_HUMAN_USER_ID}
+      MATRIX_REQUIRE_MENTION: "true"
+      # Routed through the local litellm gateway, not OpenRouter directly — same pattern
+      # as claude-agent's chat path, one place to hold the OpenRouter credential and swap
+      # models. Hermes's "main"/custom-endpoint provider is any OpenAI-compatible API
+      # reachable via OPENAI_BASE_URL + OPENAI_API_KEY. Note: this does NOT give Hermes
+      # access to the Claude Pro/Max subscription — that's blocked by Anthropic itself for
+      # any caller other than the real Claude Code CLI, proven earlier in this session
+      # (reproduced with plain curl straight to api.anthropic.com, LiteLLM or not).
+      OPENAI_BASE_URL: http://litellm:4000/v1
+      OPENAI_API_KEY: ${LITELLM_MASTER_KEY}
+      # Left disabled: Hermes itself warns that a network-reachable API server combined
+      # with the default unsandboxed ('local') terminal backend gives any caller full
+      # terminal/file access within the container. Matrix is the actual interface in use;
+      # re-enable (API_SERVER_HOST: 0.0.0.0) only alongside terminal.backend: docker if
+      # claude-agent ever needs to call Hermes programmatically.
+      API_SERVER_ENABLED: "false"
+    volumes:
+      - /home/william/hermes-data:/opt/data
+    networks:
+      - web
+    # Without this the image's default command launches the interactive CLI, which
+    # immediately exits ("Input is not a terminal") since a detached container has no
+    # stdin — the container then just sits there having done nothing, every restart.
+    command: ["gateway", "run"]
+
   claude-agent:
     image: ${GITEA_REGISTRY_IMAGE}
     depends_on:
@@ -81,10 +121,10 @@ services:
       MATRIX_BOT_TOKEN: ${MATRIX_BOT_TOKEN}
       MATRIX_CONTROL_ROOM_ID: ${MATRIX_CONTROL_ROOM_ID}
       MATRIX_BOT_USER_ID: ${MATRIX_BOT_USER_ID}
+      OTHER_AGENT_USER_IDS: ${OTHER_AGENT_USER_IDS}
       KNOWN_REPOS: ${KNOWN_REPOS}
-      # All model calls now go through the local litellm service, not OpenRouter directly —
+      # Chat replies go through the local litellm service (OpenRouter's models, incl. its
-      # one gateway for OpenRouter's models (incl. its auto-router) and, for the
+      # auto-router), not OpenRouter directly.
-      # claude-subscription route, Anthropic itself via the forwarded OAuth token above.
       LITELLM_BASE_URL: http://litellm:4000
       LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY}
     volumes: