Humalike Plugin

For any questions regarding Humalike, go to https://docs.humalike.com/.

One command gives your Hermes agent social intelligence. It decides when to speak, adapts to your group's tone and remembers who said what. Works in group chats on Slack, Telegram, WhatsApp and Discord, powered by the Humalike APIs:

• Turn-taking - decides when to jump in vs stay silent, and naturalizes replies so they read like a person wrote them, not one wall of bot text.
• Persona - /soul enhance turns a one-line description into a fleshed-out character with a real voice.
• Theory of mind - considers how a message will land for the reader and adjusts before sending.
• Social learning - picks up the group's slang, formatting, and jokes, and starts sounding like a member rather than a visitor.

Install

First update Hermes to the latest version - the plugin patches into Hermes internals, so an out-of-date Hermes can leave turn-taking silently unhooked:

hermes update

Then clone and enable:

git clone https://github.com/Humalike/hermes-humalike-plugin ~/.hermes/plugins/humalike

# run `hermes` from your Hermes install - activate its virtualenv first
# (or call the hermes CLI by its full path)
hermes plugins enable humalike

Then start Hermes so the plugin loads and runs its first-start setup:

hermes

(hermes plugins enable only records the plugin; nothing happens until Hermes actually starts. Use whatever command runs your bot - hermes, or your gateway start command.)

On first start the plugin applies every required config change itself and prints what it changed, where, and why. For authentication it prints a login URL (and opens a browser tab when the machine has one) - approve on any device and the key is saved to ~/.hermes/.env.

You can also send the bot /connect at any time to link an account from chat; the key goes live without a restart.

Configured for you on the first start

Everything turn-taking needs is applied automatically the first time the plugin runs - it writes these settings itself and prints exactly what it changed. You don't set any of them by hand; they're listed here so you know what and why:

Setting (file)	Set to	Why
streaming (config.yaml)	false	the plugin rewrites the final reply into human-style messages, so Hermes must not also stream its own raw draft over the top
group_sessions_per_user (config.yaml)	false	everyone in a group shares one conversation, so the bot follows the whole room instead of a separate thread per person
display.tool_progress (config.yaml)	off	hides "Browsing…/Clicking…" tool chatter so replies read as human
display.busy_ack_enabled (config.yaml)	false	suppresses the deterministic "⚡ Interrupting current task…" busy acks - a human doesn't announce that
display.memory_notifications (config.yaml)	off	hides the "💾 Self-improvement review…" background-memory posts - a human doesn't announce memory updates
display.platforms.telegram.streaming (config.yaml)	false	Telegram's native draft streaming would show the raw draft before naturalization
agent.disabled_toolsets (config.yaml)	+ clarify	the clarify tool's numbered-option menus are sent by the gateway directly, bypassing naturalization; without it the bot asks in plain text
slack.reply_in_thread (config.yaml, only if Slack is connected)	false	one shared conversation per channel; the default starts a fresh thread + session for every message, so the bot would answer each one separately
WHATSAPP_* / SLACK_* respond-to-everyone (.env, only for a connected platform)	open	reply to everyone in DMs and groups without needing an @mention

Restart the gateway once after this first boot so the new values load - the plugin's report ends with that reminder.

Action required - the few things it can't do for you

• Persona file location - the plugin reads your persona from ~/.hermes/SOUL.md. If yours lives somewhere else (e.g. a Docker mount), point it there in ~/.hermes/config.yaml:

  turn_taking:
    soul_path: "/path/to/SOUL.md"
  

• Telegram groups - two steps that genuinely can't be automated: disable privacy mode in @BotFather, and add the group's chat id to TELEGRAM_GROUP_ALLOWED_CHATS. The plugin prints both when Telegram is in use.
• A personal WhatsApp number - the respond-to-everyone setting means the bot replies to everyone who messages that number, in DMs and all groups. If it's your personal number, tighten it (the plugin warns about this at setup): WHATSAPP_ALLOW_ALL_USERS=false and/or WHATSAPP_GROUP_POLICY=allowlist.
• Discord bot setup - steps that can't be automated. Create the bot in the Developer Portal, enable Message Content Intent and Server Members Intent, and invite it with the bot+applications.commands scope and permissions=274878286912. Full walkthrough (intents, invite URL, env vars, auth models): the configure-discord-group skill.

Overrides

~/.hermes/.env (Authorization: Bearer):

HUMALIKE_API_KEY=your-api-key   # skips the login prompt
HUMALIKE_API_URL=…              # non-default environment; set EMPTY to disable turn-taking

Optional persona knob in ~/.hermes/config.yaml under turn_taking: - soul_auto_enhance (true by default: one automatic persona attempt per resolved SOUL.md path; set false to skip it).

That's it - restart the gateway and message the bot. It now reads the room and replies when it has something to say.

Platforms

Platform	Extra setup
WhatsApp	DMs work as-is. Groups: skills/configure-whatsapp-group
Telegram	DMs work as-is. Groups: skills/configure-telegram-group
Slack	DMs/@mentions work as-is. Unmentioned channel messages: skills/configure-slack-group
Discord	DMs work as-is. Server channels: skills/configure-discord-group

Discord notes

• Typing indicator - Discord's typing is a persistent refresh loop, so the plugin mutes the host's think-time typing and shows typing only while a reply bubble is being paced, with an explicit stop after the last bubble. To restore host typing during think time: HERMES_DISCORD_MUTE_HOST_TYPING=false (env) or turn_taking: {discord_mute_host_typing: false} (config.yaml).
• Captionless media - images/files sent without text reach the service as a clean [image]/[media] marker (with has_media), not the host's placeholder sentence, so turn-taking knows media arrived.
• Fast message bursts - a follow-up that arrives while the bot is composing is merged into the in-flight turn and the reply is re-stamped with the newest turn epoch, so quick "hermes" / "are you here?" bursts get an answer instead of a silently superseded one.
• Mentions - <@id>/<@!id> tokens are resolved for the service: the bot's own mention becomes @you, other people become @DisplayName.
• Slash commands (/new, /sethome, …) bypass the turn-taking gate.

Persona: /soul enhance

Send the bot /soul enhance to deepen its persona: reads SOUL.md, enhances it via the Personas API, backs up the old file to SOUL.md.bak, writes the result - effective on the next message. Needs a seed description first; a bare template is skipped. The plugin makes one automatic attempt per resolved SOUL.md path (disable: soul_auto_enhance: false); if it fails, use /soul enhance to retry manually.

License

MIT.