Skip to content
Back to search

hermes-humalike-plugin

A Hermes Agent plugin that makes your bot feel like a person in the chat instead of a bot. It plugs into the Humalike APIs so the agent knows when to speak, how to say it, who it is, and who it's talking to.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/humalike--hermes-humalike-plugin/badge.svg)](/listings/humalike--hermes-humalike-plugin)

HTML

<a href="/listings/humalike--hermes-humalike-plugin"><img src="/api/listings/humalike--hermes-humalike-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 165 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <a href="https://humalike.ai/"><img src="assets/humalike_x_hermes_banner.png" alt="Humalike × Hermes" width="100%"></a>
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/Humalike/hermes-humalike-plugin/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Humalike/hermes-humalike-plugin" alt="License"></a>
  6. <a href="https://github.com/Humalike/hermes-humalike-plugin/stargazers"><img src="https://img.shields.io/github/stars/Humalike/hermes-humalike-plugin" alt="Stars"></a>
  7. <a href="https://github.com/Humalike/hermes-humalike-plugin/issues"><img src="https://img.shields.io/github/issues/Humalike/hermes-humalike-plugin" alt="Issues"></a>
  8. <a href="https://humalike.ai/"><img src="https://img.shields.io/badge/website-humalike.ai-1f6feb" alt="Website"></a>
  9. </p>
  10. # Humalike Plugin
  11. For any questions regarding Humalike, go to https://docs.humalike.com/.
  12. 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](https://docs.humalike.com) APIs:
  13. - **[Turn-taking](https://docs.humalike.com/api-reference/turn-taking/overview)** -
  14. decides when to jump in vs stay silent, and naturalizes replies so they read
  15. like a person wrote them, not one wall of bot text.
  16. - **[Persona](https://docs.humalike.com/api-reference/personas)** -
  17. `/soul enhance` turns a one-line description into a fleshed-out character
  18. with a real voice.
  19. - **[Theory of mind](https://docs.humalike.com/api-reference/foresee)** -
  20. considers how a message will land for the reader and adjusts before sending.
  21. - **[Social learning](https://docs.humalike.com/api-reference/extract)** -
  22. picks up the group's slang, formatting, and jokes, and starts sounding like
  23. a member rather than a visitor.
  24. ## Install
  25. First update Hermes to the latest version - the plugin patches into Hermes
  26. internals, so an out-of-date Hermes can leave turn-taking silently unhooked:
  27. ```bash
  28. hermes update
  29. ```
  30. Then clone and enable:
  31. ```bash
  32. git clone https://github.com/Humalike/hermes-humalike-plugin ~/.hermes/plugins/humalike
  33. # run `hermes` from your Hermes install - activate its virtualenv first
  34. # (or call the hermes CLI by its full path)
  35. hermes plugins enable humalike
  36. ```
  37. Then start Hermes so the plugin loads and runs its first-start setup:
  38. ```bash
  39. hermes
  40. ```
  41. (`hermes plugins enable` only records the plugin; nothing happens until Hermes
  42. actually starts. Use whatever command runs your bot - `hermes`, or your gateway
  43. start command.)
  44. On first start the plugin applies every required config
  45. change itself and prints what it changed, where, and why. For authentication it
  46. prints a login URL (and opens a browser tab when the machine has one) - approve
  47. on any device and the key is saved to `~/.hermes/.env`.
  48. You can also send the bot `/connect` at any time to link an account from chat;
  49. the key goes live without a restart.
  50. ### Configured for you on the first start
  51. Everything turn-taking needs is applied automatically the first time the plugin
  52. runs - it writes these settings itself and prints exactly what it changed. You
  53. don't set any of them by hand; they're listed here so you know what and why:
  54. | Setting (file) | Set to | Why |
  55. |---|---|---|
  56. | `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 |
  57. | `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 |
  58. | `display.tool_progress` (config.yaml) | `off` | hides "Browsing…/Clicking…" tool chatter so replies read as human |
  59. | `display.busy_ack_enabled` (config.yaml) | `false` | suppresses the deterministic "⚡ Interrupting current task…" busy acks - a human doesn't announce that |
  60. | `display.memory_notifications` (config.yaml) | `off` | hides the "💾 Self-improvement review…" background-memory posts - a human doesn't announce memory updates |
  61. | `display.platforms.telegram.streaming` (config.yaml) | `false` | Telegram's native draft streaming would show the raw draft before naturalization |
  62. | `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 |
  63. | `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 |
  64. | `WHATSAPP_*` / `SLACK_*` respond-to-everyone (`.env`, only for a connected platform) | open | reply to everyone in DMs and groups without needing an @mention |
  65. **Restart the gateway once after this first boot** so the new values load - the
  66. plugin's report ends with that reminder.
  67. ### Action required - the few things it can't do for you
  68. - **Persona file location** - the plugin reads your persona from
  69. `~/.hermes/SOUL.md`. If yours lives somewhere else (e.g. a Docker mount),
  70. point it there in `~/.hermes/config.yaml`:
  71. ```yaml
  72. turn_taking:
  73. soul_path: "/path/to/SOUL.md"
  74. ```
  75. - **Telegram groups** - two steps that genuinely can't be automated: disable
  76. privacy mode in @BotFather, and add the group's chat id to
  77. `TELEGRAM_GROUP_ALLOWED_CHATS`. The plugin prints both when Telegram is in use.
  78. - **A personal WhatsApp number** - the respond-to-everyone setting means the bot
  79. replies to *everyone* who messages that number, in DMs and all groups. If it's
  80. your personal number, tighten it (the plugin warns about this at setup):
  81. `WHATSAPP_ALLOW_ALL_USERS=false` and/or `WHATSAPP_GROUP_POLICY=allowlist`.
  82. - **Discord bot setup** - steps that can't be automated. Create the bot in the
  83. [Developer Portal](https://discord.com/developers/applications), enable
  84. **Message Content Intent** and **Server Members Intent**, and invite it with
  85. the `bot+applications.commands` scope and `permissions=274878286912`. Full
  86. walkthrough (intents, invite URL, env vars, auth models): the
  87. [`configure-discord-group`](skills/configure-discord-group/SKILL.md) skill.
  88. ### Overrides
  89. `~/.hermes/.env` (`Authorization: Bearer`):
  90. ```bash
  91. HUMALIKE_API_KEY=your-api-key # skips the login prompt
  92. HUMALIKE_API_URL=… # non-default environment; set EMPTY to disable turn-taking
  93. ```
  94. Optional persona knob in `~/.hermes/config.yaml` under `turn_taking:` -
  95. `soul_auto_enhance` (`true` by default: one automatic persona attempt per
  96. resolved `SOUL.md` path; set `false` to skip it).
  97. That's it - restart the gateway and message the bot. It now reads the room and
  98. replies when it has something to say.
  99. ## Platforms
  100. | Platform | Extra setup |
  101. |---|---|
  102. | WhatsApp | DMs work as-is. Groups: [`skills/configure-whatsapp-group`](skills/configure-whatsapp-group/SKILL.md) |
  103. | Telegram | DMs work as-is. Groups: [`skills/configure-telegram-group`](skills/configure-telegram-group/SKILL.md) |
  104. | Slack | DMs/@mentions work as-is. Unmentioned channel messages: [`skills/configure-slack-group`](skills/configure-slack-group/SKILL.md) |
  105. | Discord | DMs work as-is. Server channels: [`skills/configure-discord-group`](skills/configure-discord-group/SKILL.md) |
  106. ### Discord notes
  107. - **Typing indicator** - Discord's typing is a persistent refresh loop, so the
  108. plugin mutes the host's think-time typing and shows typing only while a reply
  109. bubble is being paced, with an explicit stop after the last bubble. To restore
  110. host typing during think time: `HERMES_DISCORD_MUTE_HOST_TYPING=false` (env) or
  111. `turn_taking: {discord_mute_host_typing: false}` (config.yaml).
  112. - **Captionless media** - images/files sent without text reach the service as a
  113. clean `[image]`/`[media]` marker (with `has_media`), not the host's
  114. placeholder sentence, so turn-taking knows media arrived.
  115. - **Fast message bursts** - a follow-up that arrives while the bot is composing
  116. is merged into the in-flight turn and the reply is re-stamped with the newest
  117. turn epoch, so quick "hermes" / "are you here?" bursts get an answer instead
  118. of a silently superseded one.
  119. - **Mentions** - `<@id>`/`<@!id>` tokens are resolved for the service: the bot's
  120. own mention becomes `@you`, other people become `@DisplayName`.
  121. - Slash commands (`/new`, `/sethome`, …) bypass the turn-taking gate.
  122. ## Persona: `/soul enhance`
  123. Send the bot `/soul enhance` to deepen its persona: reads `SOUL.md`, enhances
  124. it via the [Personas API](https://docs.humalike.com/api-reference/personas),
  125. backs up the old file to `SOUL.md.bak`, writes the result - effective on the
  126. next message. Needs a seed description first; a bare template is skipped. The
  127. plugin makes one automatic attempt per resolved `SOUL.md` path (disable:
  128. `soul_auto_enhance: false`); if it fails, use `/soul enhance` to retry manually.
  129. ## License
  130. MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.