Summary

We run a multi-agent Discord setup (3 specialized Hermes instances in separate systemd services, each with its own profile, persona, and model). The biggest pain point: agents in shared channels have no visibility into each other's messages, making collaborative workflows impossible without triggering response cascades.

We built a working solution and want to share the approach for potential upstreaming. Related to #13054 (which proposes the same history injection) but we also solved the cascade prevention and mention-gating problems that come with multi-bot shared channels.

Our Setup

• 3 Hermes instances: Raiden (coder, GLM-5.1), Zhongli (architect, Kimi K2.6), Nahida (critic, Qwen 3.6 Plus)
• Each runs as a separate systemd service with HERMES_HOME pointing to its own profile
• Shared Discord channel where all three are present
• A human @mentions one agent to kick off a task; agents should see full channel context but NOT respond unless mentioned

What We Built

1. Channel History Injection (same direction as #13054)

A small patch in _handle_message that fetches the last N messages from Discord channel history and prepends them to the channel prompt:

# PATCH: inject recent channel history as context so agents can see
# each other's messages without needing to trigger each other.
# Controlled by DISCORD_CHANNEL_HISTORY_SIZE (0 = disabled).
_history_size = int(os.getenv("DISCORD_CHANNEL_HISTORY_SIZE", "0"))
if _history_size > 0:
    try:
        _history_lines = []
        async for _m in _chan.history(limit=_history_size, before=message):
            _author = _m.author.display_name or _m.author.name
            if _m.content:
                _history_lines.append(f"[{_author}]: {_m.content}")
        if _history_lines:
            _history_block = "Recent channel history (oldest to newest):\n" + "\n".join(reversed(_history_lines))
            _channel_prompt = (_history_block + "\n\n" + _channel_prompt).strip() if _channel_prompt else _history_block
    except Exception:
        pass

Controlled by DISCORD_CHANNEL_HISTORY_SIZE env var (0 = off, we use 50).

2. Cascade Prevention

This was the hard part. With DISCORD_ALLOW_BOTS=all, all three agents saw every message and responded to each other in an infinite loop. The existing require_mention + DISCORD_ALLOW_BOTS interaction wasn't sufficient alone.

Our working configuration for each agent's systemd service:

Plus each agent's SOUL.md includes instructions to never use @ when referencing other agents by name (prevents accidental mention triggers from bot-generated text).

3. Per-Channel Behavior

Using free_response_channels to allow free response in an agent's "home" channel while requiring mentions in the shared multi-agent channel:

discord:
  require_mention: true
  free_response_channels: '<home_channel_id>'
  allowed_channels: '<home_channel_id>,<shared_channel_id>'

Pain Points Encountered

1. require_mention config is fragile. It's set in config.yaml under discord:, which gets mapped to env var DISCORD_REQUIRE_MENTION at load time — but only if the env var isn't already set. We had to set the env var directly in the systemd service to guarantee it takes effect.

2. DISCORD_ALLOW_BOTS values are poorly documented. The three modes (none, mentions, all) are critical for multi-agent but only discoverable by reading the source. The mentions mode is the correct choice for multi-agent but wasn't obvious.

3. No built-in channel history. When require_mention: true, the agent only sees the single @mention message — zero context about what other agents said. This makes collaborative workflows (code review, planning, critique) impossible without the patch above.

4. Bot-generated @mentions trigger loops. If agent A says "ask @Raiden for help", that's a Discord mention that triggers Raiden. We had to add SOUL.md instructions to prevent this, but it's fragile — a proper solution would be a gateway-level option to ignore bot-originated mentions.

Proposed Upstream Changes

We'd love to see these land natively:

1. DISCORD_CHANNEL_HISTORY_SIZE env var (or history_backfill as #13054 proposes) — our patch above, or their PR. Either works.
2. DISCORD_ALLOW_BOTS=mentions mode — already exists, just needs better documentation.
3. A bot_mentions_trigger: false config — prevents bot-generated @mentions from triggering other bots, solving the cascade problem at the gateway level instead of relying on SOUL.md instructions.
4. Multi-agent docs page — documenting the systemd profile pattern, env var combinations, and common pitfalls.

Happy to help test or refine any of these if there's interest.