How-To Guide
Fix White Block Emojis in Hermes Matrix Integration
Resolve the white square emoji rendering issues that appear in Matrix/Element when using Hermes Agent.
Quick answer
White square emojis in Matrix tool-call messages are a rendering artifact from Matrix reactions and tool-progress bubbles after certain Hermes updates. Fix it by disabling reactions and setting the tool_progress mode for Matrix to a non-reacting value in config, which stops Hermes from emitting the artifacts.
After certain Hermes updates, white square emojis can appear in Matrix tool-call messages. This is a rendering issue with Matrix reactions and tool-progress artifacts. Disabling reactions and changing the tool_progress setting fixes it.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent connected to Matrix
- ☑Access to ~/.hermes/.env and config.yaml
Steps
- 1
Disable Matrix reactions
Add MATRIX_REACTIONS=false to ~/.hermes/.env
- 2
Change tool progress mode
In config.yaml, set display: platforms: matrix: tool_progress: new
- 3
Restart the gateway
hermes gateway restart to apply changes
- 4
Verify the fix
Send a message that triggers tool use and confirm blocks are gone
Pro Tips
- 💡The tool_progress: new setting uses a different display path that avoids the rendering bug
- 💡You can also set tool_progress: off to completely disable tool progress messages if they're distracting
- 💡This issue is specific to Matrix clients — Telegram and Discord are unaffected
Troubleshooting
❌ White blocks still appear after setting MATRIX_REACTIONS=false
✅ Also add the tool_progress: new setting to config.yaml. Both settings together fully resolve the issue.
❌ Can't find where to add display config
✅ Add to config.yaml at the root level: display:\n platforms:\n matrix:\n tool_progress: new
❌ Changes not taking effect
✅ Restart the gateway with 'hermes gateway restart'. The .env and config.yaml are only read at startup.
FAQ
Why do white block emojis show up in Matrix?
They're a rendering artifact from Matrix reactions and tool-progress bubbles, often appearing after a Hermes update changes how progress is displayed.
How do I get rid of them?
Disable reactions and adjust the Matrix tool_progress setting in your display/platforms config to a value that doesn't emit reaction-based progress artifacts.
Will disabling reactions break anything?
No core functionality — the agent still works fully. You lose live reaction-based progress indicators on Matrix, which is the source of the artifacts anyway.