--- name: hermes-agent description: Complete guide to using and extending Hermes Agent — CLI usage, setup, configuration, spawning additional agents, gateway platforms, skills, voice, tools, profiles, and a concise contributor reference. Load this skill when helping users configure Hermes, troubleshoot issues, spawn agent instances, or make code contributions. version: 2.0.0 author: Hermes Agent + Teknium license: MIT metadata: hermes: tags: [hermes, setup, configuration, multi-agent, spawning, cli, gateway, development] homepage: https://github.com/NousResearch/hermes-agent related_skills: [claude-code, codex, opencode] --- # Hermes Agent Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, messaging platforms, and IDEs. It belongs to the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, DeepSeek, local models, and 15+ others) and runs on Linux, macOS, and WSL. 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. - **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. People use Hermes for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access. **This skill helps you work with Hermes Agent effectively** — setting it up, configuring features, spawning additional agent instances, troubleshooting issues, finding the right commands and settings, and understanding how the system works when you need to extend or contribute to it. **Docs:** https://hermes-agent.nousresearch.com/docs/ ## Quick Start ```bash # Install curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash # Interactive chat (default) hermes # Single query hermes chat -q "What is the capital of France?" # Setup wizard hermes setup # Change model/provider hermes model # Check health hermes doctor ``` --- ## CLI Reference ### Global Flags ``` hermes [flags] [command] --version, -V Show version --resume, -r SESSION Resume session by ID or title --continue, -c [NAME] Resume by name, or most recent session --worktree, -w Isolated git worktree mode (parallel agents) --skills, -s SKILL Preload skills (comma-separate or repeat) --profile, -p NAME Use a named profile --yolo Skip dangerous command approval --pass-session-id Include session ID in system prompt ``` No subcommand defaults to `chat`. ### Chat ``` hermes chat [flags] -q, --query TEXT Single query, non-interactive -m, --model MODEL Model (e.g. anthropic/claude-sonnet-4) -t, --toolsets LIST Comma-separated toolsets --provider PROVIDER Force provider (openrouter, anthropic, nous, etc.) -v, --verbose Verbose output -Q, --quiet Suppress banner, spinner, tool previews --checkpoints Enable filesystem checkpoints (/rollback) --source TAG Session source tag (default: cli) ``` ### Configuration ``` hermes setup [section] Interactive wizard (model|terminal|gateway|tools|agent) hermes model Interactive model/provider picker hermes config View current config hermes config edit Open config.yaml in $EDITOR hermes config set KEY VAL Set a config value hermes config path Print config.yaml path hermes config env-path Print .env path hermes config check Check for missing/outdated config hermes model Interactive model/provider picker # OAuth credentials in current Hermes builds: hermes auth add PROVIDER --type oauth --no-browser # Example for Codex/ChatGPT subscription device auth: hermes auth add openai-codex --type oauth --no-browser --label web-setup hermes logout Clear stored auth hermes doctor [--fix] Check dependencies and config hermes status [--all] Show component status ``` ### Tools & Skills ``` hermes tools Interactive tool enable/disable (curses UI) hermes tools list Show all tools and status hermes tools enable NAME Enable a toolset hermes tools disable NAME Disable a toolset hermes skills list List installed skills hermes skills search QUERY Search the skills hub hermes skills install ID Install a skill hermes skills inspect ID Preview without installing hermes skills config Enable/disable skills per platform hermes skills check Check for updates hermes skills update Update outdated skills hermes skills uninstall N Remove a hub skill hermes skills publish PATH Publish to registry hermes skills browse Browse all available skills hermes skills tap add REPO Add a GitHub repo as skill source ``` ### MCP Servers ``` hermes mcp serve Run Hermes as an MCP server hermes mcp add NAME Add an MCP server (--url or --command) hermes mcp remove NAME Remove an MCP server hermes mcp list List configured servers hermes mcp test NAME Test connection hermes mcp configure NAME Toggle tool selection ``` ### Gateway (Messaging Platforms) ``` hermes gateway run Start gateway foreground hermes gateway install Install as background service hermes gateway start/stop Control the service hermes gateway restart Restart the service 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, Open WebUI. Platform docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ #### Telegram bot provisioning When productizing Hermes tenants with Telegram integration, use a guided `@BotFather` token-entry wizard as the default path. The official Telegram Bot API cannot create other bots or fetch BotFather tokens. Fully automated bot creation requires acting as a Telegram **user account** through MTProto/TDLib/Telethon (QR/phone login, optional 2FA, encrypted session, scripted BotFather chat), which is sensitive and can trigger anti-automation/rate limits. Treat MTProto user-account automation as an explicit advanced option only, not the MVP/default; if implemented, use short-lived encrypted sessions and delete them after bot creation where possible. #### Interactive approval buttons vary by platform When asked whether Telegram-style approval buttons exist on another messaging platform, verify the adapter rather than assuming platform parity. In current Hermes gateway code, the rich approval path is class-method based: `gateway/run.py` calls an adapter's `send_exec_approval(...)` when present and otherwise falls back to a plain text prompt instructing `/approve`, `/approve session`, `/approve always`, or `/deny`. Known practical UX notes: - Telegram implements `send_exec_approval` with inline-keyboard buttons and callback queries. - Discord, Slack, Feishu, and Matrix also have `send_exec_approval` implementations using their native interactive/card/block mechanisms. - WhatsApp is integrated through a bridge (`whatsapp-web.js` / Baileys / Business API patterns), but the default WhatsApp adapter may not implement `send_exec_approval`; expect text-command fallback unless a backend-specific button method is added. - iMessage is via the BlueBubbles adapter. BlueBubbles supports messages, media, tapbacks, typing/read indicators, and webhook delivery, but iMessage has no Telegram-like arbitrary inline bot buttons. Use text replies, or design a careful tapback mapping (e.g. 👍 approve once, 👎 deny, ❤️ approve always) only if explicitly requested and documented. See `references/gateway-interactive-approvals.md` for the verification/search workflow and iMessage visual references. #### Gateway interactive approval/button support When asked whether a messaging platform has Telegram-like approval buttons, verify the adapter implementation rather than assuming all gateway platforms support the same UI. In the Hermes codebase, dangerous-command approval prompts use an adapter method named `send_exec_approval`; if absent, gateway falls back to plain text instructions (`/approve`, `/approve session`, `/approve always`, `/deny`). As of the current checkout: - Telegram: `send_exec_approval` with inline keyboard buttons; also callback query handling. - Discord, Slack, Feishu, Matrix: implement richer interactive approval UI. - WhatsApp: gateway adapter exists (Node bridge via WhatsApp Web/Baileys/Business API patterns), but no `send_exec_approval` method in `gateway/platforms/whatsapp.py`; expect text-command fallback unless that backend is extended. - iMessage: Hermes uses the `bluebubbles` platform adapter (BlueBubbles macOS server). It supports text/media/tapbacks/typing/read receipts, but iMessage has no Telegram-style arbitrary inline bot buttons; approvals are command/text based. Quick verification commands: ```bash grep -R "def send_exec_approval" -n ~/.hermes/hermes-agent/gateway/platforms grep -R "CallbackQueryHandler\|callback_query\|interactive" -n ~/.hermes/hermes-agent/gateway/platforms/telegram.py ~/.hermes/hermes-agent/gateway/platforms/whatsapp.py ~/.hermes/hermes-agent/gateway/platforms/bluebubbles.py ``` ### Hermes Workspace web UI deployment When deploying `hermes-workspace` against a local Hermes Agent gateway: 1. Enable the gateway HTTP API in `~/.hermes/.env`, then restart the gateway: ```bash API_SERVER_ENABLED=true API_SERVER_HOST=127.0.0.1 API_SERVER_PORT=8642 API_SERVER_KEY= hermes gateway restart curl http://127.0.0.1:8642/health ``` 2. In the workspace `.env`, point to the local API and mirror the token: ```bash HERMES_API_URL=http://127.0.0.1:8642 HERMES_API_TOKEN= HERMES_DASHBOARD_URL=http://127.0.0.1:9119 HERMES_PASSWORD= COOKIE_SECURE=1 TRUST_PROXY=1 HOST=127.0.0.1 ``` 3. Start the dashboard under PM2 via a shell wrapper, not directly as the `hermes` Python entrypoint. PM2 otherwise may run the Python script with Node and crash with `SyntaxError: Invalid or unexpected token`: ```bash pm2 start /usr/bin/bash --name hermes-dashboard -- -lc 'exec /home/USER/.local/bin/hermes dashboard --port 9119 --host 127.0.0.1 --no-open' ``` 4. Start the workspace on a loopback port and verify all layers: ```bash PORT=4024 HOST=127.0.0.1 pm2 start pnpm --name hermes-workspace --cwd /path/to/hermes-workspace -- preview --host 127.0.0.1 --port 4024 curl http://127.0.0.1:4024/api/auth-check curl http://127.0.0.1:9119/api/status ``` 5. Put nginx basic auth in front if exposing publicly, but keep the workspace app password enabled too; verify unauthenticated public root returns `401`, authenticated root returns `200`, `/api/auth-check` reports `authRequired:true`, and posting the workspace password to `/api/auth` sets a valid session. If a Nuxt/Vite workspace build dies with exit `137` or the gateway appears to stall during build, check RAM/swap and add temporary swap before rebuilding. ### Sessions ``` hermes sessions list List recent sessions hermes sessions browse Interactive picker hermes sessions export OUT Export to JSONL hermes sessions rename ID T Rename a session hermes sessions delete ID Delete a session hermes sessions prune Clean up old sessions (--older-than N days) hermes sessions stats Session store statistics ``` ### Cron Jobs ``` hermes cron list List jobs (--all for disabled) hermes cron create SCHED Create: '30m', 'every 2h', '0 9 * * *' hermes cron edit ID Edit schedule, prompt, delivery hermes cron pause/resume ID Control job state hermes cron run ID Trigger on next tick hermes cron remove ID Delete a job hermes cron status Scheduler status ``` Cron script pitfall: Hermes cron script paths must be relative filenames under `~/.hermes/scripts/`; absolute paths or `~/...` paths are rejected. For project-local scripts, create a thin wrapper in `~/.hermes/scripts/` that `exec`s the real script, then pass only the wrapper filename. Cron reset pitfall: when a user says to cancel/recreate “all current cron jobs” in the context of a specific project, scope the destructive action to that project’s jobs unless they explicitly ask for every Hermes cron globally. List jobs first, remove only the matching project jobs, preserve unrelated watchers/digests, then create the replacement jobs and verify with `hermes cron list` or the cronjob tool. Periodic progress-update pattern: keep long-running worker/orchestrator jobs `deliver=local` so they do useful work without spamming chat, and create a separate bounded reporter job with `deliver=origin` for Telegram updates. For temporary windows, set a finite repeat count (for example, every 30m for 48h = 96 repeats) and trigger both worker and reporter once with `cronjob(action='run')` after setup. Reporter prompts should inspect state/reports/git and produce mobile-readable bullets/headings rather than raw logs or tables. Self-improving app pattern: when a user asks for an app/project to “keep getting better” through Hermes, make Hermes cron the intelligence layer and the app the audit/visualization layer. Create (1) a `deliver=local` agent worker that loads the relevant project-local skills and performs research/work, (2) a no-agent deterministic script job that writes an audit/state record even when no LLM pass runs, (3) a `deliver=origin` digest reporter for concise mobile updates, and (4) if the app needs cron awareness, a no-agent snapshot bridge that writes normalized `hermes cron list --all` output into the app DB. Verify both `hermes cron list`/cronjob list and the app API/UI see the jobs. Keep script paths as relative filenames under `~/.hermes/scripts/`. ### Webhooks ``` hermes webhook subscribe N Create route at /webhooks/ hermes webhook list List subscriptions hermes webhook remove NAME Remove a subscription hermes webhook test NAME Send a test POST ``` ### Profiles ``` hermes profile list List all profiles hermes profile create NAME Create (--clone, --clone-all, --clone-from) hermes profile use NAME Set sticky default hermes profile delete NAME Delete a profile hermes profile show NAME Show details hermes profile alias NAME Manage wrapper scripts hermes profile rename A B Rename a profile hermes profile export NAME Export to tar.gz hermes profile import FILE Import from archive ``` For hosted/productized Hermes deployments, prefer a Hermes-native profile/home-per-tenant architecture first, usually wrapped in one Docker container per tenant for filesystem isolation. Do not jump to a custom central message router/shared worker design until container economics are benchmarked. See `references/hosted-hermes-profile-tenants.md` for the profile/container-per-tenant pattern, BYO provider onboarding, Telegram bot-token setup, skill bundle rollout, safety defaults, and benchmark gates. Docker tenant pitfall: the stock installer places Hermes code under `$HERMES_HOME/hermes-agent` (typically `/home/hermes/.hermes/hermes-agent`) and the `hermes` launcher points there. If you bind-mount a tenant home over that same path, you hide the installed code and break the launcher. In runner images, keep the installed code path inside the image and mount tenant state elsewhere, e.g. `-e HERMES_HOME=/data/hermes -v /srv/astral/tenants//hermes-home:/data/hermes`. ### Credential Pools ``` hermes auth add PROVIDER Add an API key or OAuth credential hermes auth add openai-codex --type oauth --no-browser --label web-setup hermes auth list [PROVIDER] List pooled credentials hermes auth remove P INDEX Remove by provider + index hermes auth reset PROVIDER Clear exhaustion status ``` OAuth/device-auth note: in current Hermes builds the old `hermes login --provider openai-codex` command may print that it has been removed. For hosted tenant/container flows, first try to run `hermes auth add openai-codex --type oauth --no-browser --label