From 984f00e0b0922ebc61b1891c3251b2991173bd2d Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Fri, 13 Mar 2026 21:34:41 -0700 Subject: [PATCH] docs: expand Docusaurus coverage across CLI, tools, skills, and skins (#1232) - add code-derived reference pages for slash commands, tools, toolsets, bundled skills, and official optional skills - document the skin system and link visual theming separately from conversational personality - refresh quickstart, configuration, environment variable, and messaging docs to match current provider, gateway, and browser behavior - fix stale command, session, and Home Assistant configuration guidance --- website/docs/getting-started/quickstart.md | 13 +- website/docs/reference/cli-commands.md | 552 +++++++++++------- .../docs/reference/environment-variables.md | 60 +- .../docs/reference/optional-skills-catalog.md | 51 ++ website/docs/reference/skills-catalog.md | 243 ++++++++ website/docs/reference/slash-commands.md | 119 ++++ website/docs/reference/tools-reference.md | 163 ++++++ website/docs/reference/toolsets-reference.md | 49 ++ website/docs/user-guide/cli.md | 74 +-- website/docs/user-guide/configuration.md | 20 +- .../user-guide/features/batch-processing.md | 2 +- website/docs/user-guide/features/browser.md | 19 +- website/docs/user-guide/features/honcho.md | 2 +- website/docs/user-guide/features/mcp.md | 2 + .../docs/user-guide/features/personality.md | 12 +- website/docs/user-guide/features/skills.md | 8 + website/docs/user-guide/features/skins.md | 81 +++ website/docs/user-guide/features/tools.md | 40 +- website/docs/user-guide/messaging/discord.md | 2 +- .../user-guide/messaging/homeassistant.md | 41 +- website/docs/user-guide/messaging/index.md | 11 +- website/docs/user-guide/messaging/signal.md | 8 +- website/docs/user-guide/messaging/slack.md | 2 +- website/docs/user-guide/messaging/whatsapp.md | 43 +- website/docs/user-guide/sessions.md | 2 +- website/sidebars.ts | 6 + 26 files changed, 1228 insertions(+), 397 deletions(-) create mode 100644 website/docs/reference/optional-skills-catalog.md create mode 100644 website/docs/reference/skills-catalog.md create mode 100644 website/docs/reference/slash-commands.md create mode 100644 website/docs/reference/tools-reference.md create mode 100644 website/docs/reference/toolsets-reference.md create mode 100644 website/docs/user-guide/features/skins.md diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index eceaf73de..a4c45a301 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -44,8 +44,12 @@ hermes setup # Or configure everything at once | **Nous Portal** | Subscription-based, zero-config | OAuth login via `hermes model` | | **OpenAI Codex** | ChatGPT OAuth, uses Codex models | Device code auth via `hermes model` | | **Anthropic** | Claude models directly (Pro/Max or API key) | API key or Claude Code setup-token | -| **OpenRouter** | 200+ models, pay-per-use | Enter your API key | -| **Custom Endpoint** | VLLM, SGLang, any OpenAI-compatible API | Set base URL + API key | +| **OpenRouter** | Multi-provider routing across many models | Enter your API key | +| **Z.AI** | GLM / Zhipu-hosted models | Set `GLM_API_KEY` / `ZAI_API_KEY` | +| **Kimi / Moonshot** | Moonshot-hosted coding and chat models | Set `KIMI_API_KEY` | +| **MiniMax** | International MiniMax endpoint | Set `MINIMAX_API_KEY` | +| **MiniMax China** | China-region MiniMax endpoint | Set `MINIMAX_CN_API_KEY` | +| **Custom Endpoint** | VLLM, SGLang, or any OpenAI-compatible API | Set base URL + API key | :::tip You can switch providers at any time with `hermes model` — no code changes, no lock-in. @@ -119,7 +123,7 @@ hermes config set terminal.backend ssh # Remote server ### Connect messaging platforms -Chat with Hermes from your phone via Telegram, Discord, Slack, or WhatsApp: +Chat with Hermes from your phone or other surfaces via Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant: ```bash hermes gateway setup # Interactive platform configuration @@ -138,6 +142,7 @@ The agent will set up a cron job that runs automatically via the gateway. ```bash hermes skills search kubernetes hermes skills install openai/skills/k8s +hermes skills install official/security/1password ``` Or use the `/skills` slash command inside chat. @@ -175,5 +180,5 @@ mcp_servers: - **[CLI Guide](../user-guide/cli.md)** — Master the terminal interface - **[Configuration](../user-guide/configuration.md)** — Customize your setup -- **[Messaging Gateway](../user-guide/messaging/index.md)** — Connect Telegram, Discord, Slack, WhatsApp +- **[Messaging Gateway](../user-guide/messaging/index.md)** — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant - **[Tools & Toolsets](../user-guide/features/tools.md)** — Explore available capabilities diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 946b47b58..1348bf54c 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -1,231 +1,349 @@ --- sidebar_position: 1 title: "CLI Commands Reference" -description: "Comprehensive reference for all hermes CLI commands and slash commands" +description: "Authoritative reference for Hermes terminal commands and command families" --- # CLI Commands Reference -## Terminal Commands +This page covers the **terminal commands** you run from your shell. -These are commands you run from your shell. +For in-chat slash commands, see [Slash Commands Reference](./slash-commands.md). -### Core Commands +## Global entrypoint + +```bash +hermes [global-options] [subcommand/options] +``` + +### Global options + +| Option | Description | +|--------|-------------| +| `--version`, `-V` | Show version and exit. | +| `--resume `, `-r ` | Resume a previous session by ID or title. | +| `--continue [name]`, `-c [name]` | Resume the most recent session, or the most recent session matching a title. | +| `--worktree`, `-w` | Start in an isolated git worktree for parallel-agent workflows. | +| `--yolo` | Bypass dangerous-command approval prompts. | +| `--pass-session-id` | Include the session ID in the agent's system prompt. | + +## Top-level commands + +| Command | Purpose | +|---------|---------| +| `hermes chat` | Interactive or one-shot chat with the agent. | +| `hermes model` | Interactively choose the default provider and model. | +| `hermes gateway` | Run or manage the messaging gateway service. | +| `hermes setup` | Interactive setup wizard for all or part of the configuration. | +| `hermes whatsapp` | Configure and pair the WhatsApp bridge. | +| `hermes login` / `logout` | Authenticate with OAuth-backed providers. | +| `hermes status` | Show agent, auth, and platform status. | +| `hermes cron` | Inspect and tick the cron scheduler. | +| `hermes doctor` | Diagnose config and dependency issues. | +| `hermes config` | Show, edit, migrate, and query configuration files. | +| `hermes pairing` | Approve or revoke messaging pairing codes. | +| `hermes skills` | Browse, install, publish, audit, and configure skills. | +| `hermes honcho` | Manage Honcho cross-session memory integration. | +| `hermes tools` | Configure enabled tools per platform. | +| `hermes sessions` | Browse, export, prune, rename, and delete sessions. | +| `hermes insights` | Show token/cost/activity analytics. | +| `hermes claw` | OpenClaw migration helpers. | +| `hermes version` | Show version information. | +| `hermes update` | Pull latest code and reinstall dependencies. | +| `hermes uninstall` | Remove Hermes from the system. | + +## `hermes chat` + +```bash +hermes chat [options] +``` + +Common options: + +| Option | Description | +|--------|-------------| +| `-q`, `--query "..."` | One-shot, non-interactive prompt. | +| `-m`, `--model ` | Override the model for this run. | +| `-t`, `--toolsets ` | Enable a comma-separated set of toolsets. | +| `--provider ` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`. | +| `-v`, `--verbose` | Verbose output. | +| `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. | +| `--resume ` / `--continue [name]` | Resume a session directly from `chat`. | +| `--worktree` | Create an isolated git worktree for this run. | +| `--checkpoints` | Enable filesystem checkpoints before destructive file changes. | +| `--yolo` | Skip approval prompts. | +| `--pass-session-id` | Pass the session ID into the system prompt. | + +Examples: + +```bash +hermes +hermes chat -q "Summarize the latest PRs" +hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6 +hermes chat --toolsets web,terminal,skills +hermes chat --quiet -q "Return only JSON" +hermes chat --worktree -q "Review this repo and open a PR" +``` + +## `hermes model` + +Interactive provider + model selector. + +```bash +hermes model +``` + +Use this when you want to: +- switch default providers +- log into OAuth-backed providers during model selection +- pick from provider-specific model lists +- save the new default into config + +## `hermes gateway` + +```bash +hermes gateway +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `run` | Run the gateway in the foreground. | +| `start` | Start the installed gateway service. | +| `stop` | Stop the service. | +| `restart` | Restart the service. | +| `status` | Show service status. | +| `install` | Install as a user service (`systemd` on Linux, `launchd` on macOS). | +| `uninstall` | Remove the installed service. | +| `setup` | Interactive messaging-platform setup. | + +## `hermes setup` + +```bash +hermes setup [model|terminal|gateway|tools|agent] [--non-interactive] [--reset] +``` + +Use the full wizard or jump into one section: + +| Section | Description | +|---------|-------------| +| `model` | Provider and model setup. | +| `terminal` | Terminal backend and sandbox setup. | +| `gateway` | Messaging platform setup. | +| `tools` | Enable/disable tools per platform. | +| `agent` | Agent behavior settings. | + +Options: + +| Option | Description | +|--------|-------------| +| `--non-interactive` | Use defaults / environment values without prompts. | +| `--reset` | Reset configuration to defaults before setup. | + +## `hermes whatsapp` + +```bash +hermes whatsapp +``` + +Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing. + +## `hermes login` / `hermes logout` + +```bash +hermes login [--provider nous|openai-codex] [--portal-url ...] [--inference-url ...] +hermes logout [--provider nous|openai-codex] +``` + +`login` supports: +- Nous Portal OAuth/device flow +- OpenAI Codex OAuth/device flow + +Useful options for `login`: +- `--no-browser` +- `--timeout ` +- `--ca-bundle ` +- `--insecure` + +## `hermes status` + +```bash +hermes status [--all] [--deep] +``` + +| Option | Description | +|--------|-------------| +| `--all` | Show all details in a shareable redacted format. | +| `--deep` | Run deeper checks that may take longer. | + +## `hermes cron` + +```bash +hermes cron +``` + +| Subcommand | Description | +|------------|-------------| +| `list` | Show scheduled jobs. | +| `status` | Check whether the cron scheduler is running. | +| `tick` | Run due jobs once and exit. | + +## `hermes doctor` + +```bash +hermes doctor [--fix] +``` + +| Option | Description | +|--------|-------------| +| `--fix` | Attempt automatic repairs where possible. | + +## `hermes config` + +```bash +hermes config +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `show` | Show current config values. | +| `edit` | Open `config.yaml` in your editor. | +| `set ` | Set a config value. | +| `path` | Print the config file path. | +| `env-path` | Print the `.env` file path. | +| `check` | Check for missing or stale config. | +| `migrate` | Add newly introduced options interactively. | + +## `hermes pairing` + +```bash +hermes pairing +``` + +| Subcommand | Description | +|------------|-------------| +| `list` | Show pending and approved users. | +| `approve ` | Approve a pairing code. | +| `revoke ` | Revoke a user's access. | +| `clear-pending` | Clear pending pairing codes. | + +## `hermes skills` + +```bash +hermes skills +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `browse` | Paginated browser for skill registries. | +| `search` | Search skill registries. | +| `install` | Install a skill. | +| `inspect` | Preview a skill without installing it. | +| `list` | List installed skills. | +| `audit` | Re-scan installed hub skills. | +| `uninstall` | Remove a hub-installed skill. | +| `publish` | Publish a skill to a registry. | +| `snapshot` | Export/import skill configurations. | +| `tap` | Manage custom skill sources. | +| `config` | Interactive enable/disable configuration for skills by platform. | + +Common examples: + +```bash +hermes skills browse +hermes skills browse --source official +hermes skills search kubernetes +hermes skills inspect official/security/1password +hermes skills install official/migration/openclaw-migration +hermes skills config +``` + +## `hermes honcho` + +```bash +hermes honcho +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `setup` | Interactive Honcho setup wizard. | +| `status` | Show current Honcho config and connection status. | +| `sessions` | List known Honcho session mappings. | +| `map` | Map the current directory to a Honcho session name. | +| `peer` | Show or update peer names and dialectic reasoning level. | +| `mode` | Show or set memory mode: `hybrid`, `honcho`, or `local`. | +| `tokens` | Show or set token budgets for context and dialectic. | +| `identity` | Seed or show the AI peer identity representation. | +| `migrate` | Migration guide from openclaw-honcho to Hermes Honcho. | + +## `hermes tools` + +```bash +hermes tools [--summary] +``` + +| Option | Description | +|--------|-------------| +| `--summary` | Print the current enabled-tools summary and exit. | + +Without `--summary`, this launches the interactive per-platform tool configuration UI. + +## `hermes sessions` + +```bash +hermes sessions +``` + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `list` | List recent sessions. | +| `browse` | Interactive session picker with search and resume. | +| `export [--session-id ID]` | Export sessions to JSONL. | +| `delete ` | Delete one session. | +| `prune` | Delete old sessions. | +| `stats` | Show session-store statistics. | +| `rename ` | Set or change a session title. | + +## `hermes insights` + +```bash +hermes insights [--days N] [--source platform] +``` + +| Option | Description | +|--------|-------------| +| `--days <n>` | Analyze the last `n` days (default: 30). | +| `--source <platform>` | Filter by source such as `cli`, `telegram`, or `discord`. | + +## `hermes claw` + +```bash +hermes claw migrate +``` + +Used to migrate settings, memories, skills, and keys from OpenClaw to Hermes. + +## Maintenance commands | Command | Description | |---------|-------------| -| `hermes` | Start interactive chat (default) | -| `hermes chat -q "Hello"` | Single query mode (non-interactive) | -| `hermes chat --continue` / `-c` | Resume the most recent session | -| `hermes chat -c "my project"` | Resume a session by name (latest in lineage) | -| `hermes chat --resume <id>` / `-r <id>` | Resume a specific session by ID or title | -| `hermes chat --model <name>` | Use a specific model | -| `hermes chat --provider <name>` | Force a provider (`nous`, `openrouter`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`) | -| `hermes chat --toolsets "web,terminal"` / `-t` | Use specific toolsets | -| `hermes chat --verbose` | Enable verbose/debug output | -| `hermes --worktree` / `-w` | Start in an isolated git worktree (for parallel agents) | -| `hermes --checkpoints` | Enable filesystem checkpoints before destructive file operations | +| `hermes version` | Print version information. | +| `hermes update` | Pull latest changes and reinstall dependencies. | +| `hermes uninstall [--full] [--yes]` | Remove Hermes, optionally deleting all config/data. | -### Provider & Model Management +## See also -| Command | Description | -|---------|-------------| -| `hermes model` | Switch provider and model interactively | -| `hermes login` | OAuth login to a provider (use `--provider` to specify) | -| `hermes logout` | Clear provider authentication | - -### Configuration - -| Command | Description | -|---------|-------------| -| `hermes setup` | Full setup wizard — configures provider, model, terminal, and messaging all at once | -| `hermes config` | View current configuration | -| `hermes config edit` | Open config.yaml in your editor | -| `hermes config set KEY VAL` | Set a specific value | -| `hermes config check` | Check for missing config (useful after updates) | -| `hermes config migrate` | Interactively add missing options | -| `hermes tools` | Interactive tool configuration per platform | -| `hermes status` | Show configuration status (including auth) | -| `hermes doctor` | Diagnose issues | - -### Maintenance - -| Command | Description | -|---------|-------------| -| `hermes update` | Update to latest version | -| `hermes uninstall` | Uninstall (can keep configs for later reinstall) | -| `hermes version` | Show version info | - -### Gateway (Messaging + Cron) - -| Command | Description | -|---------|-------------| -| `hermes gateway` | Run gateway in foreground | -| `hermes gateway setup` | Configure messaging platforms interactively | -| `hermes gateway install` | Install as system service (Linux/macOS) | -| `hermes gateway start` | Start the service | -| `hermes gateway stop` | Stop the service | -| `hermes gateway restart` | Restart the service | -| `hermes gateway status` | Check service status | -| `hermes gateway uninstall` | Uninstall the system service | -| `hermes whatsapp` | Pair WhatsApp via QR code | - -### Skills - -| Command | Description | -|---------|-------------| -| `hermes skills browse` | Browse all available skills with pagination (official first) | -| `hermes skills search <query>` | Search skill registries | -| `hermes skills install <identifier>` | Install a skill (with security scan) | -| `hermes skills inspect <identifier>` | Preview before installing | -| `hermes skills list` | List installed skills | -| `hermes skills list --source hub` | List hub-installed skills only | -| `hermes skills audit` | Re-scan all hub skills | -| `hermes skills uninstall <name>` | Remove a hub skill | -| `hermes skills publish <path> --to github --repo owner/repo` | Publish a skill | -| `hermes skills snapshot export <file>` | Export skill config | -| `hermes skills snapshot import <file>` | Import from snapshot | -| `hermes skills tap add <repo>` | Add a custom source | -| `hermes skills tap remove <repo>` | Remove a source | -| `hermes skills tap list` | List custom sources | - -### Cron & Pairing - -| Command | Description | -|---------|-------------| -| `hermes cron list` | View scheduled jobs | -| `hermes cron status` | Check if cron scheduler is running | -| `hermes cron tick` | Manually trigger a cron tick | -| `hermes pairing list` | View pending + approved users | -| `hermes pairing approve <platform> <code>` | Approve a pairing code | -| `hermes pairing revoke <platform> <user_id>` | Remove user access | -| `hermes pairing clear-pending` | Clear all pending pairing requests | - -### Sessions - -| Command | Description | -|---------|-------------| -| `hermes sessions list` | Browse past sessions (shows title, preview, last active) | -| `hermes sessions rename <id> <title>` | Set or change a session's title | -| `hermes sessions export <id>` | Export a session | -| `hermes sessions delete <id>` | Delete a specific session | -| `hermes sessions prune` | Remove old sessions | -| `hermes sessions stats` | Show session statistics | - -### Insights - -| Command | Description | -|---------|-------------| -| `hermes insights` | Show usage analytics for the last 30 days | -| `hermes insights --days 7` | Analyze a custom time window | -| `hermes insights --source telegram` | Filter by platform | - ---- - -## Slash Commands (Inside Chat) - -Type `/` in the interactive CLI to see an autocomplete dropdown. - -### Navigation & Control - -| Command | Description | -|---------|-------------| -| `/help` | Show available commands | -| `/quit` | Exit the CLI (aliases: `/exit`, `/q`) | -| `/clear` | Clear screen and reset conversation | -| `/new` | Start a new conversation | -| `/reset` | Reset conversation only (keep screen) | - -### Tools & Configuration - -| Command | Description | -|---------|-------------| -| `/tools` | List all available tools | -| `/toolsets` | List available toolsets | -| `/model [provider:model]` | Show or change the current model (supports `provider:model` syntax to switch providers) | -| `/provider` | Show available providers with auth status | -| `/config` | Show current configuration | -| `/prompt [text]` | View/set custom system prompt | -| `/personality [name]` | Set a predefined personality | -| `/reasoning [arg]` | Manage reasoning effort and display. Args: effort level (`none`, `low`, `medium`, `high`, `xhigh`) or display toggle (`show`, `hide`). No args shows current state. | - -### Conversation - -| Command | Description | -|---------|-------------| -| `/history` | Show conversation history | -| `/retry` | Retry the last message | -| `/undo` | Remove the last user/assistant exchange | -| `/save` | Save the current conversation | -| `/compress` | Manually compress conversation context | -| `/title [name]` | Set or show the current session's title | -| `/usage` | Show token usage for this session | -| `/insights [--days N]` | Show usage insights and analytics (last 30 days) | - -#### /compress - -Manually triggers context compression on the current conversation. This summarizes middle turns of the conversation while preserving the first 3 and last 4 turns, significantly reducing token count. Useful when: - -- The conversation is getting long and you want to reduce costs -- You're approaching the model's context limit -- You want to continue the conversation without starting fresh - -Requirements: at least 4 messages in the conversation. The configured model (or `compression.summary_model` from config) is used to generate the summary. After compression, the session continues seamlessly with the compressed history. - -Reports the result as: `Compressed: X → Y messages, ~N → ~M tokens`. - -:::tip -Compression also happens automatically when approaching context limits (configurable via `compression.threshold` in `config.yaml`). Use `/compress` when you want to trigger it early. -::: - -### Media & Input - -| Command | Description | -|---------|-------------| -| `/paste` | Check clipboard for an image and attach it (see [Vision & Image Paste](/docs/user-guide/features/vision)) | - -### Skills & Scheduling - -| Command | Description | -|---------|-------------| -| `/cron` | Manage scheduled tasks | -| `/skills` | Browse, search, install, inspect, or manage skills | -| `/platforms` | Show gateway/messaging platform status | -| `/verbose` | Cycle tool progress: off → new → all → verbose | -| `/<skill-name>` | Invoke any installed skill | - -### Gateway-Only Commands - -These work in messaging platforms (Telegram, Discord, Slack, WhatsApp) but not the interactive CLI: - -| Command | Description | -|---------|-------------| -| `/stop` | Stop the running agent (no follow-up message) | -| `/sethome` | Set this chat as the home channel | -| `/status` | Show session info | -| `/reload-mcp` | Reload MCP servers from config | -| `/rollback` | List filesystem checkpoints for the current directory | -| `/rollback <N>` | Restore files to checkpoint #N | -| `/update` | Update Hermes Agent to the latest version | - ---- - -## Keybindings - -| Key | Action | -|-----|--------| -| `Enter` | Send message | -| `Alt+Enter` / `Ctrl+J` | New line (multi-line input) | -| `Alt+V` | Paste image from clipboard (see [Vision & Image Paste](/docs/user-guide/features/vision)) | -| `Ctrl+V` | Paste text + auto-check for clipboard image | -| `Ctrl+C` | Clear input/images, interrupt agent, or exit (contextual) | -| `Ctrl+D` | Exit | -| `Tab` | Autocomplete slash commands | - -:::tip -Commands are case-insensitive — `/HELP` works the same as `/help`. -::: - -:::info Image paste keybindings -`Alt+V` works in most terminals but **not** in VSCode's integrated terminal (VSCode intercepts Alt+key combos). `Ctrl+V` only triggers an image check when the clipboard also contains text (terminals don't send paste events for image-only clipboard). The `/paste` command is the universal fallback. See the [full compatibility table](/docs/user-guide/features/vision#platform-compatibility). -::: +- [Slash Commands Reference](./slash-commands.md) +- [CLI Interface](../user-guide/cli.md) +- [Sessions](../user-guide/sessions.md) +- [Skills System](../user-guide/features/skills.md) +- [Skins & Themes](../user-guide/features/skins.md) diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 6cecf2ac6..f179437a2 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -13,9 +13,12 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | Variable | Description | |----------|-------------| | `OPENROUTER_API_KEY` | OpenRouter API key (recommended for flexibility) | +| `OPENROUTER_BASE_URL` | Override the OpenRouter-compatible base URL | | `OPENAI_API_KEY` | API key for custom OpenAI-compatible endpoints (used with `OPENAI_BASE_URL`) | | `OPENAI_BASE_URL` | Base URL for custom endpoint (VLLM, SGLang, etc.) | | `GLM_API_KEY` | z.ai / ZhipuAI GLM API key ([z.ai](https://z.ai)) | +| `ZAI_API_KEY` | Alias for `GLM_API_KEY` | +| `Z_AI_API_KEY` | Alias for `GLM_API_KEY` | | `GLM_BASE_URL` | Override z.ai base URL (default: `https://api.z.ai/api/paas/v4`) | | `KIMI_API_KEY` | Kimi / Moonshot AI API key ([moonshot.ai](https://platform.moonshot.ai)) | | `KIMI_BASE_URL` | Override Kimi base URL (default: `https://api.moonshot.ai/v1`) | @@ -35,11 +38,14 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | Variable | Description | |----------|-------------| -| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn` (default: `auto`) | +| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn` (default: `auto`) | | `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) | | `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL | | `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) | +| `HERMES_NOUS_TIMEOUT_SECONDS` | HTTP timeout for Nous credential / token flows | | `HERMES_DUMP_REQUESTS` | Dump API request payloads to log files (`true`/`false`) | +| `HERMES_PREFILL_MESSAGES_FILE` | Path to a JSON file of ephemeral prefill messages injected at API-call time | +| `HERMES_TIMEZONE` | IANA timezone override (for example `America/New_York`) | ## Tool APIs @@ -96,37 +102,55 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | Variable | Description | |----------|-------------| | `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) | -| `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs allowed to use bot | -| `TELEGRAM_HOME_CHANNEL` | Default channel for cron delivery | -| `TELEGRAM_HOME_CHANNEL_NAME` | Display name for home channel | +| `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs allowed to use the bot | +| `TELEGRAM_HOME_CHANNEL` | Default Telegram chat/channel for cron delivery | +| `TELEGRAM_HOME_CHANNEL_NAME` | Display name for the Telegram home channel | | `DISCORD_BOT_TOKEN` | Discord bot token | -| `DISCORD_ALLOWED_USERS` | Comma-separated user IDs allowed to use bot | -| `DISCORD_HOME_CHANNEL` | Default channel for cron delivery | -| `DISCORD_HOME_CHANNEL_NAME` | Display name for home channel | +| `DISCORD_ALLOWED_USERS` | Comma-separated Discord user IDs allowed to use the bot | +| `DISCORD_HOME_CHANNEL` | Default Discord channel for cron delivery | +| `DISCORD_HOME_CHANNEL_NAME` | Display name for the Discord home channel | +| `DISCORD_REQUIRE_MENTION` | Require an @mention before responding in server channels | +| `DISCORD_FREE_RESPONSE_CHANNELS` | Comma-separated channel IDs where mention is not required | +| `DISCORD_AUTO_THREAD` | Auto-thread long replies when supported | | `SLACK_BOT_TOKEN` | Slack bot token (`xoxb-...`) | | `SLACK_APP_TOKEN` | Slack app-level token (`xapp-...`, required for Socket Mode) | | `SLACK_ALLOWED_USERS` | Comma-separated Slack user IDs | | `SLACK_HOME_CHANNEL` | Default Slack channel for cron delivery | -| `WHATSAPP_ENABLED` | Enable WhatsApp bridge (`true`/`false`) | +| `SLACK_HOME_CHANNEL_NAME` | Display name for the Slack home channel | +| `WHATSAPP_ENABLED` | Enable the WhatsApp bridge (`true`/`false`) | | `WHATSAPP_MODE` | `bot` (separate number) or `self-chat` (message yourself) | -| `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code) | -| `SIGNAL_HTTP_URL` | signal-cli daemon HTTP endpoint (e.g., `http://127.0.0.1:8080`) | -| `SIGNAL_ACCOUNT` | Bot phone number in E.164 format (e.g., `+15551234567`) | +| `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code, no `+`) | +| `SIGNAL_HTTP_URL` | signal-cli daemon HTTP endpoint (for example `http://127.0.0.1:8080`) | +| `SIGNAL_ACCOUNT` | Bot phone number in E.164 format | | `SIGNAL_ALLOWED_USERS` | Comma-separated E.164 phone numbers or UUIDs | -| `SIGNAL_GROUP_ALLOWED_USERS` | Comma-separated group IDs, or `*` for all groups (omit to disable groups) | +| `SIGNAL_GROUP_ALLOWED_USERS` | Comma-separated group IDs, or `*` for all groups | +| `SIGNAL_HOME_CHANNEL_NAME` | Display name for the Signal home channel | +| `SIGNAL_IGNORE_STORIES` | Ignore Signal stories/status updates | +| `SIGNAL_ALLOW_ALL_USERS` | Allow all Signal users without an allowlist | +| `EMAIL_ADDRESS` | Email address for the Email gateway adapter | +| `EMAIL_PASSWORD` | Password or app password for the email account | +| `EMAIL_IMAP_HOST` | IMAP hostname for the email adapter | +| `EMAIL_IMAP_PORT` | IMAP port | +| `EMAIL_SMTP_HOST` | SMTP hostname for the email adapter | +| `EMAIL_SMTP_PORT` | SMTP port | +| `EMAIL_ALLOWED_USERS` | Comma-separated email addresses allowed to message the bot | +| `EMAIL_HOME_ADDRESS` | Default recipient for proactive email delivery | +| `EMAIL_HOME_ADDRESS_NAME` | Display name for the email home target | +| `EMAIL_POLL_INTERVAL` | Email polling interval in seconds | +| `EMAIL_ALLOW_ALL_USERS` | Allow all inbound email senders | | `HASS_TOKEN` | Home Assistant Long-Lived Access Token (enables HA platform + tools) | | `HASS_URL` | Home Assistant URL (default: `http://homeassistant.local:8123`) | -| `MESSAGING_CWD` | Working directory for terminal in messaging (default: `~`) | +| `MESSAGING_CWD` | Working directory for terminal commands in messaging mode (default: `~`) | | `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms | -| `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlist (`true`/`false`, default: `false`) | +| `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlists (`true`/`false`, default: `false`) | ## Agent Behavior | Variable | Description | |----------|-------------| | `HERMES_MAX_ITERATIONS` | Max tool-calling iterations per conversation (default: 60) | -| `HERMES_TOOL_PROGRESS` | Send progress messages when using tools (`true`/`false`) | -| `HERMES_TOOL_PROGRESS_MODE` | `all` (every call, default) or `new` (only when tool changes) | +| `HERMES_TOOL_PROGRESS` | Deprecated compatibility variable for tool progress display. Prefer `display.tool_progress` in `config.yaml`. | +| `HERMES_TOOL_PROGRESS_MODE` | Deprecated compatibility variable for tool progress mode. Prefer `display.tool_progress` in `config.yaml`. | | `HERMES_HUMAN_DELAY_MODE` | Response pacing: `off`/`natural`/`custom` | | `HERMES_HUMAN_DELAY_MIN_MS` | Custom delay range minimum (ms) | | `HERMES_HUMAN_DELAY_MAX_MS` | Custom delay range maximum (ms) | @@ -138,7 +162,7 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | Variable | Description | |----------|-------------| -| `SESSION_IDLE_MINUTES` | Reset sessions after N minutes of inactivity (default: 120) | +| `SESSION_IDLE_MINUTES` | Reset sessions after N minutes of inactivity (default: 1440) | | `SESSION_RESET_HOUR` | Daily reset hour in 24h format (default: 4 = 4am) | ## Context Compression @@ -146,7 +170,7 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config | Variable | Description | |----------|-------------| | `CONTEXT_COMPRESSION_ENABLED` | Enable auto-compression (default: `true`) | -| `CONTEXT_COMPRESSION_THRESHOLD` | Trigger at this % of limit (default: 0.85) | +| `CONTEXT_COMPRESSION_THRESHOLD` | Trigger at this % of limit (default: 0.50) | | `CONTEXT_COMPRESSION_MODEL` | Model for summaries | ## Provider Routing (config.yaml only) diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md new file mode 100644 index 000000000..212c49c0f --- /dev/null +++ b/website/docs/reference/optional-skills-catalog.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 6 +title: "Official Optional Skills Catalog" +description: "Catalog of official optional skills available from the repository" +--- + +# Official Optional Skills Catalog + +Official optional skills live in the repository under `optional-skills/`. Install them with `hermes skills install official/<category>/<skill>` or browse them with `hermes skills browse --source official`. + +## autonomous-ai-agents + +| Skill | Description | Path | +|-------|-------------|------| +| `blackbox` | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. | `autonomous-ai-agents/blackbox` | + +## blockchain + +| Skill | Description | Path | +|-------|-------------|------| +| `solana` | Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required. | `blockchain/solana` | + +## email + +| Skill | Description | Path | +|-------|-------------|------| +| `agentmail` | Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to). | `email/agentmail` | + +## health + +| Skill | Description | Path | +|-------|-------------|------| +| `neuroskill-bci` | Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2/S or Open… | `health/neuroskill-bci` | + +## migration + +| Skill | Description | Path | +|-------|-------------|------| +| `openclaw-migration` | Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports exactly what could not be migrated and why. | `migration/openclaw-migration` | + +## research + +| Skill | Description | Path | +|-------|-------------|------| +| `qmd` | Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration. | `research/qmd` | + +## security + +| Skill | Description | Path | +|-------|-------------|------| +| `1password` | Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in, and reading/injecting secrets for commands. | `security/1password` | diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md new file mode 100644 index 000000000..1be8a5f38 --- /dev/null +++ b/website/docs/reference/skills-catalog.md @@ -0,0 +1,243 @@ +--- +sidebar_position: 5 +title: "Bundled Skills Catalog" +description: "Catalog of bundled skills that ship with Hermes Agent" +--- + +# Bundled Skills Catalog + +Hermes ships with a large built-in skill library copied into `~/.hermes/skills/` on install. This page catalogs the bundled skills that live in the repository under `skills/`. + +## apple + +Apple/macOS-specific skills — iMessage, Reminders, Notes, FindMy, and macOS automation. These skills only load on macOS systems. + +| Skill | Description | Path | +|-------|-------------|------| +| `apple-notes` | Manage Apple Notes via the memo CLI on macOS (create, view, search, edit). | `apple/apple-notes` | +| `apple-reminders` | Manage Apple Reminders via remindctl CLI (list, add, complete, delete). | `apple/apple-reminders` | +| `findmy` | Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture. | `apple/findmy` | +| `imessage` | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple/imessage` | + +## autonomous-ai-agents + +Skills for spawning and orchestrating autonomous AI coding agents and multi-agent workflows — running independent agent processes, delegating tasks, and coordinating parallel workstreams. + +| Skill | Description | Path | +|-------|-------------|------| +| `claude-code` | Delegate coding tasks to Claude Code (Anthropic's CLI agent). Use for building features, refactoring, PR reviews, and iterative coding. Requires the claude CLI installed. | `autonomous-ai-agents/claude-code` | +| `codex` | Delegate coding tasks to OpenAI Codex CLI agent. Use for building features, refactoring, PR reviews, and batch issue fixing. Requires the codex CLI and a git repository. | `autonomous-ai-agents/codex` | +| `hermes-agent-spawning` | Spawn additional Hermes Agent instances as autonomous subprocesses for independent long-running tasks. Supports non-interactive one-shot mode (-q) and interactive PTY mode for multi-turn collaboration. Different from delegate_task — this runs a full separate hermes process. | `autonomous-ai-agents/hermes-agent` | +| `opencode` | Delegate coding tasks to OpenCode CLI agent for feature implementation, refactoring, PR review, and long-running autonomous sessions. Requires the opencode CLI installed and authenticated. | `autonomous-ai-agents/opencode` | + +## creative + +Creative content generation — ASCII art, hand-drawn style diagrams, and visual design tools. + +| Skill | Description | Path | +|-------|-------------|------| +| `ascii-art` | Generate ASCII art using pyfiglet (571 fonts), cowsay, boxes, toilet, image-to-ascii, remote APIs (asciified, ascii.co.uk), and LLM fallback. No API keys required. | `creative/ascii-art` | +| `ascii-video` | "Production pipeline for ASCII art video — any format. Converts video/audio/images/generative input into colored ASCII character video output (MP4, GIF, image sequence). Covers: video-to-ASCII conversion, audio-reactive music visualizers, generative ASCII art animations, hybrid… | `creative/ascii-video` | +| `excalidraw` | Create hand-drawn style diagrams using Excalidraw JSON format. Generate .excalidraw files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links. | `creative/excalidraw` | + +## dogfood + +| Skill | Description | Path | +|-------|-------------|------| +| `dogfood` | Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports | `dogfood` | + +## email + +Skills for sending, receiving, searching, and managing email from the terminal. + +| Skill | Description | Path | +|-------|-------------|------| +| `himalaya` | CLI to manage emails via IMAP/SMTP. Use himalaya to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language). | `email/himalaya` | + +## gaming + +Skills for setting up, configuring, and managing game servers, modpacks, and gaming-related infrastructure. + +| Skill | Description | Path | +|-------|-------------|------| +| `minecraft-modpack-server` | Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts. | `gaming/minecraft-modpack-server` | +| `pokemon-player` | Play Pokemon games autonomously via headless emulation. Starts a game server, reads structured game state from RAM, makes strategic decisions, and sends button inputs — all from the terminal. | `gaming/pokemon-player` | + +## github + +GitHub workflow skills for managing repositories, pull requests, code reviews, issues, and CI/CD pipelines using the gh CLI and git via terminal. + +| Skill | Description | Path | +|-------|-------------|------| +| `codebase-inspection` | Inspect and analyze codebases using pygount for LOC counting, language breakdown, and code-vs-comment ratios. Use when asked to check lines of code, repo size, language composition, or codebase stats. | `github/codebase-inspection` | +| `github-auth` | Set up GitHub authentication for the agent using git (universally available) or the gh CLI. Covers HTTPS tokens, SSH keys, credential helpers, and gh auth — with a detection flow to pick the right method automatically. | `github/github-auth` | +| `github-code-review` | Review code changes by analyzing git diffs, leaving inline comments on PRs, and performing thorough pre-push review. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-code-review` | +| `github-issues` | Create, manage, triage, and close GitHub issues. Search existing issues, add labels, assign people, and link to PRs. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-issues` | +| `github-pr-workflow` | Full pull request lifecycle — create branches, commit changes, open PRs, monitor CI status, auto-fix failures, and merge. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-pr-workflow` | +| `github-repo-management` | Clone, create, fork, configure, and manage GitHub repositories. Manage remotes, secrets, releases, and workflows. Works with gh CLI or falls back to git + GitHub REST API via curl. | `github/github-repo-management` | + +## leisure + +| Skill | Description | Path | +|-------|-------------|------| +| `find-nearby` | Find nearby places (restaurants, cafes, bars, pharmacies, etc.) using OpenStreetMap. Works with coordinates, addresses, cities, zip codes, or Telegram location pins. No API keys needed. | `leisure/find-nearby` | + +## mcp + +Skills for working with MCP (Model Context Protocol) servers, tools, and integrations. Includes the built-in native MCP client (configure servers in config.yaml for automatic tool discovery) and the mcporter CLI bridge for ad-hoc server interaction. + +| Skill | Description | Path | +|-------|-------------|------| +| `mcporter` | Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation. | `mcp/mcporter` | +| `native-mcp` | Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection. | `mcp/native-mcp` | + +## media + +Skills for working with media content — YouTube transcripts, GIF search, music generation, and audio visualization. + +| Skill | Description | Path | +|-------|-------------|------| +| `gif-search` | Search and download GIFs from Tenor using curl. No dependencies beyond curl and jq. Useful for finding reaction GIFs, creating visual content, and sending GIFs in chat. | `media/gif-search` | +| `heartmula` | Set up and run HeartMuLa, the open-source music generation model family (Suno-like). Generates full songs from lyrics + tags with multilingual support. | `media/heartmula` | +| `songsee` | Generate spectrograms and audio feature visualizations (mel, chroma, MFCC, tempogram, etc.) from audio files via CLI. Useful for audio analysis, music production debugging, and visual documentation. | `media/songsee` | +| `youtube-content` | Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts). | `media/youtube-content` | + +## mlops/cloud + +GPU cloud providers and serverless compute platforms for ML workloads. + +| Skill | Description | Path | +|-------|-------------|------| +| `lambda-labs-gpu-cloud` | Reserved and on-demand GPU cloud instances for ML training and inference. Use when you need dedicated GPU instances with simple SSH access, persistent filesystems, or high-performance multi-node clusters for large-scale training. | `mlops/cloud/lambda-labs` | +| `modal-serverless-gpu` | Serverless GPU cloud platform for running ML workloads. Use when you need on-demand GPU access without infrastructure management, deploying ML models as APIs, or running batch jobs with automatic scaling. | `mlops/cloud/modal` | + +## mlops/evaluation + +Model evaluation benchmarks, experiment tracking, data curation, tokenizers, and interpretability tools. + +| Skill | Description | Path | +|-------|-------------|------| +| `evaluating-llms-harness` | Evaluates LLMs across 60+ academic benchmarks (MMLU, HumanEval, GSM8K, TruthfulQA, HellaSwag). Use when benchmarking model quality, comparing models, reporting academic results, or tracking training progress. Industry standard used by EleutherAI, HuggingFace, and major labs. Sup… | `mlops/evaluation/lm-evaluation-harness` | +| `huggingface-tokenizers` | Fast tokenizers optimized for research and production. Rust-based implementation tokenizes 1GB in <20 seconds. Supports BPE, WordPiece, and Unigram algorithms. Train custom vocabularies, track alignments, handle padding/truncation. Integrates seamlessly with transformers. Use… | `mlops/evaluation/huggingface-tokenizers` | +| `nemo-curator` | GPU-accelerated data curation for LLM training. Supports text/image/video/audio. Features fuzzy deduplication (16× faster), quality filtering (30+ heuristics), semantic deduplication, PII redaction, NSFW detection. Scales across GPUs with RAPIDS. Use for preparing high-quality t… | `mlops/evaluation/nemo-curator` | +| `sparse-autoencoder-training` | Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features. Use when discovering interpretable features, analyzing superposition, or studying monosemantic representations in language m… | `mlops/evaluation/saelens` | +| `weights-and-biases` | Track ML experiments with automatic logging, visualize training in real-time, optimize hyperparameters with sweeps, and manage model registry with W&B - collaborative MLOps platform | `mlops/evaluation/weights-and-biases` | + +## mlops/inference + +Model serving, quantization (GGUF/GPTQ), structured output, inference optimization, and model surgery tools for deploying and running LLMs. + +| Skill | Description | Path | +|-------|-------------|------| +| `gguf-quantization` | GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements. | `mlops/inference/gguf` | +| `guidance` | Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework | `mlops/inference/guidance` | +| `instructor` | Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library | `mlops/inference/instructor` | +| `llama-cpp` | Runs LLM inference on CPU, Apple Silicon, and consumer GPUs without NVIDIA hardware. Use for edge deployment, M1/M2/M3 Macs, AMD/Intel GPUs, or when CUDA is unavailable. Supports GGUF quantization (1.5-8 bit) for reduced memory and 4-10× speedup vs PyTorch on CPU. | `mlops/inference/llama-cpp` | +| `obliteratus` | Remove refusal behaviors from open-weight LLMs using OBLITERATUS — mechanistic interpretability techniques (diff-in-means, SVD, whitened SVD, LEACE, SAE decomposition, etc.) to excise guardrails while preserving reasoning. 9 CLI methods, 28 analysis modules, 116 model presets ac… | `mlops/inference/obliteratus` | +| `outlines` | Guarantee valid JSON/XML/code structure during generation, use Pydantic models for type-safe outputs, support local models (Transformers, vLLM), and maximize inference speed with Outlines - dottxt.ai's structured generation library | `mlops/inference/outlines` | +| `serving-llms-vllm` | Serves LLMs with high throughput using vLLM's PagedAttention and continuous batching. Use when deploying production LLM APIs, optimizing inference latency/throughput, or serving models with limited GPU memory. Supports OpenAI-compatible endpoints, quantization (GPTQ/AWQ/FP8), an… | `mlops/inference/vllm` | +| `tensorrt-llm` | Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency. Use for production deployment on NVIDIA GPUs (A100/H100), when you need 10-100x faster inference than PyTorch, or for serving models with quantization (FP8/INT4), in-flight batching, and mult… | `mlops/inference/tensorrt-llm` | + +## mlops/models + +Specific model architectures and tools — computer vision (CLIP, SAM, Stable Diffusion), speech (Whisper), audio generation (AudioCraft), and multimodal models (LLaVA). + +| Skill | Description | Path | +|-------|-------------|------| +| `audiocraft-audio-generation` | PyTorch library for audio generation including text-to-music (MusicGen) and text-to-sound (AudioGen). Use when you need to generate music from text descriptions, create sound effects, or perform melody-conditioned music generation. | `mlops/models/audiocraft` | +| `clip` | OpenAI's model connecting vision and language. Enables zero-shot image classification, image-text matching, and cross-modal retrieval. Trained on 400M image-text pairs. Use for image search, content moderation, or vision-language tasks without fine-tuning. Best for general-purpo… | `mlops/models/clip` | +| `llava` | Large Language and Vision Assistant. Enables visual instruction tuning and image-based conversations. Combines CLIP vision encoder with Vicuna/LLaMA language models. Supports multi-turn image chat, visual question answering, and instruction following. Use for vision-language cha… | `mlops/models/llava` | +| `segment-anything-model` | Foundation model for image segmentation with zero-shot transfer. Use when you need to segment any object in images using points, boxes, or masks as prompts, or automatically generate all object masks in an image. | `mlops/models/segment-anything` | +| `stable-diffusion-image-generation` | State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers. Use when generating images from text prompts, performing image-to-image translation, inpainting, or building custom diffusion pipelines. | `mlops/models/stable-diffusion` | +| `whisper` | OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast transcription, or multilingual audio proc… | `mlops/models/whisper` | + +## mlops/research + +ML research frameworks for building and optimizing AI systems with declarative programming. + +| Skill | Description | Path | +|-------|-------------|------| +| `dspy` | Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming | `mlops/research/dspy` | + +## mlops/training + +Fine-tuning, RLHF/DPO/GRPO training, distributed training frameworks, and optimization tools for training LLMs and other models. + +| Skill | Description | Path | +|-------|-------------|------| +| `axolotl` | Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support | `mlops/training/axolotl` | +| `distributed-llm-pretraining-torchtitan` | Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). Use when pretraining Llama 3.1, DeepSeek V3, or custom models at scale from 8 to 512+ GPUs with Float8, torch.compile, and distributed checkpointing. | `mlops/training/torchtitan` | +| `fine-tuning-with-trl` | Fine-tune LLMs using reinforcement learning with TRL - SFT for instruction tuning, DPO for preference alignment, PPO/GRPO for reward optimization, and reward model training. Use when need RLHF, align model with preferences, or train from human feedback. Works with HuggingFace Tr… | `mlops/training/trl-fine-tuning` | +| `grpo-rl-training` | Expert guidance for GRPO/RL fine-tuning with TRL for reasoning and task-specific model training | `mlops/training/grpo-rl-training` | +| `hermes-atropos-environments` | Build, test, and debug Hermes Agent RL environments for Atropos training. Covers the HermesAgentBaseEnv interface, reward functions, agent loop integration, evaluation with tools, wandb logging, and the three CLI modes (serve/process/evaluate). Use when creating, reviewing, or f… | `mlops/training/hermes-atropos-environments` | +| `huggingface-accelerate` | Simplest distributed training API. 4 lines to add distributed support to any PyTorch script. Unified API for DeepSpeed/FSDP/Megatron/DDP. Automatic device placement, mixed precision (FP16/BF16/FP8). Interactive config, single launch command. HuggingFace ecosystem standard. | `mlops/training/accelerate` | +| `optimizing-attention-flash` | Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. Use when training/running transformers with long sequences (>512 tokens), encountering GPU memory issues with attention, or need faster inference. Supports PyTorch native SDPA,… | `mlops/training/flash-attention` | +| `peft-fine-tuning` | Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. Use when fine-tuning large models (7B-70B) with limited GPU memory, when you need to train <1% of parameters with minimal accuracy loss, or for multi-adapter serving. HuggingFace's official library i… | `mlops/training/peft` | +| `pytorch-fsdp` | Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2 | `mlops/training/pytorch-fsdp` | +| `pytorch-lightning` | High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. Scales from laptop to supercomputer with same code. Use when you want clean training loops with built-in best practices. | `mlops/training/pytorch-lightning` | +| `simpo-training` | Simple Preference Optimization for LLM alignment. Reference-free alternative to DPO with better performance (+6.4 points on AlpacaEval 2.0). No reference model needed, more efficient than DPO. Use for preference alignment when want simpler, faster training than DPO/PPO. | `mlops/training/simpo` | +| `slime-rl-training` | Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. Use when training GLM models, implementing custom data generation workflows, or needing tight Megatron-LM integration for RL scaling. | `mlops/training/slime` | +| `unsloth` | Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization | `mlops/training/unsloth` | + +## mlops/vector-databases + +Vector similarity search and embedding databases for RAG, semantic search, and AI application backends. + +| Skill | Description | Path | +|-------|-------------|------| +| `chroma` | Open-source embedding database for AI applications. Store embeddings and metadata, perform vector and full-text search, filter by metadata. Simple 4-function API. Scales from notebooks to production clusters. Use for semantic search, RAG applications, or document retrieval. Best… | `mlops/vector-databases/chroma` | +| `faiss` | Facebook's library for efficient similarity search and clustering of dense vectors. Supports billions of vectors, GPU acceleration, and various index types (Flat, IVF, HNSW). Use for fast k-NN search, large-scale vector retrieval, or when you need pure similarity search without… | `mlops/vector-databases/faiss` | +| `pinecone` | Managed vector database for production AI applications. Fully managed, auto-scaling, with hybrid search (dense + sparse), metadata filtering, and namespaces. Low latency (<100ms p95). Use for production RAG, recommendation systems, or semantic search at scale. Best for server… | `mlops/vector-databases/pinecone` | +| `qdrant-vector-search` | High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance. | `mlops/vector-databases/qdrant` | + +## note-taking + +Note taking skills, to save information, assist with research, and collab on multi-session planning and information sharing. + +| Skill | Description | Path | +|-------|-------------|------| +| `obsidian` | Read, search, and create notes in the Obsidian vault. | `note-taking/obsidian` | + +## productivity + +Skills for document creation, presentations, spreadsheets, and other productivity workflows. + +| Skill | Description | Path | +|-------|-------------|------| +| `google-workspace` | Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via Python. Uses OAuth2 with automatic token refresh. No external binaries needed — runs entirely with Google's Python client libraries in the Hermes venv. | `productivity/google-workspace` | +| `nano-pdf` | Edit PDFs with natural-language instructions using the nano-pdf CLI. Modify text, fix typos, update titles, and make content changes to specific pages without manual editing. | `productivity/nano-pdf` | +| `notion` | Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal. | `productivity/notion` | +| `ocr-and-documents` | Extract text from PDFs and scanned documents. Use web_extract for remote URLs, pymupdf for local text-based PDFs, marker-pdf for OCR/scanned docs. For DOCX use python-docx, for PPTX see the powerpoint skill. | `productivity/ocr-and-documents` | +| `powerpoint` | "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in a… | `productivity/powerpoint` | + +## research + +Skills for academic research, paper discovery, literature review, domain reconnaissance, market data, content monitoring, and scientific knowledge retrieval. + +| Skill | Description | Path | +|-------|-------------|------| +| `arxiv` | Search and retrieve academic papers from arXiv using their free REST API. No API key needed. Search by keyword, author, category, or ID. Combine with web_extract or the ocr-and-documents skill to read full paper content. | `research/arxiv` | +| `blogwatcher` | Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI. Add blogs, scan for new articles, and track what you've read. | `research/blogwatcher` | +| `domain-intel` | Passive domain reconnaissance using Python stdlib. Subdomain discovery, SSL certificate inspection, WHOIS lookups, DNS records, domain availability checks, and bulk multi-domain analysis. No API keys required. | `research/domain-intel` | +| `duckduckgo-search` | Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Use the Python DDGS library or CLI to search, then web_extract for full content. | `research/duckduckgo-search` | +| `ml-paper-writing` | Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verificatio… | `research/ml-paper-writing` | +| `polymarket` | Query Polymarket prediction market data — search markets, get prices, orderbooks, and price history. Read-only via public REST APIs, no API key needed. | `research/polymarket` | + +## smart-home + +Skills for controlling smart home devices — lights, switches, sensors, and home automation systems. + +| Skill | Description | Path | +|-------|-------------|------| +| `openhue` | Control Philips Hue lights, rooms, and scenes via the OpenHue CLI. Turn lights on/off, adjust brightness, color, color temperature, and activate scenes. | `smart-home/openhue` | + +## software-development + +| Skill | Description | Path | +|-------|-------------|------| +| `code-review` | Guidelines for performing thorough code reviews with security and quality focus | `software-development/code-review` | +| `requesting-code-review` | Use when completing tasks, implementing major features, or before merging. Validates work meets requirements through systematic review process. | `software-development/requesting-code-review` | +| `subagent-driven-development` | Use when executing implementation plans with independent tasks. Dispatches fresh delegate_task per task with two-stage review (spec compliance then code quality). | `software-development/subagent-driven-development` | +| `systematic-debugging` | Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first. | `software-development/systematic-debugging` | +| `test-driven-development` | Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach. | `software-development/test-driven-development` | +| `writing-plans` | Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples. | `software-development/writing-plans` | diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md new file mode 100644 index 000000000..b67578261 --- /dev/null +++ b/website/docs/reference/slash-commands.md @@ -0,0 +1,119 @@ +--- +sidebar_position: 2 +title: "Slash Commands Reference" +description: "Complete reference for interactive CLI and messaging slash commands" +--- + +# Slash Commands Reference + +Hermes has two slash-command surfaces: + +- **Interactive CLI slash commands** — handled by `cli.py` / `hermes_cli/commands.py` +- **Messaging slash commands** — handled by `gateway/run.py` + +Installed skills are also exposed as dynamic slash commands on both surfaces. + +## Interactive CLI slash commands + +Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-insensitive. + +### Session + +| Command | Description | +|---------|-------------| +| `/new` | Start a new conversation (reset history) | +| `/reset` | Reset conversation only (keep screen) | +| `/clear` | Clear screen and reset conversation (fresh start) | +| `/history` | Show conversation history | +| `/save` | Save the current conversation | +| `/retry` | Retry the last message (resend to agent) | +| `/undo` | Remove the last user/assistant exchange | +| `/title` | Set a title for the current session (usage: /title My Session Name) | +| `/compress` | Manually compress conversation context (flush memories + summarize) | +| `/rollback` | List or restore filesystem checkpoints (usage: /rollback [number]) | +| `/background` | Run a prompt in the background (usage: /background <prompt>) | + +### Configuration + +| Command | Description | +|---------|-------------| +| `/config` | Show current configuration | +| `/model` | Show or change the current model | +| `/provider` | Show available providers and current provider | +| `/prompt` | View/set custom system prompt | +| `/personality` | Set a predefined personality | +| `/verbose` | Cycle tool progress display: off → new → all → verbose | +| `/reasoning` | Manage reasoning effort and display (usage: /reasoning [level\|show\|hide]) | +| `/skin` | Show or change the display skin/theme | + +### Tools & Skills + +| Command | Description | +|---------|-------------| +| `/tools` | List available tools | +| `/toolsets` | List available toolsets | +| `/skills` | Search, install, inspect, or manage skills from online registries | +| `/cron` | Manage scheduled tasks (list, add, remove) | +| `/reload-mcp` | Reload MCP servers from config.yaml | + +### Info + +| Command | Description | +|---------|-------------| +| `/help` | Show this help message | +| `/usage` | Show token usage for the current session | +| `/insights` | Show usage insights and analytics (last 30 days) | +| `/platforms` | Show gateway/messaging platform status | +| `/paste` | Check clipboard for an image and attach it | + +### Exit + +| Command | Description | +|---------|-------------| +| `/quit` | Exit the CLI (also: /exit, /q) | + +### Dynamic CLI slash commands + +| Command | Description | +|---------|-------------| +| `/<skill-name>` | Load any installed skill as an on-demand command. Example: `/gif-search`, `/github-pr-workflow`, `/excalidraw`. | +| `/skills ...` | Search, browse, inspect, install, audit, publish, and configure skills from registries and the official optional-skills catalog. | + +### Quick commands + +User-defined quick commands from `quick_commands` in `~/.hermes/config.yaml` are also available as slash commands. These are resolved at dispatch time, not shown in the built-in autocomplete/help tables. + +## Messaging slash commands + +The messaging gateway supports the following built-in commands inside Telegram, Discord, Slack, WhatsApp, Signal, Email, and Home Assistant chats: + +| Command | Description | +|---------|-------------| +| `/new` | Start a new conversation. | +| `/reset` | Reset conversation history. | +| `/status` | Show session info. | +| `/stop` | Interrupt the running agent without queuing a follow-up prompt. | +| `/model [provider:model]` | Show or change the model, including provider switches. | +| `/provider` | Show provider availability and auth status. | +| `/personality [name]` | Set a personality overlay for the session. | +| `/retry` | Retry the last message. | +| `/undo` | Remove the last exchange. | +| `/sethome` | Mark the current chat as the platform home channel for deliveries. | +| `/compress` | Manually compress conversation context. | +| `/title [name]` | Set or show the session title. | +| `/resume [name]` | Resume a previously named session. | +| `/usage` | Show token usage for the current session. | +| `/insights [days]` | Show usage analytics. | +| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display. | +| `/rollback [number]` | List or restore filesystem checkpoints. | +| `/background <prompt>` | Run a prompt in a separate background session. | +| `/reload-mcp` | Reload MCP servers from config. | +| `/update` | Update Hermes Agent to the latest version. | +| `/help` | Show messaging help. | +| `/<skill-name>` | Invoke any installed skill by name. | + +## Notes + +- `/skin`, `/tools`, `/toolsets`, `/config`, `/prompt`, `/cron`, `/skills`, `/platforms`, `/paste`, and `/verbose` are **CLI-only** commands. +- `/status`, `/stop`, `/sethome`, `/resume`, `/background`, and `/update` are **messaging-only** commands. +- `/reload-mcp` and `/rollback` work in **both** the CLI and the messaging gateway. \ No newline at end of file diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md new file mode 100644 index 000000000..a4fb2322d --- /dev/null +++ b/website/docs/reference/tools-reference.md @@ -0,0 +1,163 @@ +--- +sidebar_position: 3 +title: "Built-in Tools Reference" +description: "Authoritative reference for Hermes built-in tools, grouped by toolset" +--- + +# Built-in Tools Reference + +This page documents the built-in Hermes tool registry as it exists in code. Availability can still vary by platform, credentials, and enabled toolsets. + +## `browser` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `browser_back` | Navigate back to the previous page in browser history. Requires browser_navigate to be called first. | — | +| `browser_click` | Click on an element identified by its ref ID from the snapshot (e.g., '@e5'). The ref IDs are shown in square brackets in the snapshot output. Requires browser_navigate and browser_snapshot to be called first. | — | +| `browser_close` | Close the browser session and release resources. Call this when done with browser tasks to free up Browserbase session quota. | — | +| `browser_console` | Get browser console output and JavaScript errors from the current page. Returns console.log/warn/error/info messages and uncaught JS exceptions. Use this to detect silent JavaScript errors, failed API calls, and application warnings. Requi… | — | +| `browser_get_images` | Get a list of all images on the current page with their URLs and alt text. Useful for finding images to analyze with the vision tool. Requires browser_navigate to be called first. | — | +| `browser_navigate` | Navigate to a URL in the browser. Initializes the session and loads the page. Must be called before other browser tools. For simple information retrieval, prefer web_search or web_extract (faster, cheaper). Use browser tools when you need… | — | +| `browser_press` | Press a keyboard key. Useful for submitting forms (Enter), navigating (Tab), or keyboard shortcuts. Requires browser_navigate to be called first. | — | +| `browser_scroll` | Scroll the page in a direction. Use this to reveal more content that may be below or above the current viewport. Requires browser_navigate to be called first. | — | +| `browser_snapshot` | Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) for browser_click and browser_type. full=false (default): compact view with interactive elements. full=true: comp… | — | +| `browser_type` | Type text into an input field identified by its ref ID. Clears the field first, then types the new text. Requires browser_navigate and browser_snapshot to be called first. | — | +| `browser_vision` | Take a screenshot of the current page and analyze it with vision AI. Use this when you need to visually understand what's on the page - especially useful for CAPTCHAs, visual verification challenges, complex layouts, or when the text snaps… | — | + +## `clarify` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `clarify` | Ask the user a question when you need clarification, feedback, or a decision before proceeding. Supports two modes: 1. **Multiple choice** — provide up to 4 choices. The user picks one or types their own answer via a 5th 'Other' option. 2.… | — | + +## `code_execution` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `execute_code` | Run a Python script that can call Hermes tools programmatically. Use this when you need 3+ tool calls with processing logic between them, need to filter/reduce large tool outputs before they enter your context, need conditional branching (… | — | + +## `cronjob` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `list_cronjobs` | List all scheduled cronjobs with their IDs, schedules, and status. Use this to: - See what jobs are currently scheduled - Find job IDs for removal with remove_cronjob - Check job status and next run times Returns job_id, name, schedule, re… | — | +| `remove_cronjob` | Remove a scheduled cronjob by its ID. Use list_cronjobs first to find the job_id of the job you want to remove. Jobs that have completed their repeat count are auto-removed, but you can use this to cancel a job before it completes. | — | +| `schedule_cronjob` | Schedule an automated task to run the agent on a schedule. ⚠️ CRITICAL: The cronjob runs in a FRESH SESSION with NO CONTEXT from this conversation. The prompt must be COMPLETELY SELF-CONTAINED with ALL necessary information including: - Fu… | — | + +## `delegation` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `delegate_task` | Spawn one or more subagents to work on tasks in isolated contexts. Each subagent gets its own conversation, terminal session, and toolset. Only the final summary is returned -- intermediate tool results never enter your context window. TWO… | — | + +## `file` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `patch` | Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing… | — | +| `read_file` | Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM\|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. NOTE: Cannot read images o… | — | +| `search_files` | Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents. Content search (target='content'): Regex search inside files. Output modes: full matches with line… | — | +| `write_file` | Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits. | — | + +## `homeassistant` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `ha_call_service` | Call a Home Assistant service to control a device. Use ha_list_services to discover available services and their parameters for each domain. | — | +| `ha_get_state` | Get the detailed state of a single Home Assistant entity, including all attributes (brightness, color, temperature setpoint, sensor readings, etc.). | — | +| `ha_list_entities` | List Home Assistant entities. Optionally filter by domain (light, switch, climate, sensor, binary_sensor, cover, fan, etc.) or by area name (living room, kitchen, bedroom, etc.). | — | +| `ha_list_services` | List available Home Assistant services (actions) for device control. Shows what actions can be performed on each device type and what parameters they accept. Use this to discover how to control devices found via ha_list_entities. | — | + +## `honcho` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `honcho_conclude` | Write a conclusion about the user back to Honcho's memory. Conclusions are persistent facts that build the user's profile — preferences, corrections, clarifications, project context, or anything the user tells you that should be remembered… | — | +| `honcho_context` | Ask Honcho a natural language question and get a synthesized answer. Uses Honcho's LLM (dialectic reasoning) — higher cost than honcho_profile or honcho_search. Can query about any peer: the user (default), the AI assistant, or any named p… | — | +| `honcho_profile` | Retrieve the user's peer card from Honcho — a curated list of key facts about them (name, role, preferences, communication style, patterns). Fast, no LLM reasoning, minimal cost. Use this at conversation start or when you need a quick fact… | — | +| `honcho_search` | Semantic search over Honcho's stored context about the user. Returns raw excerpts ranked by relevance to your query — no LLM synthesis. Cheaper and faster than honcho_context. Good when you want to find specific past facts and reason over… | — | + +## `image_gen` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `image_generate` | Generate high-quality images from text prompts using FLUX 2 Pro model with automatic 2x upscaling. Creates detailed, artistic images that are automatically upscaled for hi-rez results. Returns a single upscaled image URL. Display it using… | FAL_KEY | + +## `memory` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `memory` | Save important information to persistent memory that survives across sessions. Your memory appears in your system prompt at session start -- it's how you remember things about the user and your environment between conversations. WHEN TO SA… | — | + +## `messaging` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `send_message` | Send a message to a connected messaging platform, or list available targets. IMPORTANT: When the user asks to send to a specific channel or person (not just a bare platform name), call send_message(action='list') FIRST to see available tar… | — | + +## `moa` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `mixture_of_agents` | Route a hard problem through multiple frontier LLMs collaboratively. Makes 5 API calls (4 reference models + 1 aggregator) with maximum reasoning effort — use sparingly for genuinely difficult problems. Best for: complex math, advanced alg… | OPENROUTER_API_KEY | + +## `rl` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `rl_check_status` | Get status and metrics for a training run. RATE LIMITED: enforces 30-minute minimum between checks for the same run. Returns WandB metrics: step, state, reward_mean, loss, percent_correct. | TINKER_API_KEY, WANDB_API_KEY | +| `rl_edit_config` | Update a configuration field. Use rl_get_current_config() first to see all available fields for the selected environment. Each environment has different configurable options. Infrastructure settings (tokenizer, URLs, lora_rank, learning_ra… | TINKER_API_KEY, WANDB_API_KEY | +| `rl_get_current_config` | Get the current environment configuration. Returns only fields that can be modified: group_size, max_token_length, total_steps, steps_per_eval, use_wandb, wandb_name, max_num_workers. | TINKER_API_KEY, WANDB_API_KEY | +| `rl_get_results` | Get final results and metrics for a completed training run. Returns final metrics and path to trained weights. | TINKER_API_KEY, WANDB_API_KEY | +| `rl_list_environments` | List all available RL environments. Returns environment names, paths, and descriptions. TIP: Read the file_path with file tools to understand how each environment works (verifiers, data loading, rewards). | TINKER_API_KEY, WANDB_API_KEY | +| `rl_list_runs` | List all training runs (active and completed) with their status. | TINKER_API_KEY, WANDB_API_KEY | +| `rl_select_environment` | Select an RL environment for training. Loads the environment's default configuration. After selecting, use rl_get_current_config() to see settings and rl_edit_config() to modify them. | TINKER_API_KEY, WANDB_API_KEY | +| `rl_start_training` | Start a new RL training run with the current environment and config. Most training parameters (lora_rank, learning_rate, etc.) are fixed. Use rl_edit_config() to set group_size, batch_size, wandb_project before starting. WARNING: Training… | TINKER_API_KEY, WANDB_API_KEY | +| `rl_stop_training` | Stop a running training job. Use if metrics look bad, training is stagnant, or you want to try different settings. | TINKER_API_KEY, WANDB_API_KEY | +| `rl_test_inference` | Quick inference test for any environment. Runs a few steps of inference + scoring using OpenRouter. Default: 3 steps x 16 completions = 48 rollouts per model, testing 3 models = 144 total. Tests environment loading, prompt construction, in… | TINKER_API_KEY, WANDB_API_KEY | + +## `session_search` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `session_search` | Search your long-term memory of past conversations. This is your recall -- every past session is searchable, and this tool summarizes what happened. USE THIS PROACTIVELY when: - The user says 'we did this before', 'remember when', 'last ti… | — | + +## `skills` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `skill_manage` | Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live. Actions: create (full SKILL.m… | — | +| `skill_view` | Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a… | — | +| `skills_list` | List available skills (name + description). Use skill_view(name) to load full content. | — | + +## `terminal` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `process` | Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (sen… | — | +| `terminal` | Execute shell commands on a Linux environment. Filesystem persists between calls. Do NOT use cat/head/tail to read files — use read_file instead. Do NOT use grep/rg/find to search — use search_files instead. Do NOT use ls to list directori… | — | + +## `todo` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `todo` | Manage your task list for the current session. Use for complex tasks with 3+ steps or when the user provides multiple tasks. Call with no parameters to read the current list. Writing: - Provide 'todos' array to create/update items - merge=… | — | + +## `tts` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `text_to_speech` | Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider… | — | + +## `vision` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `vision_analyze` | Analyze images using AI vision. Provides a comprehensive description and answers a specific question about the image content. | — | + +## `web` toolset + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `web_extract` | Extract content from web page URLs. Returns page content in markdown format. Also works with PDF URLs (arxiv papers, documents, etc.) — pass the PDF link directly and it converts to markdown text. Pages under 5000 chars return full markdow… | FIRECRAWL_API_KEY | +| `web_search` | Search the web for information on any topic. Returns up to 5 relevant results with titles, URLs, and descriptions. | FIRECRAWL_API_KEY | diff --git a/website/docs/reference/toolsets-reference.md b/website/docs/reference/toolsets-reference.md new file mode 100644 index 000000000..8f1adb108 --- /dev/null +++ b/website/docs/reference/toolsets-reference.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 4 +title: "Toolsets Reference" +description: "Reference for Hermes core, composite, platform, and dynamic toolsets" +--- + +# Toolsets Reference + +Toolsets are named bundles of tools that you can enable with `hermes chat --toolsets ...`, configure per platform, or resolve inside the agent runtime. + +| Toolset | Kind | Resolves to | +|---------|------|-------------| +| `browser` | core | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `web_search` | +| `clarify` | core | `clarify` | +| `code_execution` | core | `execute_code` | +| `cronjob` | core | `list_cronjobs`, `remove_cronjob`, `schedule_cronjob` | +| `debugging` | composite | `patch`, `process`, `read_file`, `search_files`, `terminal`, `web_extract`, `web_search`, `write_file` | +| `delegation` | core | `delegate_task` | +| `file` | core | `patch`, `read_file`, `search_files`, `write_file` | +| `hermes-cli` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-discord` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-email` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-gateway` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-homeassistant` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-signal` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-slack` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-telegram` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `hermes-whatsapp` | platform | `browser_back`, `browser_click`, `browser_close`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `clarify`, `delegate_task`, `execute_code`, `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services`, `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search`, `image_generate`, `list_cronjobs`, `memory`, `mixture_of_agents`, `patch`, `process`, `read_file`, `remove_cronjob`, `schedule_cronjob`, `search_files`, `send_message`, `session_search`, `skill_manage`, `skill_view`, `skills_list`, `terminal`, `text_to_speech`, `todo`, `vision_analyze`, `web_extract`, `web_search`, `write_file` | +| `homeassistant` | core | `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services` | +| `honcho` | core | `honcho_conclude`, `honcho_context`, `honcho_profile`, `honcho_search` | +| `image_gen` | core | `image_generate` | +| `memory` | core | `memory` | +| `moa` | core | `mixture_of_agents` | +| `rl` | core | `rl_check_status`, `rl_edit_config`, `rl_get_current_config`, `rl_get_results`, `rl_list_environments`, `rl_list_runs`, `rl_select_environment`, `rl_start_training`, `rl_stop_training`, `rl_test_inference` | +| `safe` | composite | `image_generate`, `mixture_of_agents`, `vision_analyze`, `web_extract`, `web_search` | +| `search` | core | `web_search` | +| `session_search` | core | `session_search` | +| `skills` | core | `skill_manage`, `skill_view`, `skills_list` | +| `terminal` | core | `process`, `terminal` | +| `todo` | core | `todo` | +| `tts` | core | `text_to_speech` | +| `vision` | core | `vision_analyze` | +| `web` | core | `web_extract`, `web_search` | + +## Dynamic toolsets + +- `mcp-<server>` — generated at runtime for each configured MCP server. +- Custom toolsets can be created in configuration and resolved at startup. +- Wildcards: `all` and `*` expand to every registered toolset. \ No newline at end of file diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md index 1649fd74d..6c8d558da 100644 --- a/website/docs/user-guide/cli.md +++ b/website/docs/user-guide/cli.md @@ -75,61 +75,33 @@ When resuming a previous session (`hermes -c` or `hermes --resume <id>`), a "Pre |-----|--------| | `Enter` | Send message | | `Alt+Enter` or `Ctrl+J` | New line (multi-line input) | +| `Alt+V` | Paste an image from the clipboard when supported by the terminal | +| `Ctrl+V` | Paste text and opportunistically attach clipboard images | | `Ctrl+C` | Interrupt agent (double-press within 2s to force exit) | | `Ctrl+D` | Exit | | `Tab` | Autocomplete slash commands | ## Slash Commands -Type `/` to see an autocomplete dropdown of all available commands. +Type `/` to see the autocomplete dropdown. Hermes supports a large set of CLI slash commands, dynamic skill commands, and user-defined quick commands. -### Navigation & Control +Common examples: | Command | Description | |---------|-------------| -| `/help` | Show available commands | -| `/quit` | Exit the CLI (also: `/exit`, `/q`) | -| `/clear` | Clear screen and reset conversation | -| `/new` | Start a new conversation | -| `/reset` | Reset conversation only (keep screen) | +| `/help` | Show command help | +| `/model` | Show or change the current model | +| `/tools` | List currently available tools | +| `/skills browse` | Browse the skills hub and official optional skills | +| `/background <prompt>` | Run a prompt in a separate background session | +| `/skin` | Show or switch the active CLI skin | +| `/reasoning high` | Increase reasoning effort | +| `/title My Session` | Name the current session | -### Tools & Configuration - -| Command | Description | -|---------|-------------| -| `/tools` | List all available tools grouped by toolset | -| `/toolsets` | List available toolsets with descriptions | -| `/model [provider:model]` | Show or change the current model (supports `provider:model` syntax) | -| `/provider` | Show available providers with auth status | -| `/config` | Show current configuration | -| `/prompt [text]` | View/set/clear custom system prompt | -| `/personality [name]` | Set a predefined personality | -| `/reasoning [arg]` | Manage reasoning effort (`none`/`low`/`medium`/`high`/`xhigh`) and display (`show`/`hide`) | - -### Conversation Management - -| Command | Description | -|---------|-------------| -| `/history` | Show conversation history | -| `/retry` | Retry the last message | -| `/undo` | Remove the last user/assistant exchange | -| `/save` | Save the current conversation | -| `/compress` | Manually compress conversation context | -| `/usage` | Show token usage for this session | -| `/insights [--days N]` | Show usage insights and analytics (last 30 days) | - -### Skills & Scheduling - -| Command | Description | -|---------|-------------| -| `/cron` | Manage scheduled tasks | -| `/skills` | Browse, search, install, inspect, or manage skills | -| `/platforms` | Show gateway/messaging platform status | -| `/verbose` | Cycle tool progress display: off → new → all → verbose | -| `/<skill-name>` | Invoke any installed skill (e.g., `/axolotl`, `/gif-search`) | +For the full built-in CLI and messaging lists, see [Slash Commands Reference](../reference/slash-commands.md). :::tip -Commands are case-insensitive — `/HELP` works the same as `/help`. Most commands work mid-conversation. +Commands are case-insensitive — `/HELP` works the same as `/help`. Installed skills also become slash commands automatically. ::: ## Quick Commands @@ -261,16 +233,16 @@ Resuming restores the full conversation history from SQLite. The agent sees all Use `/title My Session Name` inside a chat to name the current session, or `hermes sessions rename <id> <title>` from the command line. Use `hermes sessions list` to browse past sessions. -### Session Logging +### Session Storage -Sessions are automatically logged to `~/.hermes/sessions/`: +CLI sessions are stored in Hermes's SQLite state database under `~/.hermes/state.db`. The database keeps: -``` -sessions/ -├── session_20260201_143052_a1b2c3.json -├── session_20260201_150217_d4e5f6.json -└── ... -``` +- session metadata (ID, title, timestamps, token counters) +- message history +- lineage across compressed/resumed sessions +- full-text search indexes used by `session_search` + +Some messaging adapters also keep per-platform transcript files alongside the database, but the CLI itself resumes from the SQLite session store. ### Context Compression @@ -280,7 +252,7 @@ Long conversations are automatically summarized when approaching context limits: # In ~/.hermes/config.yaml compression: enabled: true - threshold: 0.85 # Compress at 85% of context limit + threshold: 0.50 # Compress at 50% of context limit by default summary_model: "google/gemini-3-flash-preview" # Model used for summarization ``` diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 53c429bd4..1de46644b 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -72,7 +72,7 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro | **Custom Endpoint** | `OPENAI_BASE_URL` + `OPENAI_API_KEY` in `~/.hermes/.env` | :::info Codex Note -The OpenAI Codex provider authenticates via device code (open a URL, enter a code). Credentials are stored at `~/.codex/auth.json` and auto-refresh. No Codex CLI installation required. +The OpenAI Codex provider authenticates via device code (open a URL, enter a code). Hermes stores the resulting credentials in its own auth store under `~/.hermes/auth.json` and can import existing Codex CLI credentials from `~/.codex/auth.json` when present. No Codex CLI installation is required. ::: :::warning @@ -493,7 +493,7 @@ node_modules/ ```yaml compression: enabled: true - threshold: 0.85 # Compress at 85% of context limit + threshold: 0.50 # Compress at 50% of context limit by default summary_model: "google/gemini-3-flash-preview" # Model for summarization # summary_provider: "auto" # "auto", "openrouter", "nous", "main" ``` @@ -666,12 +666,13 @@ tts: ```yaml display: - tool_progress: all # off | new | all | verbose - personality: "kawaii" # Default personality for the CLI - compact: false # Compact output mode (less whitespace) - resume_display: full # full (show previous messages on resume) | minimal (one-liner only) - bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks) - show_reasoning: false # Show model reasoning/thinking above each response (toggle with /reasoning show|hide) + tool_progress: all # off | new | all | verbose + skin: default # Built-in or custom CLI skin (see user-guide/features/skins) + personality: "kawaii" # Legacy cosmetic field still surfaced in some summaries + compact: false # Compact output mode (less whitespace) + resume_display: full # full (show previous messages on resume) | minimal (one-liner only) + bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks) + show_reasoning: false # Show model reasoning/thinking above each response (toggle with /reasoning show|hide) ``` | Mode | What you see | @@ -714,8 +715,9 @@ Usage: type `/status`, `/disk`, `/update`, or `/gpu` in the CLI or any messaging - **30-second timeout** — long-running commands are killed with an error message - **Priority** — quick commands are checked before skill commands, so you can override skill names +- **Autocomplete** — quick commands are resolved at dispatch time and are not shown in the built-in slash-command autocomplete tables - **Type** — only `exec` is supported (runs a shell command); other types show an error -- **Works everywhere** — CLI, Telegram, Discord, Slack, WhatsApp, Signal +- **Works everywhere** — CLI, Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant ## Human Delay diff --git a/website/docs/user-guide/features/batch-processing.md b/website/docs/user-guide/features/batch-processing.md index a5a123300..cdbd7b634 100644 --- a/website/docs/user-guide/features/batch-processing.md +++ b/website/docs/user-guide/features/batch-processing.md @@ -94,7 +94,7 @@ Entries can optionally include: Each prompt gets a randomly sampled set of toolsets from a **distribution**. This ensures training data covers diverse tool combinations. Use `--list_distributions` to see all available distributions. -Distributions define probability weights for each toolset combination. For example, a "default" distribution might assign high probability to `["terminal", "file", "web"]` and lower probability to web-only or file-only combinations. +In the current implementation, distributions assign a probability to **each individual toolset**. The sampler flips each toolset independently, then guarantees that at least one toolset is enabled. This is different from a hand-authored table of prebuilt combinations. ## Output Format diff --git a/website/docs/user-guide/features/browser.md b/website/docs/user-guide/features/browser.md index f7822c884..ad6e6df81 100644 --- a/website/docs/user-guide/features/browser.md +++ b/website/docs/user-guide/features/browser.md @@ -7,11 +7,16 @@ sidebar_position: 5 # Browser Automation -Hermes Agent includes a full browser automation toolset powered by [Browserbase](https://browserbase.com), enabling the agent to navigate websites, interact with page elements, fill forms, and extract information — all running in cloud-hosted browsers with built-in anti-bot stealth features. +Hermes Agent includes a full browser automation toolset that can run in two modes: + +- **Browserbase cloud mode** via [Browserbase](https://browserbase.com) for managed cloud browsers and anti-bot tooling +- **Local browser mode** via the `agent-browser` CLI and a local Chromium installation + +In both modes, the agent can navigate websites, interact with page elements, fill forms, and extract information. ## Overview -The browser tools use the `agent-browser` CLI with Browserbase cloud execution. Pages are represented as **accessibility trees** (text-based snapshots), making them ideal for LLM agents. Interactive elements get ref IDs (like `@e1`, `@e2`) that the agent uses for clicking and typing. +The browser tools use the `agent-browser` CLI. In Browserbase mode, `agent-browser` connects to Browserbase cloud sessions. In local mode, it drives a local Chromium installation. Pages are represented as **accessibility trees** (text-based snapshots), making them ideal for LLM agents. Interactive elements get ref IDs (like `@e1`, `@e2`) that the agent uses for clicking and typing. Key capabilities: @@ -23,16 +28,22 @@ Key capabilities: ## Setup -### Required Environment Variables +### Browserbase cloud mode + +To use Browserbase-managed cloud browsers, add: ```bash # Add to ~/.hermes/.env -BROWSERBASE_API_KEY=your-api-key-here +BROWSERBASE_API_KEY=*** BROWSERBASE_PROJECT_ID=your-project-id-here ``` Get your credentials at [browserbase.com](https://browserbase.com). +### Local browser mode + +If you do **not** set Browserbase credentials, Hermes can still use the browser tools through a local Chromium install driven by `agent-browser`. + ### Optional Environment Variables ```bash diff --git a/website/docs/user-guide/features/honcho.md b/website/docs/user-guide/features/honcho.md index da4dd1535..346696c50 100644 --- a/website/docs/user-guide/features/honcho.md +++ b/website/docs/user-guide/features/honcho.md @@ -298,7 +298,7 @@ hermes honcho peer --user NAME # Set user peer name hermes honcho peer --ai NAME # Set AI peer name hermes honcho peer --reasoning LEVEL # Set dialectic reasoning level hermes honcho mode # Show current memory mode -hermes honcho mode [hybrid|honcho] # Set memory mode +hermes honcho mode [hybrid|honcho|local] # Set memory mode hermes honcho tokens # Show token budget settings hermes honcho tokens --context N # Set context token cap hermes honcho tokens --dialectic N # Set dialectic char cap diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md index 9a29d4316..d1caeb065 100644 --- a/website/docs/user-guide/features/mcp.md +++ b/website/docs/user-guide/features/mcp.md @@ -161,6 +161,8 @@ Tools appear alongside built-in tools — the agent calls them like any other to :::info In addition to the server's own tools, each MCP server also gets 4 utility tools auto-registered: `list_resources`, `read_resource`, `list_prompts`, and `get_prompt`. These allow the agent to discover and use MCP resources and prompts exposed by the server. + +Each configured server also creates a **runtime toolset** named `mcp-<server>`. This means you can filter or reason about MCP servers at the toolset level in the same way you do with built-in toolsets. ::: ### Reconnection diff --git a/website/docs/user-guide/features/personality.md b/website/docs/user-guide/features/personality.md index 8ea6c5883..cc0fdfa59 100644 --- a/website/docs/user-guide/features/personality.md +++ b/website/docs/user-guide/features/personality.md @@ -216,13 +216,17 @@ The system prompt is assembled in layers (from `agent/prompt_builder.py` and `ru **SOUL.md vs agent.system_prompt**: SOUL.md is part of the "Project Context" section and coexists with the default identity. The `agent.system_prompt` (set via `/personality` or config) is an ephemeral overlay. Both can be active simultaneously — SOUL.md for tone/personality, system_prompt for additional instructions. ::: -## Display Personality (CLI Banner) +## CLI Appearance vs Conversational Personality -The `display.personality` config option controls the CLI's **visual** personality (banner art, spinner messages), independent of the agent's conversational personality: +Conversational personality and CLI appearance are separate: + +- `agent.system_prompt`, `/personality`, and `SOUL.md` affect how Hermes **speaks**. +- `display.skin` and `/skin` affect how Hermes **looks in the terminal**. ```yaml display: - personality: kawaii # Affects CLI banner and spinner art + skin: default + # personality: kawaii # legacy cosmetic setting still shown in some summaries ``` -This is purely cosmetic and doesn't affect the agent's responses — only the ASCII art and loading messages shown in the terminal. +For the full theming system — built-in skins, custom YAML skins, spinner branding, and `/skin` — see [Skins & Themes](./skins.md). diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index d40c7f42a..349791582 100644 --- a/website/docs/user-guide/features/skills.md +++ b/website/docs/user-guide/features/skills.md @@ -10,6 +10,11 @@ Skills are on-demand knowledge documents the agent can load when needed. They fo All skills live in **`~/.hermes/skills/`** — a single directory that serves as the source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here. The agent can modify or delete any skill. +See also: + +- [Bundled Skills Catalog](/docs/reference/skills-catalog) +- [Official Optional Skills Catalog](/docs/reference/optional-skills-catalog) + ## Using Skills Every installed skill is automatically available as a slash command: @@ -139,6 +144,7 @@ When a missing value is encountered, Hermes asks for it securely only when the s │ │ ├── SKILL.md # Main instructions (required) │ │ ├── references/ # Additional docs │ │ ├── templates/ # Output formats +│ │ ├── scripts/ # Helper scripts callable from the skill │ │ └── assets/ # Supplementary files │ └── vllm/ │ └── SKILL.md @@ -199,6 +205,8 @@ hermes skills tap add myorg/skills-repo # Add a custom source All hub-installed skills go through a **security scanner** that checks for data exfiltration, prompt injection, destructive commands, and other threats. +Official optional skills use identifiers like `official/security/1password` and `official/migration/openclaw-migration`. + ### Trust Levels | Level | Source | Policy | diff --git a/website/docs/user-guide/features/skins.md b/website/docs/user-guide/features/skins.md new file mode 100644 index 000000000..cb8b38c7f --- /dev/null +++ b/website/docs/user-guide/features/skins.md @@ -0,0 +1,81 @@ +--- +sidebar_position: 10 +title: "Skins & Themes" +description: "Customize the Hermes CLI with built-in and user-defined skins" +--- + +# Skins & Themes + +Skins control the **visual presentation** of the Hermes CLI: banner colors, spinner faces and verbs, response-box labels, branding text, and the tool activity prefix. + +Conversational style and visual style are separate concepts: + +- **Personality** changes the agent's tone and wording. +- **Skin** changes the CLI's appearance. + +## Change skins + +```bash +/skin # show the current skin and list available skins +/skin ares # switch to a built-in skin +/skin mytheme # switch to a custom skin from ~/.hermes/skins/mytheme.yaml +``` + +Or set the default skin in `~/.hermes/config.yaml`: + +```yaml +display: + skin: default +``` + +## Built-in skins + +| Skin | Description | Agent branding | +|------|-------------|----------------| +| `default` | Classic Hermes — gold and kawaii | `Hermes Agent` | +| `ares` | War-god theme — crimson and bronze | `Ares Agent` | +| `mono` | Monochrome — clean grayscale | `Hermes Agent` | +| `slate` | Cool blue — developer-focused | `Hermes Agent` | +| `poseidon` | Ocean-god theme — deep blue and seafoam | `Poseidon Agent` | +| `sisyphus` | Sisyphean theme — austere grayscale with persistence | `Sisyphus Agent` | +| `charizard` | Volcanic theme — burnt orange and ember | `Charizard Agent` | + +## What a skin can customize + +| Area | Keys | +|------|------| +| Banner + response colors | `colors.banner_*`, `colors.response_border` | +| Spinner animation | `spinner.waiting_faces`, `spinner.thinking_faces`, `spinner.thinking_verbs`, `spinner.wings` | +| Branding text | `branding.agent_name`, `branding.welcome`, `branding.response_label`, `branding.prompt_symbol` | +| Tool activity prefix | `tool_prefix` | + +## Custom skins + +Create YAML files under `~/.hermes/skins/`. User skins inherit missing values from the built-in `default` skin. + +```yaml +name: cyberpunk +description: Neon terminal theme + +colors: + banner_border: "#FF00FF" + banner_title: "#00FFFF" + banner_accent: "#FF1493" + +spinner: + thinking_verbs: ["jacking in", "decrypting", "uploading"] + wings: + - ["⟨⚡", "⚡⟩"] + +branding: + agent_name: "Cyber Agent" + response_label: " ⚡ Cyber " + +tool_prefix: "▏" +``` + +## Operational notes + +- Built-in skins load from `hermes_cli/skin_engine.py`. +- Unknown skins automatically fall back to `default`. +- `/skin` updates the active CLI theme immediately for the current session. \ No newline at end of file diff --git a/website/docs/user-guide/features/tools.md b/website/docs/user-guide/features/tools.md index e054adf14..c752a5628 100644 --- a/website/docs/user-guide/features/tools.md +++ b/website/docs/user-guide/features/tools.md @@ -10,25 +10,22 @@ Tools are functions that extend the agent's capabilities. They're organized into ## Available Tools -| Category | Tools | Description | -|----------|-------|-------------| -| **Web** | `web_search`, `web_extract` | Search the web, extract page content | -| **Terminal** | `terminal`, `process` | Execute commands (local/docker/singularity/modal/daytona/ssh backends), manage background processes | -| **File** | `read_file`, `write_file`, `patch`, `search_files` | Read, write, edit, and search files | -| **Browser** | `browser_navigate`, `browser_click`, `browser_type`, `browser_console`, etc. | Full browser automation via Browserbase | -| **Vision** | `vision_analyze` | Image analysis via multimodal models | -| **Image Gen** | `image_generate` | Generate images (FLUX via FAL) | -| **TTS** | `text_to_speech` | Text-to-speech (Edge TTS / ElevenLabs / OpenAI) | -| **Reasoning** | `mixture_of_agents` | Multi-model reasoning | -| **Skills** | `skills_list`, `skill_view`, `skill_manage` | Find, view, create, and manage skills | -| **Todo** | `todo` | Read/write task list for multi-step planning | -| **Memory** | `memory` | Persistent notes + user profile across sessions | -| **Session Search** | `session_search` | Search + summarize past conversations (FTS5) | -| **Cronjob** | `schedule_cronjob`, `list_cronjobs`, `remove_cronjob` | Scheduled task management | -| **Code Execution** | `execute_code` | Run Python scripts that call tools via RPC sandbox | -| **Delegation** | `delegate_task` | Spawn subagents with isolated context | -| **Clarify** | `clarify` | Ask the user multiple-choice or open-ended questions | -| **MCP** | Auto-discovered | External tools from MCP servers | +Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, RL training, messaging delivery, Home Assistant, Honcho memory, and more. + +High-level categories: + +| Category | Examples | Description | +|----------|----------|-------------| +| **Web** | `web_search`, `web_extract` | Search the web and extract page content. | +| **Terminal & Files** | `terminal`, `process`, `read_file`, `patch` | Execute commands and manipulate files. | +| **Browser** | `browser_navigate`, `browser_snapshot`, `browser_vision` | Interactive browser automation with text and vision support. | +| **Media** | `vision_analyze`, `image_generate`, `text_to_speech` | Multimodal analysis and generation. | +| **Agent orchestration** | `todo`, `clarify`, `execute_code`, `delegate_task` | Planning, clarification, code execution, and subagent delegation. | +| **Memory & recall** | `memory`, `session_search`, `honcho_*` | Persistent memory, session search, and Honcho cross-session context. | +| **Automation & delivery** | `schedule_cronjob`, `send_message` | Scheduled tasks and outbound messaging delivery. | +| **Integrations** | `ha_*`, MCP server tools, `rl_*` | Home Assistant, MCP, RL training, and other integrations. | + +For the authoritative code-derived registry, see [Built-in Tools Reference](/docs/reference/tools-reference) and [Toolsets Reference](/docs/reference/toolsets-reference). ## Using Toolsets @@ -43,7 +40,9 @@ hermes tools hermes tools ``` -**Available toolsets:** `web`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, and more. +Common toolsets include `web`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `honcho`, `homeassistant`, and `rl`. + +See [Toolsets Reference](/docs/reference/toolsets-reference) for the full set, including platform presets such as `hermes-cli`, `hermes-telegram`, and dynamic MCP toolsets like `mcp-<server>`. ## Terminal Backends @@ -56,6 +55,7 @@ The terminal tool can execute commands in different environments: | `ssh` | Remote server | Sandboxing, keep agent away from its own code | | `singularity` | HPC containers | Cluster computing, rootless | | `modal` | Cloud execution | Serverless, scale | +| `daytona` | Cloud sandbox workspace | Persistent remote dev environments | ### Configuration diff --git a/website/docs/user-guide/messaging/discord.md b/website/docs/user-guide/messaging/discord.md index 26d1d530b..38fb9598a 100644 --- a/website/docs/user-guide/messaging/discord.md +++ b/website/docs/user-guide/messaging/discord.md @@ -202,7 +202,7 @@ Replace the ID with the actual channel ID (right-click → Copy Channel ID with ## Bot Behavior -- **Server channels**: The bot responds to all messages from allowed users in channels it can access. It does **not** require a mention or prefix — any message from an allowed user is treated as a prompt. +- **Server channels**: By default the bot requires an `@mention` before it responds in server channels. You can disable that globally with `DISCORD_REQUIRE_MENTION=false` or allow specific channels to be mention-free via `DISCORD_FREE_RESPONSE_CHANNELS`. - **Direct messages**: DMs always work, even without the Message Content Intent enabled (Discord exempts DMs from this requirement). However, you should still enable the intent for server channel support. - **Conversations**: Each channel or DM maintains its own conversation context. diff --git a/website/docs/user-guide/messaging/homeassistant.md b/website/docs/user-guide/messaging/homeassistant.md index 1d14d883c..ec72383b8 100644 --- a/website/docs/user-guide/messaging/homeassistant.md +++ b/website/docs/user-guide/messaging/homeassistant.md @@ -130,33 +130,22 @@ The Home Assistant gateway adapter connects via WebSocket and subscribes to `sta By default, **no events are forwarded**. You must configure at least one of `watch_domains`, `watch_entities`, or `watch_all` to receive events. Without filters, a warning is logged at startup and all state changes are silently dropped. ::: -Configure which events the agent sees in `~/.hermes/config.yaml` under the Home Assistant platform's `extra` section: +Configure which events the agent sees in `~/.hermes/gateway.json` under the Home Assistant platform's `extra` section: -```yaml -# ~/.hermes/config.yaml -messaging: - platforms: - homeassistant: - extra: - # Watch specific domains (recommended) - watch_domains: - - climate - - binary_sensor - - alarm_control_panel - - light - - # Watch specific entities (in addition to domains) - watch_entities: - - sensor.front_door_battery - - # Ignore noisy entities - ignore_entities: - - sensor.uptime - - sensor.cpu_usage - - sensor.memory_usage - - # Per-entity cooldown (seconds) - cooldown_seconds: 30 +```json +{ + "platforms": { + "homeassistant": { + "enabled": true, + "extra": { + "watch_domains": ["climate", "binary_sensor", "alarm_control_panel", "light"], + "watch_entities": ["sensor.front_door_battery"], + "ignore_entities": ["sensor.uptime", "sensor.cpu_usage", "sensor.memory_usage"], + "cooldown_seconds": 30 + } + } + } +} ``` | Setting | Default | Description | diff --git a/website/docs/user-guide/messaging/index.md b/website/docs/user-guide/messaging/index.md index 97c4dbdda..2aa2605e6 100644 --- a/website/docs/user-guide/messaging/index.md +++ b/website/docs/user-guide/messaging/index.md @@ -62,7 +62,7 @@ hermes gateway status # Check service status | Command | Description | |---------|-------------| -| `/new` or `/reset` | Start fresh conversation | +| `/new` or `/reset` | Start a fresh conversation | | `/model [provider:model]` | Show or change the model (supports `provider:model` syntax) | | `/provider` | Show available providers with auth status | | `/personality [name]` | Set a personality | @@ -72,8 +72,13 @@ hermes gateway status # Check service status | `/stop` | Stop the running agent | | `/sethome` | Set this chat as the home channel | | `/compress` | Manually compress conversation context | +| `/title [name]` | Set or show the session title | +| `/resume [name]` | Resume a previously named session | | `/usage` | Show token usage for this session | | `/insights [days]` | Show usage insights and analytics | +| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display | +| `/rollback [number]` | List or restore filesystem checkpoints | +| `/background <prompt>` | Run a prompt in a separate background session | | `/reload-mcp` | Reload MCP servers from config | | `/update` | Update Hermes Agent to the latest version | | `/help` | Show available commands | @@ -92,7 +97,7 @@ Sessions reset based on configurable policies: | Policy | Default | Description | |--------|---------|-------------| | Daily | 4:00 AM | Reset at a specific hour each day | -| Idle | 120 min | Reset after N minutes of inactivity | +| Idle | 1440 min | Reset after N minutes of inactivity | | Both | (combined) | Whichever triggers first | Configure per-platform overrides in `~/.hermes/gateway.json`: @@ -204,7 +209,7 @@ Each platform has its own toolset: | Slack | `hermes-slack` | Full tools including terminal | | Signal | `hermes-signal` | Full tools including terminal | | Email | `hermes-email` | Full tools including terminal | -| Home Assistant | `hermes-gateway` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) | +| Home Assistant | `hermes-homeassistant` | Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services) | ## Next Steps diff --git a/website/docs/user-guide/messaging/signal.md b/website/docs/user-guide/messaging/signal.md index dae1e6eee..53bb862ad 100644 --- a/website/docs/user-guide/messaging/signal.md +++ b/website/docs/user-guide/messaging/signal.md @@ -192,8 +192,8 @@ The adapter monitors the SSE connection and automatically reconnects if: | **Messages not received** | Check that `SIGNAL_ALLOWED_USERS` includes the sender's number in E.164 format (with `+` prefix) | | **"signal-cli not found on PATH"** | Install signal-cli and ensure it's in your PATH, or use Docker | | **Connection keeps dropping** | Check signal-cli logs for errors. Ensure Java 17+ is installed. | -| **Group messages ignored** | `SIGNAL_GROUP_POLICY` defaults to `disabled`. Set to `allowlist` or `open`. | -| **Bot responds to everyone** | Set `SIGNAL_DM_POLICY=pairing` or `allowlist` and configure `SIGNAL_ALLOWED_USERS` | +| **Group messages ignored** | Configure `SIGNAL_GROUP_ALLOWED_USERS` with specific group IDs, or `*` to allow all groups. | +| **Bot responds to no one** | Configure `SIGNAL_ALLOWED_USERS`, use DM pairing, or explicitly allow all users through gateway policy if you want broader access. | | **Duplicate messages** | Ensure only one signal-cli instance is listening on your phone number | --- @@ -205,8 +205,8 @@ The adapter monitors the SSE connection and automatically reconnects if: ::: - Phone numbers are redacted in all log output -- Use `SIGNAL_DM_POLICY=pairing` (default) for safe onboarding of new users -- Keep groups disabled unless you specifically need group support +- Use DM pairing or explicit allowlists for safe onboarding of new users +- Keep groups disabled unless you specifically need group support, or allowlist only the groups you trust - Signal's end-to-end encryption protects message content in transit - The signal-cli session data in `~/.local/share/signal-cli/` contains account credentials — protect it like a password diff --git a/website/docs/user-guide/messaging/slack.md b/website/docs/user-guide/messaging/slack.md index 48608f68b..5ba6c7dde 100644 --- a/website/docs/user-guide/messaging/slack.md +++ b/website/docs/user-guide/messaging/slack.md @@ -20,7 +20,7 @@ the steps below. | Component | Value | |-----------|-------| -| **Library** | `@slack/bolt` (Socket Mode) | +| **Library** | `slack-bolt` / `slack_sdk` for Python (Socket Mode) | | **Connection** | WebSocket — no public URL required | | **Auth tokens needed** | Bot Token (`xoxb-`) + App-Level Token (`xapp-`) | | **User identification** | Slack Member IDs (e.g., `U01ABC2DEF3`) | diff --git a/website/docs/user-guide/messaging/whatsapp.md b/website/docs/user-guide/messaging/whatsapp.md index 22285eb63..8bdf28dd5 100644 --- a/website/docs/user-guide/messaging/whatsapp.md +++ b/website/docs/user-guide/messaging/whatsapp.md @@ -6,13 +6,10 @@ description: "Set up Hermes Agent as a WhatsApp bot via the built-in Baileys bri # WhatsApp Setup -Hermes connects to WhatsApp through a built-in bridge using [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js) -(Baileys-based). This works by emulating a WhatsApp Web session — **not** through the official -WhatsApp Business API. No Meta developer account or Business verification is required. +Hermes connects to WhatsApp through a built-in bridge based on **Baileys**. This works by emulating a WhatsApp Web session — **not** through the official WhatsApp Business API. No Meta developer account or Business verification is required. :::warning Unofficial API — Ban Risk -WhatsApp does **not** officially support third-party bots outside the Business API. Using -whatsapp-web.js carries a small risk of account restrictions. To minimize risk: +WhatsApp does **not** officially support third-party bots outside the Business API. Using a third-party bridge carries a small risk of account restrictions. To minimize risk: - **Use a dedicated phone number** for the bot (not your personal number) - **Don't send bulk/spam messages** — keep usage conversational - **Don't automate outbound messaging** to people who haven't messaged first @@ -20,7 +17,7 @@ whatsapp-web.js carries a small risk of account restrictions. To minimize risk: :::warning WhatsApp Web Protocol Updates WhatsApp periodically updates their Web protocol, which can temporarily break compatibility -with whatsapp-web.js. When this happens, Hermes will update the bridge dependency. If the +with third-party bridges. When this happens, Hermes will update the bridge dependency. If the bot stops working after a WhatsApp update, pull the latest Hermes version and re-pair. ::: @@ -38,21 +35,7 @@ bot stops working after a WhatsApp update, pull the latest Hermes version and re - **Node.js v18+** and **npm** — the WhatsApp bridge runs as a Node.js process - **A phone with WhatsApp** installed (for scanning the QR code) -**On Linux headless servers**, you also need Chromium/Puppeteer dependencies: - -```bash -# Debian / Ubuntu -sudo apt-get install -y \ - libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \ - libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \ - libpango-1.0-0 libcairo2 libasound2 libxshmfence1 - -# Fedora / RHEL -sudo dnf install -y \ - nss atk at-spi2-atk cups-libs libdrm libxkbcommon \ - libXcomposite libXdamage libXrandr mesa-libgbm \ - pango cairo alsa-lib -``` +Unlike older browser-driven bridges, the current Baileys-based bridge does **not** require a local Chromium or Puppeteer dependency stack. --- @@ -112,9 +95,6 @@ Add the following to your `~/.hermes/.env` file: WHATSAPP_ENABLED=true WHATSAPP_MODE=bot # "bot" or "self-chat" WHATSAPP_ALLOWED_USERS=15551234567 # Comma-separated phone numbers (with country code, no +) - -# Optional -WHATSAPP_HOME_CONTACT=15551234567 # Default contact for proactive/scheduled messages ``` Then start the gateway: @@ -130,12 +110,11 @@ The gateway starts the WhatsApp bridge automatically using the saved session. ## Session Persistence -The whatsapp-web.js `LocalAuth` strategy saves your session to the `.wwebjs_auth` folder inside -your Hermes data directory (`~/.hermes/`). This means: +The Baileys bridge saves its session under `~/.hermes/whatsapp/session`. This means: - **Sessions survive restarts** — you don't need to re-scan the QR code every time - The session data includes encryption keys and device credentials -- **Do not share or commit the `.wwebjs_auth` folder** — it grants full access to the WhatsApp account +- **Do not share or commit this session directory** — it grants full access to the WhatsApp account --- @@ -170,9 +149,9 @@ Hermes supports voice on WhatsApp: |---------|----------| | **QR code not scanning** | Ensure terminal is wide enough (60+ columns). Try a different terminal. Make sure you're scanning from the correct WhatsApp account (bot number, not personal). | | **QR code expires** | QR codes refresh every ~20 seconds. If it times out, restart `hermes whatsapp`. | -| **Session not persisting** | Check that `~/.hermes/.wwebjs_auth/` exists and is writable. On Docker, mount this as a volume. | -| **Logged out unexpectedly** | WhatsApp unlinks devices after ~14 days of phone inactivity. Keep the phone on and connected to WiFi. Re-pair with `hermes whatsapp`. | -| **"Execution context was destroyed"** | Chromium crashed. Install the Puppeteer dependencies listed in Prerequisites. On low-RAM servers, add swap space. | +| **Session not persisting** | Check that `~/.hermes/whatsapp/session` exists and is writable. If containerized, mount it as a persistent volume. | +| **Logged out unexpectedly** | WhatsApp unlinks devices after long inactivity. Keep the phone on and connected to the network, then re-pair with `hermes whatsapp` if needed. | +| **Bridge crashes or reconnect loops** | Restart the gateway, update Hermes, and re-pair if the session was invalidated by a WhatsApp protocol change. | | **Bot stops working after WhatsApp update** | Update Hermes to get the latest bridge version, then re-pair. | | **Messages not being received** | Verify `WHATSAPP_ALLOWED_USERS` includes the sender's number (with country code, no `+` or spaces). | @@ -186,8 +165,8 @@ of authorized users. Without this setting, the gateway will **deny all incoming safety measure. ::: -- The `.wwebjs_auth` folder contains full session credentials — protect it like a password -- Set file permissions: `chmod 700 ~/.hermes/.wwebjs_auth` +- The `~/.hermes/whatsapp/session` directory contains full session credentials — protect it like a password +- Set file permissions: `chmod 700 ~/.hermes/whatsapp/session` - Use a **dedicated phone number** for the bot to isolate risk from your personal account - If you suspect compromise, unlink the device from WhatsApp → Settings → Linked Devices - Phone numbers in logs are partially redacted, but review your log retention policy diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md index f468e632c..25398eded 100644 --- a/website/docs/user-guide/sessions.md +++ b/website/docs/user-guide/sessions.md @@ -271,7 +271,7 @@ Total messages: 3847 Database size: 12.4 MB ``` -For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use [`hermes insights`](/docs/reference/cli-commands#insights). +For deeper analytics — token usage, cost estimates, tool breakdown, and activity patterns — use [`hermes insights`](/docs/reference/cli-commands#hermes-insights). ## Session Search Tool diff --git a/website/sidebars.ts b/website/sidebars.ts index 6d767bb1e..e525ab58f 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -54,6 +54,7 @@ const sidebars: SidebarsConfig = { 'user-guide/features/memory', 'user-guide/features/context-files', 'user-guide/features/personality', + 'user-guide/features/skins', ], }, { @@ -111,6 +112,11 @@ const sidebars: SidebarsConfig = { label: 'Reference', items: [ 'reference/cli-commands', + 'reference/slash-commands', + 'reference/tools-reference', + 'reference/toolsets-reference', + 'reference/skills-catalog', + 'reference/optional-skills-catalog', 'reference/environment-variables', 'reference/faq', ],