diff --git a/skills/autonomous-ai-agents/hermes-agent/SKILL.md b/skills/autonomous-ai-agents/hermes-agent/SKILL.md index 6d8cd1c61..bb84f69b6 100644 --- a/skills/autonomous-ai-agents/hermes-agent/SKILL.md +++ b/skills/autonomous-ai-agents/hermes-agent/SKILL.md @@ -19,7 +19,7 @@ What makes Hermes different: - **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment. - **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works. -- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 8+ other platforms with full tool access, not just chat. +- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 10+ other platforms with full tool access, not just chat. - **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically. - **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory. - **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem. @@ -148,7 +148,7 @@ hermes gateway status Check status hermes gateway setup Configure platforms ``` -Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, API Server, Webhooks, Open WebUI. +Supported platforms: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, Matrix, Mattermost, Home Assistant, DingTalk, Feishu, WeCom, BlueBubbles (iMessage), Weixin (WeChat), API Server, Webhooks. Open WebUI connects via the API Server adapter. Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ @@ -215,7 +215,7 @@ hermes insights [--days N] Usage analytics hermes update Update to latest version hermes pairing list/approve/revoke DM authorization hermes plugins list/install/remove Plugin management -hermes honcho setup/status Honcho memory integration +hermes honcho setup/status Honcho memory integration (requires honcho plugin) hermes memory setup/status/off Memory provider config hermes completion bash|zsh Shell completions hermes acp ACP server (IDE integration) @@ -269,6 +269,28 @@ Type these during an interactive chat session. /plugins List plugins (CLI) ``` +### Gateway +``` +/approve Approve a pending command (gateway) +/deny Deny a pending command (gateway) +/restart Restart gateway (gateway) +/sethome Set current chat as home channel (gateway) +/update Update Hermes to latest (gateway) +/platforms (/gateway) Show platform connection status (gateway) +``` + +### Utility +``` +/branch (/fork) Branch the current session +/btw Ephemeral side question (doesn't interrupt main task) +/fast Toggle priority/fast processing +/browser Open CDP browser connection +/history Show conversation history (CLI) +/save Save conversation to file (CLI) +/paste Attach clipboard image (CLI) +/image Attach local image file (CLI) +``` + ### Info ``` /help Show commands @@ -311,11 +333,11 @@ Edit with `hermes config edit` or `hermes config set section.key value`. | `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) | | `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) | | `display` | `skin`, `tool_progress`, `show_reasoning`, `show_cost` | -| `stt` | `enabled`, `provider` (local/groq/openai) | -| `tts` | `provider` (edge/elevenlabs/openai/kokoro/fish) | +| `stt` | `enabled`, `provider` (local/groq/openai/mistral) | +| `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts) | | `memory` | `memory_enabled`, `user_profile_enabled`, `provider` | | `security` | `tirith_enabled`, `website_blocklist` | -| `delegation` | `model`, `provider`, `max_iterations` (50) | +| `delegation` | `model`, `provider`, `base_url`, `api_key`, `max_iterations` (50), `reasoning_effort` | | `smart_model_routing` | `enabled`, `cheap_model` | | `checkpoints` | `enabled`, `max_snapshots` (50) | @@ -323,7 +345,7 @@ Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/con ### Providers -18 providers supported. Set via `hermes model` or `hermes setup`. +20+ providers supported. Set via `hermes model` or `hermes setup`. | Provider | Auth | Key env var | |----------|------|-------------| @@ -332,16 +354,23 @@ Full config reference: https://hermes-agent.nousresearch.com/docs/user-guide/con | Nous Portal | OAuth | `hermes login --provider nous` | | OpenAI Codex | OAuth | `hermes login --provider openai-codex` | | GitHub Copilot | Token | `COPILOT_GITHUB_TOKEN` | +| Google Gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | | DeepSeek | API key | `DEEPSEEK_API_KEY` | +| xAI / Grok | API key | `XAI_API_KEY` | | Hugging Face | Token | `HF_TOKEN` | | Z.AI / GLM | API key | `GLM_API_KEY` | | MiniMax | API key | `MINIMAX_API_KEY` | +| MiniMax CN | API key | `MINIMAX_CN_API_KEY` | | Kimi / Moonshot | API key | `KIMI_API_KEY` | | Alibaba / DashScope | API key | `DASHSCOPE_API_KEY` | +| Xiaomi MiMo | API key | `XIAOMI_API_KEY` | | Kilo Code | API key | `KILOCODE_API_KEY` | +| AI Gateway (Vercel) | API key | `AI_GATEWAY_API_KEY` | +| OpenCode Zen | API key | `OPENCODE_ZEN_API_KEY` | +| OpenCode Go | API key | `OPENCODE_GO_API_KEY` | +| Qwen OAuth | OAuth | `hermes login --provider qwen-oauth` | | Custom endpoint | Config | `model.base_url` + `model.api_key` in config.yaml | - -Plus: AI Gateway, OpenCode Zen, OpenCode Go, MiniMax CN, GitHub Copilot ACP. +| GitHub Copilot ACP | External | `COPILOT_CLI_PATH` or Copilot CLI | Full provider docs: https://hermes-agent.nousresearch.com/docs/integrations/providers @@ -364,7 +393,10 @@ Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable | `session_search` | Search past conversations | | `delegation` | Subagent task delegation | | `cronjob` | Scheduled task management | -| `clarify` | Ask user clarifying questions | +| `messaging` | Cross-platform message sending | +| `search` | Web search only (subset of `web`) | +| `todo` | In-session task planning and tracking | +| `rl` | Reinforcement learning tools (off by default) | | `moa` | Mixture of Agents (off by default) | | `homeassistant` | Smart home control (off by default) | @@ -382,12 +414,13 @@ Provider priority (auto-detected): 1. **Local faster-whisper** — free, no API key: `pip install faster-whisper` 2. **Groq Whisper** — free tier: set `GROQ_API_KEY` 3. **OpenAI Whisper** — paid: set `VOICE_TOOLS_OPENAI_KEY` +4. **Mistral Voxtral** — set `MISTRAL_API_KEY` Config: ```yaml stt: enabled: true - provider: local # local, groq, openai + provider: local # local, groq, openai, mistral local: model: base # tiny, base, small, medium, large-v3 ``` @@ -399,8 +432,9 @@ stt: | Edge TTS | None | Yes (default) | | ElevenLabs | `ELEVENLABS_API_KEY` | Free tier | | OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid | -| Kokoro (local) | None | Free | -| Fish Audio | `FISH_AUDIO_API_KEY` | Free tier | +| MiniMax | `MINIMAX_API_KEY` | Paid | +| Mistral (Voxtral) | `MISTRAL_API_KEY` | Paid | +| NeuTTS (local) | None (`pip install neutts[all]` + `espeak-ng`) | Free | Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`. @@ -492,7 +526,7 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305 ### Voice not working 1. Check `stt.enabled: true` in config.yaml 2. Verify provider: `pip install faster-whisper` or set API key -3. Restart gateway: `/restart` +3. In gateway: `/restart`. In CLI: exit and relaunch. ### Tool not available 1. `hermes tools` — check if toolset is enabled for your platform @@ -503,10 +537,11 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305 1. `hermes doctor` — check config and dependencies 2. `hermes login` — re-authenticate OAuth providers 3. Check `.env` has the right API key +4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot. ### Changes not taking effect - **Tools/skills:** `/reset` starts a new session with updated toolset -- **Config changes:** `/restart` reloads gateway config +- **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch. - **Code changes:** Restart the CLI or gateway process ### Skills not showing @@ -520,6 +555,23 @@ Check logs first: grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20 ``` +Common gateway problems: +- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER` +- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes). +- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway` + +### Platform-specific issues +- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents. +- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels. +- **Windows HTTP 400 "No models provided"**: Config file encoding issue (BOM). Ensure `config.yaml` is saved as UTF-8 without BOM. + +### Auxiliary models not working +If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider: +```bash +hermes config set auxiliary.vision.provider +hermes config set auxiliary.vision.model +``` + --- ## Where to Find Things @@ -557,7 +609,7 @@ hermes-agent/ ├── toolsets.py # Toolset definitions ├── cli.py # Interactive CLI (HermesCLI) ├── hermes_state.py # SQLite session store -├── agent/ # Prompt builder, compression, display, adapters +├── agent/ # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch ├── hermes_cli/ # CLI subcommands, config, setup, commands │ ├── commands.py # Slash command registry (CommandDef) │ ├── config.py # DEFAULT_CONFIG, env var definitions @@ -626,7 +678,6 @@ run_conversation(): ### Testing ```bash -source venv/bin/activate # or .venv/bin/activate python -m pytest tests/ -o 'addopts=' -q # Full suite python -m pytest tests/tools/ -q # Specific area ```