289cc47631
Broad drift audit against origin/main (b52b63396). Reference pages (most user-visible drift): - slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer that were missing; drop non-existent /terminal-setup; fix /q footnote (resolves to /queue, not /quit); extend CLI-only list with all 24 CLI-only commands in the registry - cli-commands: add dedicated sections for hermes curator / fallback / hooks (new subcommands not previously documented); remove stale hermes honcho standalone section (the plugin registers dynamically via hermes memory); list curator/fallback/hooks in top-level table; fix completion to include fish - toolsets-reference: document the real 52-toolset count; split browser vs browser-cdp; add discord / discord_admin / spotify / yuanbao; correct hermes-cli tool count from 36 to 38; fix misleading claim that hermes-homeassistant adds tools (it's identical to hermes-cli) - tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao, 2 Discord toolsets; move browser_cdp/browser_dialog to their own browser-cdp toolset section - environment-variables: add 40+ user-facing HERMES_* vars that were undocumented (--yolo, --accept-hooks, --ignore-*, inference model override, agent/stream/checkpoint timeouts, OAuth trace, per-platform batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs, gateway restart/connect timeouts); dedupe the Cron Scheduler section; replace stale QQ_SANDBOX with QQ_PORTAL_HOST User-guide (top level): - cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20) - configuration.md: display.platforms is the canonical per-platform override key; tool_progress_overrides is deprecated and auto-migrated - profiles.md: model.default is the config key, not model.model - sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8 - checkpoints-and-rollback.md: destructive-command list now matches _DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd) - docker.md: the container runs as non-root hermes (UID 10000) via gosu; fix install command (uv pip); add missing --insecure on the dashboard compose example (required for non-loopback bind) - security.md: systemctl danger pattern also matches 'restart' - index.md: built-in tool count 47 -> 68 - integrations/index.md: 6 STT providers, 8 memory providers - integrations/providers.md: drop fictional dashscope/qwen aliases Features: - overview.md: 9 image models (not 8), 9 TTS providers (not 5), 8 memory providers (Supermemory was missing) - tool-gateway.md: 9 image models - tools.md: extend common-toolsets list with search / messaging / spotify / discord / debugging / safe - fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY (lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan, tencent-tokenhub, azure-foundry) - plugins.md: Available Hooks table now includes on_session_finalize, on_session_reset, subagent_stop - built-in-plugins.md: add the 7 bundled plugins the page didn't mention (spotify, google_meet, three image_gen providers, two dashboard examples) - web-dashboard.md: add --insecure and --tui flags - cron.md: hermes cron create takes positional schedule/prompt, not flags Messaging: - telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch. - discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default is 2.0, not 0.1 - dingtalk.md: document DINGTALK_REQUIRE_MENTION / FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL / ALLOW_ALL_USERS that the adapter supports - bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env var; the setting lives in platforms.bluebubbles.extra only - qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and QQ_GROUP_ALLOWED_USERS - wecom-callback.md: replace 'hermes gateway start' (service-only) with 'hermes gateway' for first-time setup Developer-guide: - architecture.md: refresh tool/toolset counts (61/52), terminal backend count (7), line counts for run_agent.py (~13.7k), cli.py (~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py (~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform adapter count 18 -> 20 - agent-loop.md: run_agent.py line count 10.7k -> 13.7k - tools-runtime.md: add vercel_sandbox backend - adding-tools.md: remove stale 'Discovery import added to model_tools.py' checklist item (registry auto-discovery) - adding-platform-adapters.md: mark send_typing / get_chat_info as concrete base methods; only connect/disconnect/send are abstract - acp-internals.md: ACP sessions now persist to SessionDB (~/.hermes/state.db); acp.run_agent call uses use_unstable_protocol=True - cron-internals.md: gateway runs scheduler in a dedicated background thread via _start_cron_ticker, not on a maintenance cycle; locking is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows) - gateway-internals.md: gateway/run.py ~12k lines - provider-runtime.md: cron DOES support fallback (run_job reads fallback_providers from config) - session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations 10 and 11 (trigram FTS, inline-mode FTS5 re-index); add api_call_count column to Sessions DDL; document messages_fts_trigram and state_meta in the architecture tree - context-compression-and-caching.md: remove the obsolete 'context pressure warnings' section (warnings were removed for causing models to give up early) - context-engine-plugin.md: compress() signature now includes focus_topic param - extending-the-cli.md: _build_tui_layout_children signature now includes model_picker_widget; add to default layout Also fixed three pre-existing broken links/anchors the build warned about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and tips#background-tasks, nix-setup.md -> #container-aware-cli). Regenerated per-skill pages via website/scripts/generate-skill-docs.py so catalog tables and sidebar are consistent with current SKILL.md frontmatter. docusaurus build: clean, no broken links or anchors.
160 lines
8.9 KiB
Markdown
160 lines
8.9 KiB
Markdown
---
|
|
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 control what the agent can do. They're the primary mechanism for configuring tool availability per platform, per session, or per task.
|
|
|
|
## How Toolsets Work
|
|
|
|
Every tool belongs to exactly one toolset. When you enable a toolset, all tools in that bundle become available to the agent. Toolsets come in three kinds:
|
|
|
|
- **Core** — A single logical group of related tools (e.g., `file` bundles `read_file`, `write_file`, `patch`, `search_files`)
|
|
- **Composite** — Combines multiple core toolsets for a common scenario (e.g., `debugging` bundles file, terminal, and web tools)
|
|
- **Platform** — A complete tool configuration for a specific deployment context (e.g., `hermes-cli` is the default for interactive CLI sessions)
|
|
|
|
## Configuring Toolsets
|
|
|
|
### Per-session (CLI)
|
|
|
|
```bash
|
|
hermes chat --toolsets web,file,terminal
|
|
hermes chat --toolsets debugging # composite — expands to file + terminal + web
|
|
hermes chat --toolsets all # everything
|
|
```
|
|
|
|
### Per-platform (config.yaml)
|
|
|
|
```yaml
|
|
toolsets:
|
|
- hermes-cli # default for CLI
|
|
# - hermes-telegram # override for Telegram gateway
|
|
```
|
|
|
|
### Interactive management
|
|
|
|
```bash
|
|
hermes tools # curses UI to enable/disable per platform
|
|
```
|
|
|
|
Or in-session:
|
|
|
|
```
|
|
/tools list
|
|
/tools disable browser
|
|
/tools enable rl
|
|
```
|
|
|
|
## Core Toolsets
|
|
|
|
| Toolset | Tools | Purpose |
|
|
|---------|-------|---------|
|
|
| `browser` | `browser_back`, `browser_click`, `browser_console`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `web_search` | Core browser automation. Includes `web_search` as a fallback for quick lookups. `browser_cdp` and `browser_dialog` live in a separate `browser-cdp` toolset and are registered only when a CDP endpoint is reachable at session start — via `/browser connect`, `browser.cdp_url` config, Browserbase, or Camofox. `browser_dialog` works together with the `pending_dialogs` and `frame_tree` fields that `browser_snapshot` adds when a CDP supervisor is attached. |
|
|
| `clarify` | `clarify` | Ask the user a question when the agent needs clarification. |
|
|
| `code_execution` | `execute_code` | Run Python scripts that call Hermes tools programmatically. |
|
|
| `cronjob` | `cronjob` | Schedule and manage recurring tasks. |
|
|
| `debugging` | composite (`file` + `terminal` + `web`) | Debug bundle — file, process/terminal, web extract/search. |
|
|
| `delegation` | `delegate_task` | Spawn isolated subagent instances for parallel work. |
|
|
| `discord` | `discord` | Core Discord text/embed/DM actions (gateway-only). Active on the `hermes-discord` toolset. |
|
|
| `discord_admin` | `discord_admin` | Discord moderation (bans, role changes, channel management). Active on the `hermes-discord` toolset; requires the bot to hold the relevant Discord permissions. |
|
|
| `feishu_doc` | `feishu_doc_read` | Read Feishu/Lark document content. Used by the Feishu document-comment intelligent-reply handler. |
|
|
| `feishu_drive` | `feishu_drive_add_comment`, `feishu_drive_list_comments`, `feishu_drive_list_comment_replies`, `feishu_drive_reply_comment` | Feishu/Lark drive comment operations. Scoped to the comment agent; not exposed on `hermes-cli` or other messaging toolsets. |
|
|
| `file` | `patch`, `read_file`, `search_files`, `write_file` | File reading, writing, searching, and editing. |
|
|
| `homeassistant` | `ha_call_service`, `ha_get_state`, `ha_list_entities`, `ha_list_services` | Smart home control via Home Assistant. Only available when `HASS_TOKEN` is set. |
|
|
| `image_gen` | `image_generate` | Text-to-image generation via FAL.ai (with opt-in OpenAI / xAI backends). |
|
|
| `memory` | `memory` | Persistent cross-session memory management. |
|
|
| `messaging` | `send_message` | Send messages to other platforms (Telegram, Discord, etc.) from within a session. |
|
|
| `moa` | `mixture_of_agents` | Multi-model consensus via Mixture of Agents. |
|
|
| `rl` | `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` | RL training environment management (Atropos). |
|
|
| `safe` | `image_generate`, `vision_analyze`, `web_extract`, `web_search` (via `includes`) | Read-only research + media generation. No file writes, no terminal, no code execution. |
|
|
| `search` | `web_search` | Web search only (without extract). |
|
|
| `session_search` | `session_search` | Search past conversation sessions. |
|
|
| `skills` | `skill_manage`, `skill_view`, `skills_list` | Skill CRUD and browsing. |
|
|
| `spotify` | `spotify_albums`, `spotify_devices`, `spotify_library`, `spotify_playback`, `spotify_playlists`, `spotify_queue`, `spotify_search` | Native Spotify control (playback, queue, search, playlists, albums, library). Registered by the bundled `spotify` plugin. |
|
|
| `terminal` | `process`, `terminal` | Shell command execution and background process management. |
|
|
| `todo` | `todo` | Task list management within a session. |
|
|
| `tts` | `text_to_speech` | Text-to-speech audio generation. |
|
|
| `vision` | `vision_analyze` | Image analysis via vision-capable models. |
|
|
| `web` | `web_extract`, `web_search` | Web search and page content extraction. |
|
|
| `yuanbao` | `yb_query_group_info`, `yb_query_group_members`, `yb_search_sticker`, `yb_send_dm`, `yb_send_sticker` | Yuanbao DM/group actions and sticker search. Registered only on `hermes-yuanbao`. |
|
|
|
|
## Platform Toolsets
|
|
|
|
Platform toolsets define the complete tool configuration for a deployment target. Most messaging platforms use the same set as `hermes-cli`:
|
|
|
|
| Toolset | Differences from `hermes-cli` |
|
|
|---------|-------------------------------|
|
|
| `hermes-cli` | Full toolset — 38 tools. The default for interactive CLI sessions. |
|
|
| `hermes-acp` | Drops `clarify`, `cronjob`, `image_generate`, `send_message`, `text_to_speech`, and all four Home Assistant tools. Focused on coding tasks in IDE context. |
|
|
| `hermes-api-server` | Drops `clarify`, `send_message`, and `text_to_speech`. Keeps everything else — suitable for programmatic access where user interaction isn't possible. |
|
|
| `hermes-cron` | Same as `hermes-cli`. |
|
|
| `hermes-telegram` | Same as `hermes-cli`. |
|
|
| `hermes-discord` | Adds `discord` and `discord_admin` on top of `hermes-cli`. |
|
|
| `hermes-slack` | Same as `hermes-cli`. |
|
|
| `hermes-whatsapp` | Same as `hermes-cli`. |
|
|
| `hermes-signal` | Same as `hermes-cli`. |
|
|
| `hermes-matrix` | Same as `hermes-cli`. |
|
|
| `hermes-mattermost` | Same as `hermes-cli`. |
|
|
| `hermes-email` | Same as `hermes-cli`. |
|
|
| `hermes-sms` | Same as `hermes-cli`. |
|
|
| `hermes-bluebubbles` | Same as `hermes-cli`. |
|
|
| `hermes-dingtalk` | Same as `hermes-cli`. |
|
|
| `hermes-feishu` | Adds the five `feishu_doc_*` / `feishu_drive_*` tools (only used by the document-comment handler, not the regular chat adapter). |
|
|
| `hermes-qqbot` | Same as `hermes-cli`. |
|
|
| `hermes-wecom` | Same as `hermes-cli`. |
|
|
| `hermes-wecom-callback` | Same as `hermes-cli`. |
|
|
| `hermes-weixin` | Same as `hermes-cli`. |
|
|
| `hermes-yuanbao` | Adds the five `yb_*` tools (DM/group/sticker) on top of `hermes-cli`. |
|
|
| `hermes-homeassistant` | Same as `hermes-cli` (the Home Assistant tools are already present by default and activate when `HASS_TOKEN` is set). |
|
|
| `hermes-webhook` | Same as `hermes-cli`. |
|
|
| `hermes-gateway` | Internal gateway orchestrator toolset — union of every `hermes-<platform>` toolset; used when the gateway needs to accept any message source. |
|
|
|
|
## Dynamic Toolsets
|
|
|
|
### MCP server toolsets
|
|
|
|
Each configured MCP server generates a `mcp-<server>` toolset at runtime. For example, if you configure a `github` MCP server, a `mcp-github` toolset is created containing all tools that server exposes.
|
|
|
|
```yaml
|
|
# config.yaml
|
|
mcp_servers:
|
|
github:
|
|
command: npx
|
|
args: ["-y", "@modelcontextprotocol/server-github"]
|
|
```
|
|
|
|
This creates a `mcp-github` toolset you can reference in `--toolsets` or platform configs.
|
|
|
|
### Plugin toolsets
|
|
|
|
Plugins can register their own toolsets via `ctx.register_tool()` during plugin initialization. These appear alongside built-in toolsets and can be enabled/disabled the same way.
|
|
|
|
### Custom toolsets
|
|
|
|
Define custom toolsets in `config.yaml` to create project-specific bundles:
|
|
|
|
```yaml
|
|
toolsets:
|
|
- hermes-cli
|
|
custom_toolsets:
|
|
data-science:
|
|
- file
|
|
- terminal
|
|
- code_execution
|
|
- web
|
|
- vision
|
|
```
|
|
|
|
### Wildcards
|
|
|
|
- `all` or `*` — expands to every registered toolset (built-in + dynamic + plugin)
|
|
|
|
## Relationship to `hermes tools`
|
|
|
|
The `hermes tools` command provides a curses-based UI for toggling individual tools on or off per platform. This operates at the tool level (finer than toolsets) and persists to `config.yaml`. Disabled tools are filtered out even if their toolset is enabled.
|
|
|
|
See also: [Tools Reference](./tools-reference.md) for the complete list of individual tools and their parameters.
|