Hermes Slack Watcher

A small toolkit for using Hermes Agent as a private Slack watcher under one owner's control.

It is meant for a simple setup: Hermes can follow selected channels, keep history in SQLite, and answer only the person who owns the installation.

Support the project: Donate with PayPal

What it does:

• listen to selected Slack channels where the bot is invited;
• only obey one configured owner user;
• avoid public replies in monitored channels;
• send owner-only private Slack responses in the origin channel;
• copy answers to a private home channel so the conversation can continue;
• store monitored-channel history in local SQLite for summaries and search;
• resolve Slack user IDs to human names when the bot token has users:read;
• work without requiring Mem0, Obsidian, vector DBs, or any specific memory provider.

Requirements

• Hermes Agent already installed
• Slack workspace where you can create or install apps
• Slack bot token
• Slack app token for Socket Mode
• Python 3 if you want to use the optional local helper tools

Quick start

1. Install the skill:

hermes skills install gitlares/hermes-slack/skills/slack-hermes-watcher --yes

2. In Hermes, ask:

Use slack-hermes-watcher to configure Slack supervision.

3. Follow the setup flow:

• create the Slack app;
• enable Socket Mode;
• install the app to your workspace;
• provide the bot token and app token;
• choose the owner Slack user ID;
• choose the private home channel;
• choose monitored channels;
• verify watcher search and summaries.

Install

Install through Hermes' standard skill installer:

hermes skills install gitlares/hermes-slack/skills/slack-hermes-watcher --yes

This installs only the safe skill bundle. Hermes blocks community skills that handle secrets or local runtime changes, so the setup helpers stay outside the installed skill.

After installing, ask Hermes:

Use slack-hermes-watcher to configure Slack supervision.

The skill walks through the setup: Slack app, owner user ID, private home channel, monitored channels, watcher tools, SQLite history, memory policy, validation, and troubleshooting.

Optional helper tools

If you want a guided local setup after installing the skill, clone this repo and run the helper:

git clone git@github.com:gitlares/hermes-slack.git
cd hermes-slack
python tools/setup_wizard.py

The helper generates a Slack manifest, asks for tokens locally, resolves user and channel names, configures Hermes, installs the companion plugin, applies the supported runtime patches, validates imports, and offers to restart hermes-gateway.

It stays outside the installed skill bundle because it touches secrets and local runtime state.

Layout

skills/slack-hermes-watcher/
  SKILL.md
  references/
    slack-app-setup.md
    slack-manifest-template.md

plugin/slack_api/
  __init__.py
  plugin.yaml

tools/
  setup_wizard.py
  slack_manifest.py
  configure_env.py
  install_plugin.py
  patch_runtime.py

docs/
  hermes-runtime-behavior.md

Companion plugin tools

The optional slack_api Hermes plugin exposes:

• slack_list_channels
• slack_channel_history
• slack_search_messages
• slack_watcher_channels
• slack_watcher_recent
• slack_watcher_search
• slack_watcher_backfill
• slack_watcher_prune

What is verified already

• the skill installs through Hermes' normal skill installer;
• the installed bundle is accepted as safe;
• the public install path was tested in a clean temporary Ubuntu-based container on a separate machine;
• hermes skills inspect gitlares/hermes-slack/skills/slack-hermes-watcher works from a fresh Hermes install;
• hermes skills install gitlares/hermes-slack/skills/slack-hermes-watcher --yes completes successfully from a fresh Hermes install;
• the watcher plugin exposes the expected Slack and SQLite tools;
• the repo includes helper tooling for local setup and runtime patching;
• the prune workflow is available so the SQLite watcher does not grow forever.

Current limits

• a true clean-room test from zero on a brand-new Hermes machine is still worth doing;
• Slack setup still depends on valid app configuration and tokens from the user;
• the optional helper path uses local scripts by design, because Hermes blocks risky community skill bundles that handle secrets or patch runtime automatically.

Visible commands

Main install command:

hermes skills install gitlares/hermes-slack/skills/slack-hermes-watcher --yes

Optional guided helper:

git clone git@github.com:gitlares/hermes-slack.git
cd hermes-slack
python tools/setup_wizard.py

Validation notes

The install path was smoke-tested from a clean environment:

• fresh Hermes install in a temporary container
• hermes skills inspect gitlares/hermes-slack/skills/slack-hermes-watcher
• hermes skills install gitlares/hermes-slack/skills/slack-hermes-watcher --yes

That test confirmed the community bundle is accepted as safe and installs the expected files.

Retention

The watcher stores Slack history in SQLite, so prompt context stays clean, but the local database can still grow over time.

Use SLACK_WATCH_RETENTION_DAYS to define default retention, for example:

SLACK_WATCH_RETENTION_DAYS=30

Use slack_watcher_prune to clean old rows and optionally cap rows per channel.

Security notes

Never commit .env, Slack tokens, SQLite databases, or local Hermes configs.

The installed skill does not contain token-handling scripts. External helper tools operate locally and should be reviewed before use.

License

Released under the MIT License.