From 1754bdf1e875f8f0f1702e722c64387eb2d24c2d Mon Sep 17 00:00:00 2001 From: teknium1 Date: Tue, 3 Mar 2026 19:00:09 -0800 Subject: [PATCH] docs: update AGENTS.md, README.md, and messaging.md to include interactive setup for messaging platforms Enhanced documentation to reflect the new interactive setup command for configuring messaging platforms (Telegram, Discord, Slack, WhatsApp). Updated sections in AGENTS.md, README.md, and messaging.md to provide clear instructions on using the 'hermes gateway setup' command, improving user experience and accessibility for platform configuration. --- AGENTS.md | 15 ++++++++++++++- README.md | 33 +++++++++++++++++++++------------ docs/messaging.md | 40 +++++++++++++++++++++++----------------- 3 files changed, 58 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d88fbf7ff..37af4c968 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -235,6 +235,7 @@ The unified `hermes` command provides all functionality: | `hermes update` | Update to latest (checks for new config) | | `hermes uninstall` | Uninstall (can keep configs for reinstall) | | `hermes gateway` | Start gateway (messaging + cron scheduler) | +| `hermes gateway setup` | Configure messaging platforms interactively | | `hermes gateway install` | Install gateway as system service | | `hermes cron list` | View scheduled jobs | | `hermes cron status` | Check if cron scheduler is running | @@ -245,7 +246,19 @@ The unified `hermes` command provides all functionality: ## Messaging Gateway -The gateway connects Hermes to Telegram, Discord, and WhatsApp. +The gateway connects Hermes to Telegram, Discord, Slack, and WhatsApp. + +### Setup + +The interactive setup wizard handles platform configuration: + +```bash +hermes gateway setup # Arrow-key menu of all platforms, configure tokens/allowlists/home channels +``` + +This is the recommended way to configure messaging. It shows which platforms are already set up, walks through each one interactively, and offers to start/restart the gateway service at the end. + +Platforms can also be configured manually in `~/.hermes/.env`: ### Configuration (in `~/.hermes/.env`): diff --git a/README.md b/README.md index 8d101a2eb..62fb8ab46 100644 --- a/README.md +++ b/README.md @@ -220,26 +220,36 @@ See [OpenRouter provider routing docs](https://openrouter.ai/docs/guides/routing Chat with Hermes from Telegram, Discord, Slack, or WhatsApp. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages. -### Starting the Gateway +### Setting Up Messaging Platforms + +The easiest way to configure messaging platforms is the interactive setup wizard: + +```bash +hermes gateway setup # Interactive setup for all messaging platforms +``` + +This walks you through configuring each platform with arrow-key selection, shows which platforms are already configured, and offers to start/restart the gateway service when you're done. + +You can also configure platforms manually by editing `~/.hermes/.env` directly (see platform-specific details below). + +### Gateway Commands ```bash hermes gateway # Run in foreground -hermes gateway install # Install as systemd service (Linux) -hermes gateway start # Start the systemd service -hermes gateway stop # Stop the systemd service +hermes gateway setup # Configure messaging platforms interactively +hermes gateway install # Install as systemd service (Linux) / launchd (macOS) +hermes gateway start # Start the service +hermes gateway stop # Stop the service hermes gateway status # Check service status ``` -The installer will offer to set this up automatically if it detects a bot token. - ### Telegram Setup 1. **Create a bot:** Message [@BotFather](https://t.me/BotFather) on Telegram, use `/newbot` 2. **Get your user ID:** Message [@userinfobot](https://t.me/userinfobot) — it replies with your numeric ID -3. **Configure:** +3. **Configure:** Run `hermes gateway setup` and select Telegram, or add to `~/.hermes/.env` manually: ```bash -# Add to ~/.hermes/.env: TELEGRAM_BOT_TOKEN=123456:ABC-DEF... TELEGRAM_ALLOWED_USERS=YOUR_USER_ID # Comma-separated for multiple users ``` @@ -252,10 +262,9 @@ TELEGRAM_ALLOWED_USERS=YOUR_USER_ID # Comma-separated for multiple users 2. **Enable intents:** Bot → Privileged Gateway Intents → enable Message Content Intent 3. **Get your user ID:** Enable Developer Mode in Discord settings, right-click your name → Copy ID 4. **Invite to your server:** OAuth2 → URL Generator → scopes: `bot`, `applications.commands` → permissions: Send Messages, Read Message History, Attach Files -5. **Configure:** +5. **Configure:** Run `hermes gateway setup` and select Discord, or add to `~/.hermes/.env` manually: ```bash -# Add to ~/.hermes/.env: DISCORD_BOT_TOKEN=MTIz... DISCORD_ALLOWED_USERS=YOUR_USER_ID ``` @@ -267,10 +276,9 @@ DISCORD_ALLOWED_USERS=YOUR_USER_ID 3. **Get tokens:** - Bot Token (`xoxb-...`): OAuth & Permissions → Install to Workspace - App Token (`xapp-...`): Basic Information → App-Level Tokens → Generate -4. **Configure:** +4. **Configure:** Run `hermes gateway setup` and select Slack, or add to `~/.hermes/.env` manually: ```bash -# Add to ~/.hermes/.env: SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... SLACK_ALLOWED_USERS=U01234ABCDE # Comma-separated Slack user IDs @@ -423,6 +431,7 @@ hermes uninstall # Uninstall (can keep configs for later reinstall) # Gateway (messaging + cron scheduler) hermes gateway # Run gateway in foreground +hermes gateway setup # Configure messaging platforms interactively hermes gateway install # Install as system service (messaging + cron) hermes gateway status # Check service status hermes whatsapp # Pair WhatsApp via QR code diff --git a/docs/messaging.md b/docs/messaging.md index afcebc474..021ef5e3f 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -4,27 +4,33 @@ Hermes Agent can connect to messaging platforms like Telegram, Discord, and What ## Quick Start +The easiest way to configure messaging is the interactive wizard: + ```bash -# 1. Set your bot token(s) in ~/.hermes/.env -echo 'TELEGRAM_BOT_TOKEN="your_telegram_bot_token"' >> ~/.hermes/.env -echo 'DISCORD_BOT_TOKEN="your_discord_bot_token"' >> ~/.hermes/.env - -# 2. Test the gateway (foreground) -./scripts/hermes-gateway run - -# 3. Install as a system service (runs in background) -./scripts/hermes-gateway install - -# 4. Manage the service -./scripts/hermes-gateway start -./scripts/hermes-gateway stop -./scripts/hermes-gateway restart -./scripts/hermes-gateway status +hermes gateway setup # Configure Telegram, Discord, Slack, WhatsApp ``` -**Quick test (without service install):** +This walks you through each platform with arrow-key selection, handles tokens, allowlists, and home channels, and offers to start/restart the gateway when done. + +**Or configure manually** by editing `~/.hermes/.env`: + ```bash -python cli.py --gateway # Runs in foreground, useful for debugging +# Set your bot token(s) +echo 'TELEGRAM_BOT_TOKEN="your_telegram_bot_token"' >> ~/.hermes/.env +echo 'DISCORD_BOT_TOKEN="your_discord_bot_token"' >> ~/.hermes/.env +``` + +**Then start the gateway:** + +```bash +hermes gateway # Run in foreground (useful for debugging) +hermes gateway install # Install as a system service (runs in background) + +# Manage the service +hermes gateway start +hermes gateway stop +hermes gateway restart +hermes gateway status ``` ## Architecture Overview