mesh-configs/skills/devops/hermes-telegram-cli-notify/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
hermes-telegram-cli-notify	Send Telegram notifications when Hermes CLI/TUI is started from the terminal — wrapper function for ~/.bashrc	1.0.0	Hermes Agent	MIT	linux	hermes tags related_skills hermes telegram notification cli wrapper bashrc hermes-agent hermes-gateway-systemd

Hermes CLI Telegram Notification Wrapper

Send a Telegram message automatically whenever you start hermes or hermes --tui from the terminal. Useful for tracking when interactive sessions are launched.

Installation

Add to ~/.bashrc (or ~/.zshrc):

# Load Hermes env (for TELEGRAM_BOT_TOKEN)
[ -f /root/.hermes/.env ] && export $(grep -v '^#' /root/.hermes/.env | xargs) 2>/dev/null

# Hermes CLI Start → Telegram Notification
hermes() {
    local msg="🖥️ <b>Hermes CLI gestartet</b>%0AHost: $(hostname)%0AUser: $(whoami)%0ADir: $(pwd)%0ACmd: hermes $*"
    if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
        # Send notification synchronously (wait for it)
        curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
            -d chat_id="${TELEGRAM_HOME_CHANNEL:-6417835766}" \
            -d parse_mode="HTML" \
            -d text="$msg" >/dev/null 2>&1
    fi
    command hermes "$@"
}

Then reload:

source ~/.bashrc

Requirements

• TELEGRAM_BOT_TOKEN in /root/.hermes/.env (or wherever your Hermes config lives)
• TELEGRAM_HOME_CHANNEL or TELEGRAM_ALLOWED_USERS set to your chat ID
• Gateway must be running and bot connected to Telegram

How It Works

1. Bash function hermes() wraps the real hermes command
2. On invocation, sends a formatted HTML message to Telegram via Bot API
3. Then executes the real hermes command with all passed arguments
4. Uses command hermes to bypass the function and call the actual binary

Message Format

🖥️ <b>Hermes CLI gestartet</b>
Host: <hostname>
User: <username>
Dir: <current-working-directory>
Cmd: hermes <args>

Pitfalls & Gotchas

1. .bashrc Early Return Block

Most .bashrc files have [ -z "$PS1" ] && return at the top for non-interactive shells. The wrapper MUST be defined BEFORE this line, otherwise it won't work in bash -lc or scripts.

# ~/.bashrc - CORRECT ORDER
# Hermes wrapper HERE (before early return)
hermes() { ... }

# If not running interactively, don't do anything
[ -z "$PS1" ] && return

2. Environment Variables Not Loaded

The wrapper sources /root/.hermes/.env at shell startup. If the file moves or variables change, reload:

source /root/.hermes/.env && source ~/.bashrc

3. Background & vs Synchronous

Initially used & to background the curl. This caused race conditions where Hermes started before notification sent. Fix: Remove & — send synchronously (fast enough, ~100-300ms).

4. Token Not Available in Subshells

When running bash -lc 'hermes ...', the .bashrc is sourced but the early return may skip the wrapper. Ensure .bashrc structure puts wrapper before [ -z "$PS1" ] && return.

Verification

Test manually:

# Direct curl test (should appear in Telegram)
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
    -d chat_id="6417835766" \
    -d parse_mode="HTML" \
    -d text="🖥️ <b>Test</b>%0AHost: $(hostname)%0AUser: $(whoami)"

# Wrapper test
hermes --version
# Check Telegram for notification

Real-World Example (This Session)

• Goal: Notify on Telegram when hermes or hermes --tui started from terminal
• Implementation: Added wrapper to /root/.bashrc with synchronous curl
• Issue Found: Wrapper placed after [ -z "$PS1" ] && return → didn't work in bash -lc
• Fix: Moved wrapper before early return line
• Result: Notifications now sent on every CLI start

Related Skills

• hermes-agent — main Hermes configuration
• hermes-gateway-systemd — gateway service troubleshooting (bot must be running)