---
name: hermes-telegram-cli-notify
description: "Send Telegram notifications when Hermes CLI/TUI is started from the terminal — wrapper function for ~/.bashrc"
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [hermes, telegram, notification, cli, wrapper, bashrc]
    related_skills: [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`):

```bash
# 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:
```bash
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

```html
🖥️ <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.

```bash
# ~/.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:
```bash
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:
```bash
# 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)