diff --git a/website/docs/developer-guide/acp-internals.md b/website/docs/developer-guide/acp-internals.md index 0db8d94cd6..968b2b906a 100644 --- a/website/docs/developer-guide/acp-internals.md +++ b/website/docs/developer-guide/acp-internals.md @@ -27,7 +27,7 @@ hermes acp / hermes-acp / python -m acp_adapter -> load ~/.hermes/.env -> configure stderr logging -> construct HermesACPAgent - -> acp.run_agent(agent) + -> acp.run_agent(agent, use_unstable_protocol=True) ``` Stdout is reserved for ACP JSON-RPC transport. Human-readable logs go to stderr. @@ -170,7 +170,7 @@ ACP temporarily installs an approval callback on the terminal tool during prompt ## Current limitations -- ACP sessions are process-local from the ACP server's point of view +- ACP sessions are persisted to the shared `~/.hermes/state.db` (SessionDB) and transparently restored across process restarts; they appear in `session_search` - non-text prompt blocks are currently ignored for request text extraction - editor-specific UX varies by ACP client implementation diff --git a/website/docs/developer-guide/adding-platform-adapters.md b/website/docs/developer-guide/adding-platform-adapters.md index 1ddb07f08b..0f8438895f 100644 --- a/website/docs/developer-guide/adding-platform-adapters.md +++ b/website/docs/developer-guide/adding-platform-adapters.md @@ -18,11 +18,11 @@ User ↔ Messaging Platform ↔ Platform Adapter ↔ Gateway Runner ↔ AIAgent Every adapter extends `BasePlatformAdapter` from `gateway/platforms/base.py` and implements: -- **`connect()`** — Establish connection (WebSocket, long-poll, HTTP server, etc.) -- **`disconnect()`** — Clean shutdown -- **`send()`** — Send a text message to a chat -- **`send_typing()`** — Show typing indicator (optional) -- **`get_chat_info()`** — Return chat metadata +- **`connect()`** — Establish connection (WebSocket, long-poll, HTTP server, etc.) *(abstract)* +- **`disconnect()`** — Clean shutdown *(abstract)* +- **`send()`** — Send a text message to a chat *(abstract)* +- **`send_typing()`** — Show typing indicator (optional override) +- **`get_chat_info()`** — Return chat metadata (optional override) Inbound messages are received by the adapter and forwarded via `self.handle_message(event)`, which the base class routes to the gateway runner. diff --git a/website/docs/developer-guide/adding-tools.md b/website/docs/developer-guide/adding-tools.md index 497202bfce..f1ab79f31e 100644 --- a/website/docs/developer-guide/adding-tools.md +++ b/website/docs/developer-guide/adding-tools.md @@ -192,7 +192,6 @@ OPTIONAL_ENV_VARS = { - [ ] Tool file created with handler, schema, check function, and registration - [ ] Added to appropriate toolset in `toolsets.py` -- [ ] Discovery import added to `model_tools.py` - [ ] Handler returns JSON strings, errors returned as `{"error": "..."}` - [ ] Optional: API key added to `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` - [ ] Optional: Added to `toolset_distributions.py` for batch processing diff --git a/website/docs/developer-guide/agent-loop.md b/website/docs/developer-guide/agent-loop.md index 8cf6adeae6..4ca66b5628 100644 --- a/website/docs/developer-guide/agent-loop.md +++ b/website/docs/developer-guide/agent-loop.md @@ -6,7 +6,7 @@ description: "Detailed walkthrough of AIAgent execution, API modes, tools, callb # Agent Loop Internals -The core orchestration engine is `run_agent.py`'s `AIAgent` class — roughly 10,700 lines that handle everything from prompt assembly to tool dispatch to provider failover. +The core orchestration engine is `run_agent.py`'s `AIAgent` class — roughly 13,700 lines that handle everything from prompt assembly to tool dispatch to provider failover. ## Core Responsibilities @@ -222,7 +222,7 @@ After each turn: | File | Purpose | |------|---------| -| `run_agent.py` | AIAgent class — the complete agent loop (~10,700 lines) | +| `run_agent.py` | AIAgent class — the complete agent loop (~13,700 lines) | | `agent/prompt_builder.py` | System prompt assembly from memory, skills, context files, personality | | `agent/context_engine.py` | ContextEngine ABC — pluggable context management | | `agent/context_compressor.py` | Default engine — lossy summarization algorithm | diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md index f153e47cbb..c890193419 100644 --- a/website/docs/developer-guide/architecture.md +++ b/website/docs/developer-guide/architecture.md @@ -32,15 +32,15 @@ This page is the top-level map of Hermes Agent internals. Use it to orient yours │ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │ │ │ Compression │ │ 3 API Modes │ │ Tool Registry│ │ │ │ & Caching │ │ chat_compl. │ │ (registry.py)│ │ -│ │ │ │ codex_resp. │ │ 47 tools │ │ -│ │ │ │ anthropic │ │ 19 toolsets │ │ +│ │ │ │ codex_resp. │ │ 61 tools │ │ +│ │ │ │ anthropic │ │ 52 toolsets │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────┴─────────────────┴─────────────────┴───────────────────────┘ │ │ ▼ ▼ ┌───────────────────┐ ┌──────────────────────┐ │ Session Storage │ │ Tool Backends │ -│ (SQLite + FTS5) │ │ Terminal (6 backends) │ +│ (SQLite + FTS5) │ │ Terminal (7 backends) │ │ hermes_state.py │ │ Browser (5 backends) │ │ gateway/session.py│ │ Web (4 backends) │ └───────────────────┘ │ MCP (dynamic) │ @@ -52,8 +52,8 @@ This page is the top-level map of Hermes Agent internals. Use it to orient yours ```text hermes-agent/ -├── run_agent.py # AIAgent — core conversation loop (~10,700 lines) -├── cli.py # HermesCLI — interactive terminal UI (~10,000 lines) +├── run_agent.py # AIAgent — core conversation loop (~13,700 lines) +├── cli.py # HermesCLI — interactive terminal UI (~11,500 lines) ├── model_tools.py # Tool discovery, schema collection, dispatch ├── toolsets.py # Tool groupings and platform presets ├── hermes_state.py # SQLite session/state database with FTS5 @@ -76,14 +76,14 @@ hermes-agent/ │ └── trajectory.py # Trajectory saving helpers │ ├── hermes_cli/ # CLI subcommands and setup -│ ├── main.py # Entry point — all `hermes` subcommands (~6,000 lines) +│ ├── main.py # Entry point — all `hermes` subcommands (~10,400 lines) │ ├── config.py # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration │ ├── commands.py # COMMAND_REGISTRY — central slash command definitions │ ├── auth.py # PROVIDER_REGISTRY, credential resolution │ ├── runtime_provider.py # Provider → api_mode + credentials │ ├── models.py # Model catalog, provider model lists │ ├── model_switch.py # /model command logic (CLI + gateway shared) -│ ├── setup.py # Interactive setup wizard (~3,100 lines) +│ ├── setup.py # Interactive setup wizard (~3,500 lines) │ ├── skin_engine.py # CLI theming engine │ ├── skills_config.py # hermes skills — enable/disable per platform │ ├── skills_hub.py # /skills slash command @@ -102,14 +102,14 @@ hermes-agent/ │ ├── browser_tool.py # 10 browser automation tools │ ├── code_execution_tool.py # execute_code sandbox │ ├── delegate_tool.py # Subagent delegation -│ ├── mcp_tool.py # MCP client (~2,200 lines) +│ ├── mcp_tool.py # MCP client (~3,100 lines) │ ├── credential_files.py # File-based credential passthrough │ ├── env_passthrough.py # Env var passthrough for sandboxes │ ├── ansi_strip.py # ANSI escape stripping │ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity) │ ├── gateway/ # Messaging platform gateway -│ ├── run.py # GatewayRunner — message dispatch (~9,000 lines) +│ ├── run.py # GatewayRunner — message dispatch (~12,200 lines) │ ├── session.py # SessionStore — conversation persistence │ ├── delivery.py # Outbound message delivery │ ├── pairing.py # DM pairing authorization @@ -117,10 +117,11 @@ hermes-agent/ │ ├── mirror.py # Cross-session message mirroring │ ├── status.py # Token locks, profile-scoped process tracking │ ├── builtin_hooks/ # Extension point for always-registered hooks (none shipped) -│ └── platforms/ # 18 adapters: telegram, discord, slack, whatsapp, +│ └── platforms/ # 20 adapters: telegram, discord, slack, whatsapp, │ # signal, matrix, mattermost, email, sms, │ # dingtalk, feishu, wecom, wecom_callback, weixin, -│ # bluebubbles, qqbot, homeassistant, webhook, api_server +│ # bluebubbles, qqbot, homeassistant, webhook, api_server, +│ # yuanbao │ ├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains) ├── cron/ # Scheduler (jobs.py, scheduler.py) @@ -212,7 +213,7 @@ A shared runtime resolver used by CLI, gateway, cron, ACP, and auxiliary calls. ### Tool System -Central tool registry (`tools/registry.py`) with 47 registered tools across 19 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 6 backends (local, Docker, SSH, Daytona, Modal, Singularity). +Central tool registry (`tools/registry.py`) with 61 registered tools across 52 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 7 backends (local, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox). → [Tools Runtime](./tools-runtime.md) @@ -224,7 +225,7 @@ SQLite-based session storage with FTS5 full-text search. Sessions have lineage t ### Messaging Gateway -Long-running process with 18 platform adapters, unified session routing, user authorization (allowlists + DM pairing), slash command dispatch, hook system, cron ticking, and background maintenance. +Long-running process with 20 platform adapters, unified session routing, user authorization (allowlists + DM pairing), slash command dispatch, hook system, cron ticking, and background maintenance. → [Gateway Internals](./gateway-internals.md) diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md index bf7610c250..5c6268bbce 100644 --- a/website/docs/developer-guide/context-compression-and-caching.md +++ b/website/docs/developer-guide/context-compression-and-caching.md @@ -345,14 +345,4 @@ The CLI shows caching status at startup: ## Context Pressure Warnings -The agent emits context pressure warnings at 85% of the compression threshold -(not 85% of context — 85% of the threshold which is itself 50% of context): - -``` -⚠️ Context is 85% to compaction threshold (42,500/50,000 tokens) -``` - -After compression, if usage drops below 85% of threshold, the warning state -is cleared. If compression fails to reduce below the warning level (the -conversation is too dense), the warning persists but compression won't -re-trigger until the threshold is exceeded again. +Intermediate context-pressure warnings have been removed (see the iteration-budget block in `run_agent.py`, which notes: "No intermediate pressure warnings — they caused models to 'give up' prematurely on complex tasks"). Compression fires when prompt tokens reach the configured `compression.threshold` (default 50%) with no prior warning step; gateway session hygiene fires as the secondary safety net at 85% of the model's context window. diff --git a/website/docs/developer-guide/context-engine-plugin.md b/website/docs/developer-guide/context-engine-plugin.md index 5a606f8ea0..64fea96acb 100644 --- a/website/docs/developer-guide/context-engine-plugin.md +++ b/website/docs/developer-guide/context-engine-plugin.md @@ -58,10 +58,15 @@ class LCMEngine(ContextEngine): def should_compress(self, prompt_tokens: int = None) -> bool: """Return True if compaction should fire this turn.""" - def compress(self, messages: list, current_tokens: int = None) -> list: + def compress(self, messages: list, current_tokens: int = None, + focus_topic: str = None) -> list: """Compact the message list and return a new (possibly shorter) list. The returned list must be a valid OpenAI-format message sequence. + + ``focus_topic`` is an optional topic string from manual + ``/compress ``; engines that support guided compression should + prioritise preserving information related to it, others may ignore it. """ ``` diff --git a/website/docs/developer-guide/cron-internals.md b/website/docs/developer-guide/cron-internals.md index d5bd237de0..12f817f656 100644 --- a/website/docs/developer-guide/cron-internals.md +++ b/website/docs/developer-guide/cron-internals.md @@ -102,7 +102,7 @@ tick() ### Gateway Integration -In gateway mode, the scheduler tick is integrated into the gateway's main event loop. The gateway calls `scheduler.tick()` on its periodic maintenance cycle, which runs alongside message handling. +In gateway mode, the scheduler runs in a dedicated background thread (`_start_cron_ticker` in `gateway/run.py`) that calls `scheduler.tick()` every 60 seconds alongside message handling. In CLI mode, cron jobs only fire when `hermes cron` commands are run or during active CLI sessions. @@ -205,7 +205,7 @@ Cron-run sessions have the `cronjob` toolset disabled. This prevents: ## Locking -The scheduler uses file-based locking to prevent overlapping ticks from executing the same due-job batch twice. This is important in gateway mode where multiple maintenance cycles could overlap if a previous tick takes longer than the tick interval. +The scheduler uses cross-process file-based locking (`fcntl.flock` on Unix, `msvcrt.locking` on Windows) to prevent overlapping ticks from executing the same due-job batch twice — even between the gateway's in-process ticker and a standalone `hermes cron` / manual `tick()` call. If the lock cannot be acquired, `tick()` returns 0 immediately. ## CLI Interface diff --git a/website/docs/developer-guide/extending-the-cli.md b/website/docs/developer-guide/extending-the-cli.md index c7aedd9c4c..fbd6da6f94 100644 --- a/website/docs/developer-guide/extending-the-cli.md +++ b/website/docs/developer-guide/extending-the-cli.md @@ -141,12 +141,13 @@ Override this only when you need full control over widget ordering. Most extensi ```python def _build_tui_layout_children(self, *, sudo_widget, secret_widget, - approval_widget, clarify_widget, spinner_widget, spacer, - status_bar, input_rule_top, image_bar, input_area, - input_rule_bot, voice_status_bar, completions_menu) -> list: + approval_widget, clarify_widget, model_picker_widget=None, + spinner_widget=None, spacer, status_bar, input_rule_top, + image_bar, input_area, input_rule_bot, voice_status_bar, + completions_menu) -> list: ``` -The default implementation returns: +The default implementation returns (any `None` widgets are filtered out): ```python [ @@ -155,6 +156,7 @@ The default implementation returns: secret_widget, # secret input prompt (conditional) approval_widget, # dangerous command approval (conditional) clarify_widget, # clarify question UI (conditional) + model_picker_widget, # model picker overlay (conditional) spinner_widget, # thinking spinner (conditional) spacer, # fills remaining vertical space *self._get_extra_tui_widgets(), # YOUR WIDGETS GO HERE diff --git a/website/docs/developer-guide/gateway-internals.md b/website/docs/developer-guide/gateway-internals.md index 4ed68082b6..e10fe6821f 100644 --- a/website/docs/developer-guide/gateway-internals.md +++ b/website/docs/developer-guide/gateway-internals.md @@ -12,7 +12,7 @@ The messaging gateway is the long-running process that connects Hermes to 14+ ex | File | Purpose | |------|---------| -| `gateway/run.py` | `GatewayRunner` — main loop, slash commands, message dispatch (~9,000 lines) | +| `gateway/run.py` | `GatewayRunner` — main loop, slash commands, message dispatch (~12,000 lines) | | `gateway/session.py` | `SessionStore` — conversation persistence and session key construction | | `gateway/delivery.py` | Outbound message delivery to target platforms/channels | | `gateway/pairing.py` | DM pairing flow for user authorization | diff --git a/website/docs/developer-guide/provider-runtime.md b/website/docs/developer-guide/provider-runtime.md index bf9abe0ce5..415962f90b 100644 --- a/website/docs/developer-guide/provider-runtime.md +++ b/website/docs/developer-guide/provider-runtime.md @@ -179,9 +179,10 @@ Hermes supports a configured fallback model/provider pair, allowing runtime fail ### What does NOT support fallback - **Subagent delegation** (`tools/delegate_tool.py`): subagents inherit the parent's provider but not the fallback config -- **Cron jobs** (`cron/`): run with a fixed provider, no fallback mechanism - **Auxiliary tasks**: use their own independent provider auto-detection chain (see Auxiliary model routing above) +Cron jobs **do** support fallback: `run_job()` reads `fallback_providers` (or legacy `fallback_model`) from `config.yaml` and passes it to `AIAgent(fallback_model=...)`, matching the gateway's `_load_fallback_model()` pattern. See [Cron Internals](./cron-internals.md). + ### Test coverage See `tests/test_fallback_model.py` for comprehensive tests covering all supported providers, one-shot semantics, and edge cases. diff --git a/website/docs/developer-guide/session-storage.md b/website/docs/developer-guide/session-storage.md index a7868976c0..55da265595 100644 --- a/website/docs/developer-guide/session-storage.md +++ b/website/docs/developer-guide/session-storage.md @@ -11,10 +11,12 @@ Source file: `hermes_state.py` ``` ~/.hermes/state.db (SQLite, WAL mode) -├── sessions — Session metadata, token counts, billing -├── messages — Full message history per session -├── messages_fts — FTS5 virtual table for full-text search -└── schema_version — Single-row table tracking migration state +├── sessions — Session metadata, token counts, billing +├── messages — Full message history per session +├── messages_fts — FTS5 virtual table (content + tool_name + tool_calls) +├── messages_fts_trigram — FTS5 virtual table with trigram tokenizer (CJK / substring search) +├── state_meta — Key/value metadata table +└── schema_version — Single-row table tracking migration state ``` Key design decisions: @@ -57,6 +59,7 @@ CREATE TABLE IF NOT EXISTS sessions ( cost_source TEXT, pricing_version TEXT, title TEXT, + api_call_count INTEGER DEFAULT 0, FOREIGN KEY (parent_session_id) REFERENCES sessions(id) ); @@ -130,10 +133,9 @@ END; ## Schema Version and Migrations -Current schema version: **9** +Current schema version: **11** -The `schema_version` table stores a single integer. On initialization, -`_init_schema()` checks the current version and applies migrations sequentially: +The `schema_version` table stores a single integer. Simple column additions are handled declaratively by `_reconcile_columns()` (which diffs live columns against `SCHEMA_SQL` and ADDs any missing ones). The version-gated chain is reserved for data migrations and index/FTS changes that can't be expressed declaratively: | Version | Change | |---------|--------| @@ -146,10 +148,10 @@ The `schema_version` table stores a single integer. On initialization, | 7 | Add `reasoning_content` column to messages | | 8 | Add `api_call_count` column to sessions | | 9 | Add `codex_message_items` column to messages for Codex Responses message id/phase replay | +| 10 | Add `messages_fts_trigram` virtual table (trigram tokenizer for CJK / substring search) and backfill existing rows | +| 11 | Re-index `messages_fts` and `messages_fts_trigram` to cover `tool_name` + `tool_calls` and switch from external-content to inline mode; drop old triggers and backfill every message row | -Each migration uses `ALTER TABLE ADD COLUMN` wrapped in try/except to handle -the column-already-exists case (idempotent). The version number is bumped after -each successful migration block. +Declarative column adds use `ALTER TABLE ADD COLUMN` wrapped in try/except to handle the column-already-exists case (idempotent). The version number is bumped after each successful migration block. ## Write Contention Handling diff --git a/website/docs/developer-guide/tools-runtime.md b/website/docs/developer-guide/tools-runtime.md index 851ad6bc96..f6036fbda8 100644 --- a/website/docs/developer-guide/tools-runtime.md +++ b/website/docs/developer-guide/tools-runtime.md @@ -213,6 +213,7 @@ The terminal system supports multiple backends: - singularity - modal - daytona +- vercel_sandbox It also supports: diff --git a/website/docs/getting-started/nix-setup.md b/website/docs/getting-started/nix-setup.md index 75fb8fd28f..ceeabec9c6 100644 --- a/website/docs/getting-started/nix-setup.md +++ b/website/docs/getting-started/nix-setup.md @@ -943,6 +943,6 @@ nix-store --query --roots $(docker exec hermes-agent readlink /data/current-pack | `hermes version` shows old version | Container not restarted | `systemctl restart hermes-agent` | | Permission denied on `/var/lib/hermes` | State dir is `0750 hermes:hermes` | Use `docker exec` or `sudo -u hermes` | | `nix-collect-garbage` removed hermes | GC root missing | Restart the service (preStart recreates the GC root) | -| `no container with name or ID "hermes-agent"` (Podman) | Podman rootful container not visible to regular user | Add passwordless sudo for podman (see [Container-aware CLI](#container-aware-cli) section) | +| `no container with name or ID "hermes-agent"` (Podman) | Podman rootful container not visible to regular user | Add passwordless sudo for podman (see [Container Mode](#container-mode) section) | | `unable to find user hermes` | Container still starting (entrypoint hasn't created user yet) | Wait a few seconds and retry — the CLI retries automatically | | Tool added via `extraPackages` not found in terminal | Requires `nixos-rebuild switch` to update the per-user profile | Rebuild and restart: `nixos-rebuild switch && systemctl restart hermes-agent` | diff --git a/website/docs/index.md b/website/docs/index.md index 01dcf35dc0..de7ef698bf 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -29,7 +29,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl | 🗺️ **[Learning Path](/docs/getting-started/learning-path)** | Find the right docs for your experience level | | ⚙️ **[Configuration](/docs/user-guide/configuration)** | Config file, providers, models, and options | | 💬 **[Messaging Gateway](/docs/user-guide/messaging)** | Set up Telegram, Discord, Slack, or WhatsApp | -| 🔧 **[Tools & Toolsets](/docs/user-guide/features/tools)** | 47 built-in tools and how to configure them | +| 🔧 **[Tools & Toolsets](/docs/user-guide/features/tools)** | 68 built-in tools and how to configure them | | 🧠 **[Memory System](/docs/user-guide/features/memory)** | Persistent memory that grows across sessions | | 📚 **[Skills System](/docs/user-guide/features/skills)** | Procedural memory the agent creates and reuses | | 🔌 **[MCP Integration](/docs/user-guide/features/mcp)** | Connect to MCP servers, filter their tools, and extend Hermes safely | diff --git a/website/docs/integrations/index.md b/website/docs/integrations/index.md index ccb7853702..f511e03bf5 100644 --- a/website/docs/integrations/index.md +++ b/website/docs/integrations/index.md @@ -63,7 +63,7 @@ Text-to-speech and speech-to-text across all messaging platforms: || **MiniMax** | Good | Paid | `MINIMAX_API_KEY` | || **NeuTTS** | Good | Free | None needed | -Speech-to-text supports three providers: local Whisper (free, runs on-device), Groq (fast cloud), and OpenAI Whisper API. Voice message transcription works across Telegram, Discord, WhatsApp, and other messaging platforms. See [Voice & TTS](/docs/user-guide/features/tts) and [Voice Mode](/docs/user-guide/features/voice-mode) for details. +Speech-to-text supports six providers: local faster-whisper (free, runs on-device), a local command wrapper, Groq, OpenAI Whisper API, Mistral, and xAI. Voice message transcription works across Telegram, Discord, WhatsApp, and other messaging platforms. See [Voice & TTS](/docs/user-guide/features/tts) and [Voice Mode](/docs/user-guide/features/voice-mode) for details. ## IDE & Editor Integration @@ -76,7 +76,7 @@ Speech-to-text supports three providers: local Whisper (free, runs on-device), G ## Memory & Personalization - **[Built-in Memory](/docs/user-guide/features/memory)** — Persistent, curated memory via `MEMORY.md` and `USER.md` files. The agent maintains bounded stores of personal notes and user profile data that survive across sessions. -- **[Memory Providers](/docs/user-guide/features/memory-providers)** — Plug in external memory backends for deeper personalization. Seven providers are supported: Honcho (dialectic reasoning), OpenViking (tiered retrieval), Mem0 (cloud extraction), Hindsight (knowledge graphs), Holographic (local SQLite), RetainDB (hybrid search), and ByteRover (CLI-based). +- **[Memory Providers](/docs/user-guide/features/memory-providers)** — Plug in external memory backends for deeper personalization. Eight providers are supported: Honcho (dialectic reasoning), OpenViking (tiered retrieval), Mem0 (cloud extraction), Hindsight (knowledge graphs), Holographic (local SQLite), RetainDB (hybrid search), ByteRover (CLI-based), and Supermemory. ## Messaging Platforms diff --git a/website/docs/integrations/providers.md b/website/docs/integrations/providers.md index 7cbb9db5e2..80d122b7b2 100644 --- a/website/docs/integrations/providers.md +++ b/website/docs/integrations/providers.md @@ -28,7 +28,7 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro | **GMI Cloud** | `GMI_API_KEY` in `~/.hermes/.env` (provider: `gmi`; aliases: `gmi-cloud`, `gmicloud`) | | **MiniMax** | `MINIMAX_API_KEY` in `~/.hermes/.env` (provider: `minimax`) | | **MiniMax China** | `MINIMAX_CN_API_KEY` in `~/.hermes/.env` (provider: `minimax-cn`) | -| **Alibaba Cloud** | `DASHSCOPE_API_KEY` in `~/.hermes/.env` (provider: `alibaba`, aliases: `dashscope`, `qwen`) | +| **Alibaba Cloud** | `DASHSCOPE_API_KEY` in `~/.hermes/.env` (provider: `alibaba`) | | **Alibaba Coding Plan** | `DASHSCOPE_API_KEY` (provider: `alibaba-coding-plan`, alias: `alibaba_coding`) — separate billing SKU, different endpoint | | **Kilo Code** | `KILOCODE_API_KEY` in `~/.hermes/.env` (provider: `kilocode`) | | **Xiaomi MiMo** | `XIAOMI_API_KEY` in `~/.hermes/.env` (provider: `xiaomi`, aliases: `mimo`, `xiaomi-mimo`) | diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index ac600bbeef..933cb64732 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -38,6 +38,7 @@ hermes [global-options] [subcommand/options] |---------|---------| | `hermes chat` | Interactive or one-shot chat with the agent. | | `hermes model` | Interactively choose the default provider and model. | +| `hermes fallback` | Manage fallback providers tried when the primary model errors. | | `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. | @@ -47,6 +48,7 @@ hermes [global-options] [subcommand/options] | `hermes status` | Show agent, auth, and platform status. | | `hermes cron` | Inspect and tick the cron scheduler. | | `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. | +| `hermes hooks` | Inspect, approve, or remove shell-script hooks declared in `config.yaml`. | | `hermes doctor` | Diagnose config and dependency issues. | | `hermes dump` | Copy-pasteable setup summary for support/debugging. | | `hermes debug` | Debug tools — upload logs and system info for support. | @@ -56,8 +58,8 @@ hermes [global-options] [subcommand/options] | `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 memory` | Configure external memory provider. | +| `hermes curator` | Background skill maintenance — status, run, pause, pin. See [Curator](../user-guide/features/curator.md). | +| `hermes memory` | Configure external memory provider. Plugin-specific subcommands (e.g. `hermes honcho`) register automatically when their provider is active. | | `hermes acp` | Run Hermes as an ACP server for editor integration. | | `hermes mcp` | Manage MCP server configurations and run Hermes as an MCP server. | | `hermes plugins` | Manage Hermes Agent plugins (install, enable, disable, remove). | @@ -68,7 +70,7 @@ hermes [global-options] [subcommand/options] | `hermes claw` | OpenClaw migration helpers. | | `hermes dashboard` | Launch the web dashboard for managing config, API keys, and sessions. | | `hermes profile` | Manage profiles — multiple isolated Hermes instances. | -| `hermes completion` | Print shell completion scripts (bash/zsh). | +| `hermes completion` | Print shell completion scripts (bash/zsh/fish). | | `hermes version` | Show version information. | | `hermes update` | Pull latest code and reinstall dependencies. `--check` prints commit diff without pulling; `--backup` takes a pre-pull `HERMES_HOME` snapshot. | | `hermes uninstall` | Remove Hermes from the system. | @@ -671,33 +673,59 @@ Notes: - `--source well-known` lets you point Hermes at a site exposing `/.well-known/skills/index.json`. - Passing an `http(s)://…/*.md` URL installs a single-file SKILL.md directly. When frontmatter has no `name:` and the URL slug isn't a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (`/skills install` inside the TUI, gateway platforms) require `--name ` instead. -## `hermes honcho` +## `hermes curator` ```bash -hermes honcho [--target-profile NAME] +hermes curator ``` -Manage Honcho cross-session memory integration. This command is provided by the Honcho memory provider plugin and is only available when `memory.provider` is set to `honcho` in your config. - -The `--target-profile` flag lets you manage another profile's Honcho config without switching to it. - -Subcommands: +The curator is an auxiliary-model background task that periodically reviews agent-created skills, prunes stale ones, consolidates overlaps, and archives obsolete skills. Bundled and hub-installed skills are never touched. Archives are recoverable; auto-deletion never happens. | Subcommand | Description | |------------|-------------| -| `setup` | Redirects to `hermes memory setup` (unified setup path). | -| `status [--all]` | Show current Honcho config and connection status. `--all` shows a cross-profile overview. | -| `peers` | Show peer identities across all profiles. | -| `sessions` | List known Honcho session mappings. | -| `map [name]` | Map the current directory to a Honcho session name. Omit `name` to list current mappings. | -| `peer` | Show or update peer names and dialectic reasoning level. Options: `--user NAME`, `--ai NAME`, `--reasoning LEVEL`. | -| `mode [mode]` | Show or set recall mode: `hybrid`, `context`, or `tools`. Omit to show current. | -| `tokens` | Show or set token budgets for context and dialectic. Options: `--context N`, `--dialectic N`. | -| `identity [file] [--show]` | Seed or show the AI peer identity representation. | -| `enable` | Enable Honcho for the active profile. | -| `disable` | Disable Honcho for the active profile. | -| `sync` | Sync Honcho config to all existing profiles (creates missing host blocks). | -| `migrate` | Step-by-step migration guide from openclaw-honcho to Hermes Honcho. | +| `status` | Show curator status and skill stats | +| `run` | Trigger a curator review now | +| `pause` | Pause the curator until resumed | +| `resume` | Resume a paused curator | +| `pin ` | Pin a skill so the curator never auto-transitions it | +| `unpin ` | Unpin a skill | +| `restore ` | Restore an archived skill | + +See [Curator](../user-guide/features/curator.md) for behavior and config. + +## `hermes fallback` + +```bash +hermes fallback +``` + +Manage the fallback provider chain. Fallback providers are tried in order when the primary model fails with rate-limit, overload, or connection errors. + +| Subcommand | Description | +|------------|-------------| +| `list` (alias: `ls`) | Show the current fallback chain (default when no subcommand) | +| `add` | Pick a provider + model (same picker as `hermes model`) and append to the chain | +| `remove` (alias: `rm`) | Pick an entry to delete from the chain | +| `clear` | Remove all fallback entries | + +See [Fallback Providers](../user-guide/features/fallback-providers.md). + +## `hermes hooks` + +```bash +hermes hooks +``` + +Inspect shell-script hooks declared in `~/.hermes/config.yaml`, test them against synthetic payloads, and manage the first-use consent allowlist at `~/.hermes/shell-hooks-allowlist.json`. + +| Subcommand | Description | +|------------|-------------| +| `list` (alias: `ls`) | List configured hooks with matcher, timeout, and consent status | +| `test ` | Fire every hook matching `` against a synthetic payload | +| `revoke` (aliases: `remove`, `rm`) | Remove a command's allowlist entries (takes effect on next restart) | +| `doctor` | Check each configured hook: exec bit, allowlist, mtime drift, JSON validity, and synthetic run timing | + +See [Hooks](../user-guide/features/hooks.md) for event signatures and payload shapes. ## `hermes memory` @@ -715,6 +743,10 @@ Subcommands: | `status` | Show current memory provider config. | | `off` | Disable external provider (built-in only). | +:::info Provider-specific subcommands +When an external memory provider is active, it may register its own top-level `hermes ` command for provider-specific management (e.g. `hermes honcho` when Honcho is active). Inactive providers do not expose their subcommands. Run `hermes --help` to see what's currently wired in. +::: + ## `hermes acp` ```bash @@ -935,7 +967,7 @@ hermes -p work chat -q "Hello from work profile" ## `hermes completion` ```bash -hermes completion [bash|zsh] +hermes completion [bash|zsh|fish] ``` Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Hermes commands, subcommands, and profile names. @@ -948,6 +980,9 @@ hermes completion bash >> ~/.bashrc # Zsh hermes completion zsh >> ~/.zshrc + +# Fish +hermes completion fish > ~/.config/fish/completions/hermes.fish ``` ## `hermes update` diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 671b66573f..8a4ab19289 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -225,7 +225,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `TELEGRAM_HOME_CHANNEL_NAME` | Display name for the Telegram home channel | | `TELEGRAM_WEBHOOK_URL` | Public HTTPS URL for webhook mode (enables webhook instead of polling) | | `TELEGRAM_WEBHOOK_PORT` | Local listen port for webhook server (default: `8443`) | -| `TELEGRAM_WEBHOOK_SECRET` | Secret token for verifying updates come from Telegram | +| `TELEGRAM_WEBHOOK_SECRET` | Secret token Telegram echoes back in each update for verification. **Required whenever `TELEGRAM_WEBHOOK_URL` is set** — the gateway refuses to start without it (GHSA-3vpc-7q5r-276h). Generate with `openssl rand -hex 32`. | | `TELEGRAM_REACTIONS` | Enable emoji reactions on messages during processing (default: `false`) | | `TELEGRAM_REPLY_TO_MODE` | Reply-reference behavior: `off`, `first` (default), or `all`. Matches the Discord pattern. | | `TELEGRAM_IGNORED_THREADS` | Comma-separated Telegram forum topic/thread IDs where the bot never responds | @@ -341,7 +341,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `QQ_ALLOW_ALL_USERS` | Allow all users (`true`/`false`, overrides `QQ_ALLOWED_USERS`) | | `QQBOT_HOME_CHANNEL` | QQ user/group openID for cron delivery and notifications | | `QQBOT_HOME_CHANNEL_NAME` | Display name for the QQ home channel | -| `QQ_SANDBOX` | Route QQ Bot to the sandbox gateway for development testing (`true`/`false`). Use with a sandbox app credential from [q.qq.com](https://q.qq.com). | +| `QQ_PORTAL_HOST` | Override the QQ portal host (set to `sandbox.q.qq.com` to route through the sandbox gateway; default: `q.qq.com`). | | `MATTERMOST_URL` | Mattermost server URL (e.g. `https://mm.example.com`) | | `MATTERMOST_TOKEN` | Bot token or personal access token for Mattermost | | `MATTERMOST_ALLOWED_USERS` | Comma-separated Mattermost user IDs allowed to message the bot | @@ -380,11 +380,45 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms | | `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlists (`true`/`false`, default: `false`) | +### Advanced Messaging Tuning + +Advanced per-platform knobs for throttling the outbound message batcher. Most users never need to touch these; defaults are set to respect each platform's rate limits without feeling sluggish. + +| Variable | Description | +|----------|-------------| +| `HERMES_TELEGRAM_TEXT_BATCH_DELAY_SECONDS` | Grace window before flushing a queued Telegram text chunk (default: `0.6`). | +| `HERMES_TELEGRAM_TEXT_BATCH_SPLIT_DELAY_SECONDS` | Delay between split chunks when a single Telegram message exceeds the length limit (default: `2.0`). | +| `HERMES_TELEGRAM_MEDIA_BATCH_DELAY_SECONDS` | Grace window before flushing queued Telegram media (default: `0.6`). | +| `HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS` | Delay before sending a follow-up after the agent finishes, to avoid racing the last stream chunk. | +| `HERMES_TELEGRAM_HTTP_CONNECT_TIMEOUT` / `_READ_TIMEOUT` / `_WRITE_TIMEOUT` / `_POOL_TIMEOUT` | Override the underlying `python-telegram-bot` HTTP timeouts (seconds). | +| `HERMES_TELEGRAM_HTTP_POOL_SIZE` | Max concurrent HTTP connections to the Telegram API. | +| `HERMES_TELEGRAM_DISABLE_FALLBACK_IPS` | Disable the hard-coded Cloudflare fallback IPs used when DNS fails (`true`/`false`). | +| `HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS` | Grace window before flushing a queued Discord text chunk (default: `0.6`). | +| `HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS` | Delay between split chunks when a Discord message exceeds the length limit (default: `2.0`). | +| `HERMES_MATRIX_TEXT_BATCH_DELAY_SECONDS` / `_SPLIT_DELAY_SECONDS` | Matrix equivalents of the Telegram batch knobs. | +| `HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS` / `_SPLIT_DELAY_SECONDS` / `_MAX_CHARS` / `_MAX_MESSAGES` | Feishu batcher tuning — delay, split delay, max chars per message, max messages per batch. | +| `HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS` | Feishu media flush delay. | +| `HERMES_FEISHU_DEDUP_CACHE_SIZE` | Size of the Feishu webhook dedup cache (default: `1024`). | +| `HERMES_WECOM_TEXT_BATCH_DELAY_SECONDS` / `_SPLIT_DELAY_SECONDS` | WeCom batcher tuning. | +| `HERMES_VISION_DOWNLOAD_TIMEOUT` | Timeout in seconds for downloading an image before handing it to vision models (default: `30`). | +| `HERMES_RESTART_DRAIN_TIMEOUT` | Gateway: seconds to wait for active runs to drain on `/restart` before forcing the restart (default: `900`). | +| `HERMES_GATEWAY_PLATFORM_CONNECT_TIMEOUT` | Per-platform connect timeout during gateway startup (seconds). | +| `HERMES_GATEWAY_BUSY_INPUT_MODE` | Default gateway busy-input behavior: `queue`, `steer`, or `interrupt`. Can be overridden per chat with `/busy`. | +| `HERMES_CRON_TIMEOUT` | Inactivity timeout for cron job agent runs in seconds (default: `600`). The agent can run indefinitely while actively calling tools or receiving stream tokens — this only triggers when idle. Set to `0` for unlimited. | +| `HERMES_CRON_SCRIPT_TIMEOUT` | Timeout for pre-run scripts attached to cron jobs in seconds (default: `120`). Override for scripts that need longer execution (e.g., randomized delays for anti-bot timing). Also configurable via `cron.script_timeout_seconds` in `config.yaml`. | +| `HERMES_CRON_MAX_PARALLEL` | Max cron jobs run in parallel per tick (default: `4`). | + ## Agent Behavior | Variable | Description | |----------|-------------| | `HERMES_MAX_ITERATIONS` | Max tool-calling iterations per conversation (default: 90) | +| `HERMES_INFERENCE_MODEL` | Override model name at process level (takes priority over `config.yaml` for the session). Also settable via `-m`/`--model` flag. | +| `HERMES_YOLO_MODE` | Set to `1` to bypass dangerous-command approval prompts. Equivalent to `--yolo`. | +| `HERMES_ACCEPT_HOOKS` | Auto-approve any unseen shell hooks declared in `config.yaml` without a TTY prompt. Equivalent to `--accept-hooks` or `hooks_auto_accept: true`. | +| `HERMES_IGNORE_USER_CONFIG` | Skip `~/.hermes/config.yaml` and use built-in defaults (credentials in `.env` still load). Equivalent to `--ignore-user-config`. | +| `HERMES_IGNORE_RULES` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, memory, and preloaded skills. Equivalent to `--ignore-rules`. | +| `HERMES_MD_NAMES` | Comma-separated list of rules-file names to auto-inject (default: `AGENTS.md,CLAUDE.md,.cursorrules,SOUL.md`). | | `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` | @@ -395,10 +429,30 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `HERMES_API_CALL_STALE_TIMEOUT` | Non-streaming stale-call timeout in seconds (default: `300`). Auto-disabled for local providers when left unset. Also configurable via `providers..stale_timeout_seconds` or `providers..models..stale_timeout_seconds` in `config.yaml`. | | `HERMES_STREAM_READ_TIMEOUT` | Streaming socket read timeout in seconds (default: `120`). Auto-increased to `HERMES_API_TIMEOUT` for local providers. Increase if local LLMs time out during long code generation. | | `HERMES_STREAM_STALE_TIMEOUT` | Stale stream detection timeout in seconds (default: `180`). Auto-disabled for local providers. Triggers connection kill if no chunks arrive within this window. | +| `HERMES_STREAM_RETRIES` | Number of mid-stream reconnect attempts on transient network errors (default: `3`). | +| `HERMES_AGENT_TIMEOUT` | Gateway inactivity timeout for a running agent in seconds (default: `900`). Resets on every tool call and streamed token. Set to `0` to disable. | +| `HERMES_AGENT_TIMEOUT_WARNING` | Gateway: send a warning message after this many seconds of inactivity (default: 75% of `HERMES_AGENT_TIMEOUT`). | +| `HERMES_AGENT_NOTIFY_INTERVAL` | Gateway: interval in seconds between progress notifications on long-running agent turns. | +| `HERMES_CHECKPOINT_TIMEOUT` | Timeout for filesystem checkpoint creation in seconds (default: `30`). | | `HERMES_EXEC_ASK` | Enable execution approval prompts in gateway mode (`true`/`false`) | | `HERMES_ENABLE_PROJECT_PLUGINS` | Enable auto-discovery of repo-local plugins from `./.hermes/plugins/` (`true`/`false`, default: `false`) | | `HERMES_BACKGROUND_NOTIFICATIONS` | Background process notification mode in gateway: `all` (default), `result`, `error`, `off` | | `HERMES_EPHEMERAL_SYSTEM_PROMPT` | Ephemeral system prompt injected at API-call time (never persisted to sessions) | +| `HERMES_PREFILL_MESSAGES_FILE` | Path to a JSON file of ephemeral prefill messages injected at API-call time. | +| `HERMES_ALLOW_PRIVATE_URLS` | `true`/`false` — allow tools to fetch localhost/private-network URLs. Off by default in gateway mode. | +| `HERMES_REDACT_SECRETS` | `true`/`false` — control secret redaction in logs and shareable outputs (default: `true`). | +| `HERMES_WRITE_SAFE_ROOT` | Optional directory prefix that restricts `write_file`/`patch` writes; paths outside require approval. | +| `HERMES_DISABLE_FILE_STATE_GUARD` | Set to `1` to turn off the "file changed since you read it" guard on `patch`/`write_file`. | +| `HERMES_CORE_TOOLS` | Comma-separated override for the canonical core tool list (advanced; rarely needed). | +| `HERMES_BUNDLED_SKILLS` | Comma-separated override for the list of bundled skills loaded at startup. | +| `HERMES_OPTIONAL_SKILLS` | Comma-separated list of optional-skill names to auto-install on first run. | +| `HERMES_DEBUG_INTERRUPT` | Set to `1` to log detailed interrupt/cancel tracing to `agent.log`. | +| `HERMES_DUMP_REQUESTS` | Dump API request payloads to log files (`true`/`false`) | +| `HERMES_DUMP_REQUEST_STDOUT` | Dump API request payloads to stdout instead of log files. | +| `HERMES_OAUTH_TRACE` | Set to `1` to log OAuth token exchange and refresh attempts. Includes redacted timing info. | +| `HERMES_OAUTH_FILE` | Override the path used for OAuth credential storage (default: `~/.hermes/auth.json`). | +| `HERMES_AGENT_HELP_GUIDANCE` | Append additional guidance text to the system prompt for custom deployments. | +| `HERMES_AGENT_LOGO` | Override the ASCII banner logo at CLI startup. | | `DELEGATION_MAX_CONCURRENT_CHILDREN` | Max parallel subagents per `delegate_task` batch (default: `3`, floor of 1, no ceiling). Also configurable via `delegation.max_concurrent_children` in `config.yaml` — the config value takes priority. | ## Interface @@ -411,13 +465,6 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `HERMES_TUI_THEME` | Force the TUI color theme: `light`, `dark`, or a raw 6-character background hex (e.g. `ffffff` or `1a1a2e`). When unset, Hermes auto-detects using `COLORFGBG` and terminal background queries; this variable overrides detection on terminals (Ghostty, Warp, iTerm2, etc.) that don't set `COLORFGBG`. | | `HERMES_INFERENCE_MODEL` | Force the model for `hermes -z` / `hermes chat` without mutating `config.yaml`. Pairs with `HERMES_INFERENCE_PROVIDER`. Useful for scripted callers (sweeper, CI, batch runners) that need to override the default model per run. | -## Cron Scheduler - -| Variable | Description | -|----------|-------------| -| `HERMES_CRON_TIMEOUT` | Inactivity timeout for cron job agent runs in seconds (default: `600`). The agent can run indefinitely while actively calling tools or receiving stream tokens — this only triggers when idle. Set to `0` for unlimited. | -| `HERMES_CRON_SCRIPT_TIMEOUT` | Timeout for pre-run scripts attached to cron jobs in seconds (default: `120`). Override for scripts that need longer execution (e.g., randomized delays for anti-bot timing). Also configurable via `cron.script_timeout_seconds` in `config.yaml`. | - ## Session Settings | Variable | Description | diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md index 8af14003a4..e438ff8a5c 100644 --- a/website/docs/reference/skills-catalog.md +++ b/website/docs/reference/skills-catalog.md @@ -14,114 +14,119 @@ If a skill is missing from this list but present in the repo, the catalog is reg | Skill | Description | Path | |-------|-------------|------| -| [`apple-notes`](/docs/user-guide/skills/bundled/apple/apple-apple-notes) | Manage Apple Notes via the memo CLI on macOS (create, view, search, edit). | `apple/apple-notes` | -| [`apple-reminders`](/docs/user-guide/skills/bundled/apple/apple-apple-reminders) | Manage Apple Reminders via remindctl CLI (list, add, complete, delete). | `apple/apple-reminders` | -| [`findmy`](/docs/user-guide/skills/bundled/apple/apple-findmy) | Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture. | `apple/findmy` | +| [`apple-notes`](/docs/user-guide/skills/bundled/apple/apple-apple-notes) | Manage Apple Notes via memo CLI: create, search, edit. | `apple/apple-notes` | +| [`apple-reminders`](/docs/user-guide/skills/bundled/apple/apple-apple-reminders) | Apple Reminders via remindctl: add, list, complete. | `apple/apple-reminders` | +| [`findmy`](/docs/user-guide/skills/bundled/apple/apple-findmy) | Track Apple devices/AirTags via FindMy.app on macOS. | `apple/findmy` | | [`imessage`](/docs/user-guide/skills/bundled/apple/apple-imessage) | Send and receive iMessages/SMS via the imsg CLI on macOS. | `apple/imessage` | ## autonomous-ai-agents | Skill | Description | Path | |-------|-------------|------| -| [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-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`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-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`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Complete guide to using and extending Hermes Agent — CLI usage, setup, configuration, spawning additional agents, gateway platforms, skills, voice, tools, profiles, and a concise contributor reference. Load this skill when helping users... | `autonomous-ai-agents/hermes-agent` | -| [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-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` | +| [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code) | Delegate coding to Claude Code CLI (features, PRs). | `autonomous-ai-agents/claude-code` | +| [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex) | Delegate coding to OpenAI Codex CLI (features, PRs). | `autonomous-ai-agents/codex` | +| [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | Configure, extend, or contribute to Hermes Agent. | `autonomous-ai-agents/hermes-agent` | +| [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) | Delegate coding to OpenCode CLI (features, PR review). | `autonomous-ai-agents/opencode` | ## creative | Skill | Description | Path | |-------|-------------|------| -| [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | Generate dark-themed SVG diagrams of software systems and cloud infrastructure as standalone HTML files with inline SVG graphics. Semantic component colors (cyan=frontend, emerald=backend, violet=database, amber=cloud/AWS, rose=security,... | `creative/architecture-diagram` | -| [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-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`](/docs/user-guide/skills/bundled/creative/creative-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,... | `creative/ascii-video` | -| [`baoyu-comic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-comic) | Knowledge comic creator supporting multiple art styles and tones. Creates original educational comics with detailed panel layouts and sequential image generation. Use when user asks to create "知识漫画", "教育漫画", "biography comic", "tutorial... | `creative/baoyu-comic` | -| [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Generate professional infographics with 21 layout types and 21 visual styles. Analyzes content, recommends layout×style combinations, and generates publication-ready infographics. Use when user asks to create "infographic", "visual summa... | `creative/baoyu-infographic` | -| [`ideation`](/docs/user-guide/skills/bundled/creative/creative-creative-ideation) | Generate project ideas through creative constraints. Use when the user says 'I want to build something', 'give me a project idea', 'I'm bored', 'what should I make', 'inspire me', or any variant of 'I have tools but no direction'. Works... | `creative/creative-ideation` | -| [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author, validate, diff, and export DESIGN.md files — Google's open-source format spec that gives coding agents a persistent, structured understanding of a design system (tokens + rationale in one file). Use when building a design system,... | `creative/design-md` | -| [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-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 l... | `creative/excalidraw` | -| [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when us... | `creative/manim-video` | -| [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | Production pipeline for interactive and generative visual art using p5.js. Creates browser-based sketches, generative art, data visualizations, interactive experiences, 3D scenes, audio-reactive visuals, and motion graphics — exported as... | `creative/p5js` | -| [`pixel-art`](/docs/user-guide/skills/bundled/creative/creative-pixel-art) | Convert images into retro pixel art with hardware-accurate palettes (NES, Game Boy, PICO-8, C64, etc.), and animate them into short videos. Presets cover arcade, SNES, and 10+ era-correct looks. Use `clarify` to let the user pick a style... | `creative/pixel-art` | -| [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 production-quality design systems extracted from real websites. Load a template to generate HTML/CSS that matches the visual identity of sites like Stripe, Linear, Vercel, Notion, Airbnb, and more. Each template includes colors, typog... | `creative/popular-web-designs` | -| [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft, AI music generation prompts (Suno focus), parody/adaptation techniques, phonetic tricks, and lessons learned. These are tools and ideas, not rules. Break any of them when the art calls for it. | `creative/songwriting-and-ai-music` | +| [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | Dark-themed SVG architecture/cloud/infra diagrams as HTML. | `creative/architecture-diagram` | +| [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art) | ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. | `creative/ascii-art` | +| [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video) | ASCII video: convert video/audio to colored ASCII MP4/GIF. | `creative/ascii-video` | +| [`baoyu-comic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. | `creative/baoyu-comic` | +| [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic) | Infographics: 21 layouts x 21 styles (信息图, 可视化). | `creative/baoyu-infographic` | +| [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design) | Design one-off HTML artifacts (landing, deck, prototype). | `creative/claude-design` | +| [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui) | Generate images, video, and audio with ComfyUI — install, launch, manage nodes/models, run workflows with parameter injection. Uses the official comfy-cli for lifecycle and direct REST API for execution. | `creative/comfyui` | +| [`ideation`](/docs/user-guide/skills/bundled/creative/creative-creative-ideation) | Generate project ideas via creative constraints. | `creative/creative-ideation` | +| [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md) | Author/validate/export Google's DESIGN.md token spec files. | `creative/design-md` | +| [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) | Hand-drawn Excalidraw JSON diagrams (arch, flow, seq). | `creative/excalidraw` | +| [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer) | Humanize text: strip AI-isms and add real voice. | `creative/humanizer` | +| [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video) | Manim CE animations: 3Blue1Brown math/algo videos. | `creative/manim-video` | +| [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js) | p5.js sketches: gen art, shaders, interactive, 3D. | `creative/p5js` | +| [`pixel-art`](/docs/user-guide/skills/bundled/creative/creative-pixel-art) | Pixel art w/ era palettes (NES, Game Boy, PICO-8). | `creative/pixel-art` | +| [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs) | 54 real design systems (Stripe, Linear, Vercel) as HTML/CSS. | `creative/popular-web-designs` | +| [`pretext`](/docs/user-guide/skills/bundled/creative/creative-pretext) | Use when building creative browser demos with @chenglou/pretext — DOM-free text layout for ASCII art, typographic flow around obstacles, text-as-geometry games, kinetic typography, and text-powered generative art. Produces single-file HT... | `creative/pretext` | +| [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch) | Throwaway HTML mockups: 2-3 design variants to compare. | `creative/sketch` | +| [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music) | Songwriting craft and Suno AI music prompts. | `creative/songwriting-and-ai-music` | | [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp) | Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools. | `creative/touchdesigner-mcp` | ## data-science | Skill | Description | Path | |-------|-------------|------| -| [`jupyter-live-kernel`](/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) | Use a live Jupyter kernel for stateful, iterative Python execution via hamelnb. Load this skill when the task involves exploration, iteration, or inspecting intermediate results — data science, ML experimentation, API exploration, or bui... | `data-science/jupyter-live-kernel` | +| [`jupyter-live-kernel`](/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) | Iterative Python via live Jupyter kernel (hamelnb). | `data-science/jupyter-live-kernel` | ## devops | Skill | Description | Path | |-------|-------------|------| -| [`webhook-subscriptions`](/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions) | Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats. | `devops/webhook-subscriptions` | +| [`webhook-subscriptions`](/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions) | Webhook subscriptions: event-driven agent runs. | `devops/webhook-subscriptions` | ## dogfood | Skill | Description | Path | |-------|-------------|------| -| [`dogfood`](/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood) | Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports | `dogfood` | +| [`dogfood`](/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood) | Exploratory QA of web apps: find bugs, evidence, reports. | `dogfood` | ## email | Skill | Description | Path | |-------|-------------|------| -| [`himalaya`](/docs/user-guide/skills/bundled/email/email-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` | +| [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) | Himalaya CLI: IMAP/SMTP email from terminal. | `email/himalaya` | ## gaming | Skill | Description | Path | |-------|-------------|------| -| [`minecraft-modpack-server`](/docs/user-guide/skills/bundled/gaming/gaming-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`](/docs/user-guide/skills/bundled/gaming/gaming-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` | +| [`minecraft-modpack-server`](/docs/user-guide/skills/bundled/gaming/gaming-minecraft-modpack-server) | Host modded Minecraft servers (CurseForge, Modrinth). | `gaming/minecraft-modpack-server` | +| [`pokemon-player`](/docs/user-guide/skills/bundled/gaming/gaming-pokemon-player) | Play Pokemon via headless emulator + RAM reads. | `gaming/pokemon-player` | ## github | Skill | Description | Path | |-------|-------------|------| -| [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-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`](/docs/user-guide/skills/bundled/github/github-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`](/docs/user-guide/skills/bundled/github/github-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`](/docs/user-guide/skills/bundled/github/github-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`](/docs/user-guide/skills/bundled/github/github-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`](/docs/user-guide/skills/bundled/github/github-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` | +| [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) | Inspect codebases w/ pygount: LOC, languages, ratios. | `github/codebase-inspection` | +| [`github-auth`](/docs/user-guide/skills/bundled/github/github-github-auth) | GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login. | `github/github-auth` | +| [`github-code-review`](/docs/user-guide/skills/bundled/github/github-github-code-review) | Review PRs: diffs, inline comments via gh or REST. | `github/github-code-review` | +| [`github-issues`](/docs/user-guide/skills/bundled/github/github-github-issues) | Create, triage, label, assign GitHub issues via gh or REST. | `github/github-issues` | +| [`github-pr-workflow`](/docs/user-guide/skills/bundled/github/github-github-pr-workflow) | GitHub PR lifecycle: branch, commit, open, CI, merge. | `github/github-pr-workflow` | +| [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) | Clone/create/fork repos; manage remotes, releases. | `github/github-repo-management` | ## mcp | Skill | Description | Path | |-------|-------------|------| -| [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-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 filterin... | `mcp/native-mcp` | +| [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp) | MCP client: connect servers, register tools (stdio/HTTP). | `mcp/native-mcp` | ## media | Skill | Description | Path | |-------|-------------|------| -| [`gif-search`](/docs/user-guide/skills/bundled/media/media-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`](/docs/user-guide/skills/bundled/media/media-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`](/docs/user-guide/skills/bundled/media/media-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` | -| [`spotify`](/docs/user-guide/skills/bundled/media/media-spotify) | Control Spotify — play music, search the catalog, manage playlists and library, inspect devices and playback state. Loads when the user asks to play/pause/queue music, search tracks/albums/artists, manage playlists, or check what's playi... | `media/spotify` | -| [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) | Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts). Use when the user shares a YouTube URL or video link, asks to summarize a video, requests a transcript, or wants to ex... | `media/youtube-content` | +| [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search) | Search/download GIFs from Tenor via curl + jq. | `media/gif-search` | +| [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula) | HeartMuLa: Suno-like song generation from lyrics + tags. | `media/heartmula` | +| [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee) | Audio spectrograms/features (mel, chroma, MFCC) via CLI. | `media/songsee` | +| [`spotify`](/docs/user-guide/skills/bundled/media/media-spotify) | Spotify: play, search, queue, manage playlists and devices. | `media/spotify` | +| [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content) | YouTube transcripts to summaries, threads, blogs. | `media/youtube-content` | ## mlops | Skill | Description | Path | |-------|-------------|------| -| [`audiocraft-audio-generation`](/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft) | 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` | -| [`axolotl`](/docs/user-guide/skills/bundled/mlops/mlops-training-axolotl) | Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support | `mlops/training/axolotl` | -| [`dspy`](/docs/user-guide/skills/bundled/mlops/mlops-research-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` | -| [`huggingface-hub`](/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub) | Hugging Face Hub CLI (hf) — search, download, and upload models and datasets, manage repos, query datasets with SQL, deploy inference endpoints, manage Spaces and buckets. | `mlops/huggingface-hub` | +| [`audiocraft-audio-generation`](/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft) | AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. | `mlops/models/audiocraft` | +| [`axolotl`](/docs/user-guide/skills/bundled/mlops/mlops-training-axolotl) | Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO). | `mlops/training/axolotl` | +| [`dspy`](/docs/user-guide/skills/bundled/mlops/mlops-research-dspy) | DSPy: declarative LM programs, auto-optimize prompts, RAG. | `mlops/research/dspy` | +| [`huggingface-hub`](/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub) | HuggingFace hf CLI: search/download/upload models, datasets. | `mlops/huggingface-hub` | | [`llama-cpp`](/docs/user-guide/skills/bundled/mlops/mlops-inference-llama-cpp) | llama.cpp local GGUF inference + HF Hub model discovery. | `mlops/inference/llama-cpp` | -| [`evaluating-llms-harness`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-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 El... | `mlops/evaluation/lm-evaluation-harness` | -| [`obliteratus`](/docs/user-guide/skills/bundled/mlops/mlops-inference-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,... | `mlops/inference/obliteratus` | -| [`outlines`](/docs/user-guide/skills/bundled/mlops/mlops-inference-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` | -| [`segment-anything-model`](/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything) | 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` | -| [`fine-tuning-with-trl`](/docs/user-guide/skills/bundled/mlops/mlops-training-trl-fine-tuning) | 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... | `mlops/training/trl-fine-tuning` | -| [`unsloth`](/docs/user-guide/skills/bundled/mlops/mlops-training-unsloth) | Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization | `mlops/training/unsloth` | -| [`serving-llms-vllm`](/docs/user-guide/skills/bundled/mlops/mlops-inference-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... | `mlops/inference/vllm` | -| [`weights-and-biases`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-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` | +| [`evaluating-llms-harness`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness) | lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). | `mlops/evaluation/lm-evaluation-harness` | +| [`obliteratus`](/docs/user-guide/skills/bundled/mlops/mlops-inference-obliteratus) | OBLITERATUS: abliterate LLM refusals (diff-in-means). | `mlops/inference/obliteratus` | +| [`outlines`](/docs/user-guide/skills/bundled/mlops/mlops-inference-outlines) | Outlines: structured JSON/regex/Pydantic LLM generation. | `mlops/inference/outlines` | +| [`segment-anything-model`](/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything) | SAM: zero-shot image segmentation via points, boxes, masks. | `mlops/models/segment-anything` | +| [`fine-tuning-with-trl`](/docs/user-guide/skills/bundled/mlops/mlops-training-trl-fine-tuning) | TRL: SFT, DPO, PPO, GRPO, reward modeling for LLM RLHF. | `mlops/training/trl-fine-tuning` | +| [`unsloth`](/docs/user-guide/skills/bundled/mlops/mlops-training-unsloth) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. | `mlops/training/unsloth` | +| [`serving-llms-vllm`](/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm) | vLLM: high-throughput LLM serving, OpenAI API, quantization. | `mlops/inference/vllm` | +| [`weights-and-biases`](/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases) | W&B: log ML experiments, sweeps, model registry, dashboards. | `mlops/evaluation/weights-and-biases` | ## note-taking @@ -134,49 +139,60 @@ If a skill is missing from this list but present in the repo, the catalog is reg | Skill | Description | Path | |-------|-------------|------| | [`airtable`](/docs/user-guide/skills/bundled/productivity/productivity-airtable) | Airtable REST API via curl. Records CRUD, filters, upserts. | `productivity/airtable` | -| [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) | Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses Hermes-managed OAuth2 setup, prefers the Google Workspace CLI (`gws`) when available for broader API coverage, and falls back to the Python client libraries... | `productivity/google-workspace` | -| [`linear`](/docs/user-guide/skills/bundled/productivity/productivity-linear) | Manage Linear issues, projects, and teams via the GraphQL API. Create, update, search, and organize issues. Uses API key auth (no OAuth needed). All operations via curl — no dependencies. | `productivity/linear` | -| [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) | Location intelligence — geocode a place, reverse-geocode coordinates, find nearby places (46 POI categories), driving/walking/cycling distance + time, turn-by-turn directions, timezone lookup, bounding box + area for a named place, and P... | `productivity/maps` | -| [`nano-pdf`](/docs/user-guide/skills/bundled/productivity/productivity-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`](/docs/user-guide/skills/bundled/productivity/productivity-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`](/docs/user-guide/skills/bundled/productivity/productivity-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`](/docs/user-guide/skills/bundled/productivity/productivity-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... | `productivity/powerpoint` | +| [`google-workspace`](/docs/user-guide/skills/bundled/productivity/productivity-google-workspace) | Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. | `productivity/google-workspace` | +| [`linear`](/docs/user-guide/skills/bundled/productivity/productivity-linear) | Linear: manage issues, projects, teams via GraphQL + curl. | `productivity/linear` | +| [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) | Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. | `productivity/maps` | +| [`nano-pdf`](/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf) | Edit PDF text/typos/titles via nano-pdf CLI (NL prompts). | `productivity/nano-pdf` | +| [`notion`](/docs/user-guide/skills/bundled/productivity/productivity-notion) | Notion API via curl: pages, databases, blocks, search. | `productivity/notion` | +| [`ocr-and-documents`](/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) | Extract text from PDFs/scans (pymupdf, marker-pdf). | `productivity/ocr-and-documents` | +| [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) | Create, read, edit .pptx decks, slides, notes, templates. | `productivity/powerpoint` | ## red-teaming | Skill | Description | Path | |-------|-------------|------| -| [`godmode`](/docs/user-guide/skills/bundled/red-teaming/red-teaming-godmode) | Jailbreak API-served LLMs using G0DM0D3 techniques — Parseltongue input obfuscation (33 techniques), GODMODE CLASSIC system prompt templates, ULTRAPLINIAN multi-model racing, encoding escalation, and Hermes-native prefill/system prompt i... | `red-teaming/godmode` | +| [`godmode`](/docs/user-guide/skills/bundled/red-teaming/red-teaming-godmode) | Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN. | `red-teaming/godmode` | ## research | Skill | Description | Path | |-------|-------------|------| -| [`arxiv`](/docs/user-guide/skills/bundled/research/research-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`](/docs/user-guide/skills/bundled/research/research-blogwatcher) | Monitor blogs and RSS/Atom feeds for updates using the blogwatcher-cli tool. Add blogs, scan for new articles, track read status, and filter by category. | `research/blogwatcher` | -| [`llm-wiki`](/docs/user-guide/skills/bundled/research/research-llm-wiki) | Karpathy's LLM Wiki — build and maintain a persistent, interlinked markdown knowledge base. Ingest sources, query compiled knowledge, and lint for consistency. | `research/llm-wiki` | -| [`polymarket`](/docs/user-guide/skills/bundled/research/research-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` | -| [`research-paper-writing`](/docs/user-guide/skills/bundled/research/research-research-paper-writing) | End-to-end pipeline for writing ML/AI research papers — from experiment design through analysis, drafting, revision, and submission. Covers NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Integrates automated experiment monitoring, statistical ana... | `research/research-paper-writing` | +| [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) | Search arXiv papers by keyword, author, category, or ID. | `research/arxiv` | +| [`blogwatcher`](/docs/user-guide/skills/bundled/research/research-blogwatcher) | Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool. | `research/blogwatcher` | +| [`llm-wiki`](/docs/user-guide/skills/bundled/research/research-llm-wiki) | Karpathy's LLM Wiki: build/query interlinked markdown KB. | `research/llm-wiki` | +| [`polymarket`](/docs/user-guide/skills/bundled/research/research-polymarket) | Query Polymarket: markets, prices, orderbooks, history. | `research/polymarket` | +| [`research-paper-writing`](/docs/user-guide/skills/bundled/research/research-research-paper-writing) | Write ML papers for NeurIPS/ICML/ICLR: design→submit. | `research/research-paper-writing` | ## smart-home | Skill | Description | Path | |-------|-------------|------| -| [`openhue`](/docs/user-guide/skills/bundled/smart-home/smart-home-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` | +| [`openhue`](/docs/user-guide/skills/bundled/smart-home/smart-home-openhue) | Control Philips Hue lights, scenes, rooms via OpenHue CLI. | `smart-home/openhue` | ## social-media | Skill | Description | Path | |-------|-------------|------| -| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | Interact with X/Twitter via xurl, the official X API CLI. Use for posting, replying, quoting, searching, timelines, mentions, likes, reposts, bookmarks, follows, DMs, media upload, and raw v2 endpoint access. | `social-media/xurl` | +| [`xurl`](/docs/user-guide/skills/bundled/social-media/social-media-xurl) | X/Twitter via xurl CLI: post, search, DM, media, v2 API. | `social-media/xurl` | ## software-development | Skill | Description | Path | |-------|-------------|------| -| [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | Plan mode for Hermes — inspect context, write a markdown plan into the active workspace's `.hermes/plans/` directory, and do not execute the work. | `software-development/plan` | -| [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit verification pipeline — static security scan, baseline-aware quality gates, independent reviewer subagent, and auto-fix loop. Use after code changes and before committing, pushing, or opening a PR. | `software-development/requesting-code-review` | -| [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-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`](/docs/user-guide/skills/bundled/software-development/software-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`](/docs/user-guide/skills/bundled/software-development/software-development-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`](/docs/user-guide/skills/bundled/software-development/software-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` | +| [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) | Debug Hermes TUI slash commands: Python, gateway, Ink UI. | `software-development/debugging-hermes-tui-commands` | +| [`hermes-agent-skill-authoring`](/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring) | Author in-repo SKILL.md: frontmatter, validator, structure. | `software-development/hermes-agent-skill-authoring` | +| [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger) | Debug Node.js via --inspect + Chrome DevTools Protocol CLI. | `software-development/node-inspect-debugger` | +| [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | Plan mode: write markdown plan to .hermes/plans/, no exec. | `software-development/plan` | +| [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) | Debug Python: pdb REPL + debugpy remote (DAP). | `software-development/python-debugpy` | +| [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | Pre-commit review: security scan, quality gates, auto-fix. | `software-development/requesting-code-review` | +| [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike) | Throwaway experiments to validate an idea before build. | `software-development/spike` | +| [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) | Execute plans via delegate_task subagents (2-stage review). | `software-development/subagent-driven-development` | +| [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | 4-phase root cause debugging: understand bugs before fixing. | `software-development/systematic-debugging` | +| [`test-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development) | TDD: enforce RED-GREEN-REFACTOR, tests before code. | `software-development/test-driven-development` | +| [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans) | Write implementation plans: bite-sized tasks, paths, code. | `software-development/writing-plans` | + +## yuanbao + +| Skill | Description | Path | +|-------|-------------|------| +| [`yuanbao`](/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao) | Yuanbao (元宝) groups: @mention users, query info/members. | `yuanbao` | diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md index 0678725d46..6cc37287cb 100644 --- a/website/docs/reference/slash-commands.md +++ b/website/docs/reference/slash-commands.md @@ -32,9 +32,10 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/rollback` | List or restore filesystem checkpoints (usage: /rollback [number]) | | `/snapshot [create\|restore \|prune]` (alias: `/snap`) | Create or restore state snapshots of Hermes config/state. `create [label]` saves a snapshot, `restore ` reverts to it, `prune [N]` removes old snapshots, or list all with no args. | | `/stop` | Kill all running background processes | -| `/queue ` (alias: `/q`) | Queue a prompt for the next turn (doesn't interrupt the current agent response). **Note:** `/q` is claimed by both `/queue` and `/quit`; the last registration wins, so `/q` resolves to `/quit` in practice. Use `/queue` explicitly. | +| `/queue ` (alias: `/q`) | Queue a prompt for the next turn (doesn't interrupt the current agent response). | | `/steer ` | Inject a mid-run note that arrives at the agent **after the next tool call** — no interrupt, no new user turn. The text is appended to the last tool result's content once the current tool completes, giving the agent new context without breaking the current tool-calling loop. Use this to nudge direction mid-task (e.g. "focus on the auth module" while the agent is running tests). | | `/resume [name]` | Resume a previously-named session | +| `/redraw` | Force a full UI repaint (recovers from terminal drift after tmux resize, mouse selection artifacts, etc.) | | `/status` | Show session info | | `/agents` (alias: `/tasks`) | Show active agents and running tasks across the current session. | | `/background ` (alias: `/bg`, `/btw`) | Run a prompt in a separate background session. The agent processes your prompt independently — your current session stays free for other work. Results appear as a panel when the task finishes. See [CLI Background Sessions](/docs/user-guide/cli#background-sessions). | @@ -54,6 +55,9 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/statusbar` (alias: `/sb`) | Toggle the context/model status bar on or off | | `/voice [on\|off\|tts\|status]` | Toggle CLI voice mode and spoken playback. Recording uses `voice.record_key` (default: `Ctrl+B`). | | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. | +| `/footer [on\|off\|status]` | Toggle the gateway runtime-metadata footer on final replies (shows model, tool counts, timing). | +| `/busy [queue\|steer\|interrupt\|status]` | CLI-only: control what pressing Enter does while Hermes is working — queue the new message, steer mid-turn, or interrupt immediately. | +| `/indicator [kaomoji\|emoji\|unicode\|ascii]` | CLI-only: pick the TUI busy-indicator style. | ### Tools & Skills @@ -64,6 +68,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/browser [connect\|disconnect\|status]` | Manage local Chrome CDP connection. `connect` attaches browser tools to a running Chrome instance (default: `ws://localhost:9222`). `disconnect` detaches. `status` shows current connection. Auto-launches Chrome if no debugger is detected. | | `/skills` | Search, install, inspect, or manage skills from online registries | | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) | +| `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See [Curator](/docs/user-guide/features/curator). | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config.yaml | | `/reload` | Reload `.env` variables into the running session (picks up new API keys without restarting) | | `/plugins` | List installed plugins and their status | @@ -79,7 +84,6 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | `/paste` | Attach a clipboard image | | `/copy [number]` | Copy the last assistant response to clipboard (or the Nth-from-last with a number). CLI-only. | | `/image ` | Attach a local image file for your next prompt. | -| `/terminal-setup [auto\|vscode\|cursor\|windsurf]` | TUI-only: configure local VS Code-family terminal bindings for better multiline + undo/redo parity. | | `/debug` | Upload debug report (system info + logs) and get shareable links. Also available in messaging. | | `/profile` | Show active profile name and home directory | | `/gquota` | Show Google Gemini Code Assist quota usage with progress bars (only available when the `google-gemini-cli` provider is active). | @@ -88,7 +92,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in | Command | Description | |---------|-------------| -| `/quit` | Exit the CLI (also: `/exit`). See note on `/q` under `/queue` above. | +| `/quit` | Exit the CLI (also: `/exit`). | ### Dynamic CLI slash commands @@ -147,6 +151,10 @@ The messaging gateway supports the following built-in commands inside Telegram, | `/voice [on\|off\|tts\|join\|channel\|leave\|status]` | Control spoken replies in chat. `join`/`channel`/`leave` manage Discord voice-channel mode. | | `/rollback [number]` | List or restore filesystem checkpoints. | | `/background ` | Run a prompt in a separate background session. Results are delivered back to the same chat when the task finishes. See [Messaging Background Sessions](/docs/user-guide/messaging/#background-sessions). | +| `/queue ` (alias: `/q`) | Queue a prompt for the next turn without interrupting the current one. | +| `/steer ` | Inject a message after the next tool call without interrupting — the model picks it up on its next iteration rather than as a new turn. | +| `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, tool counts, timing). | +| `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. | | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. | | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. | | `/commands [page]` | Browse all commands and skills (paginated). | @@ -160,8 +168,8 @@ The messaging gateway supports the following built-in commands inside Telegram, ## Notes -- `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/skills`, `/platforms`, `/paste`, `/image`, `/terminal-setup`, `/statusbar`, `/mouse`, `/plugins`, and `/steer` are **CLI-only** (the `/mouse` command is TUI-exclusive; `/steer` works in both classic CLI and TUI). +- `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/skills`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/plugins`, `/busy`, `/indicator`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, and `/quit` are **CLI-only** commands. - `/verbose` is **CLI-only by default**, but can be enabled for messaging platforms by setting `display.tool_progress_command: true` in `config.yaml`. When enabled, it cycles the `display.tool_progress` mode and saves to config. - `/sethome`, `/update`, `/restart`, `/approve`, `/deny`, and `/commands` are **messaging-only** commands. -- `/status`, `/background`, `/voice`, `/reload-mcp`, `/rollback`, `/debug`, `/fast`, and `/yolo` work in **both** the CLI and the messaging gateway. +- `/status`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, and `/yolo` work in **both** the CLI and the messaging gateway. - `/voice join`, `/voice channel`, and `/voice leave` are only meaningful on Discord. diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md index 3f1d509d91..be4eca1831 100644 --- a/website/docs/reference/tools-reference.md +++ b/website/docs/reference/tools-reference.md @@ -6,9 +6,9 @@ description: "Authoritative reference for Hermes built-in tools, grouped by tool # Built-in Tools Reference -This page documents all 55 built-in tools in the Hermes tool registry, grouped by toolset. Availability varies by platform, credentials, and enabled toolsets. +This page documents all 68 built-in tools in the Hermes tool registry, grouped by toolset. Availability varies by platform, credentials, and enabled toolsets. -**Quick counts:** 12 browser tools, 4 file tools, 10 RL tools, 4 Home Assistant tools, 2 terminal tools, 2 web tools, 5 Feishu tools, and 15 standalone tools across other toolsets. +**Quick counts:** 10 browser tools (core) + 2 browser-cdp tools, 4 file tools, 10 RL tools, 4 Home Assistant tools, 2 terminal tools, 2 web tools, 5 Feishu tools, 7 Spotify tools, 5 Yuanbao tools, 2 Discord tools, and 15 standalone tools across other toolsets. :::tip MCP Tools In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with a server-name prefix (e.g., `github_create_issue` for the `github` MCP server). See [MCP Integration](/docs/user-guide/features/mcp) for configuration. @@ -19,8 +19,6 @@ In addition to built-in tools, Hermes can load tools dynamically from MCP server | Tool | Description | Requires environment | |------|-------------|----------------------| | `browser_back` | Navigate back to the previous page in browser history. Requires browser_navigate to be called first. | — | -| `browser_cdp` | Send a raw Chrome DevTools Protocol (CDP) command. Escape hatch for browser operations not covered by browser_navigate, browser_click, browser_console, etc. Only available when a CDP endpoint is reachable at session start — via `/browser connect` or `browser.cdp_url` config. See https://chromedevtools.github.io/devtools-protocol/ | — | -| `browser_dialog` | Respond to a native JavaScript dialog (alert / confirm / prompt / beforeunload). Call `browser_snapshot` first — pending dialogs appear in its `pending_dialogs` field. Then call `browser_dialog(action='accept'|'dismiss')`. Same availability as `browser_cdp` (Browserbase or `/browser connect`). | — | | `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_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. | — | @@ -31,6 +29,15 @@ In addition to built-in tools, Hermes can load tools dynamically from MCP server | `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… | — | +## `browser-cdp` toolset + +Registered only when a Chrome DevTools Protocol endpoint is reachable at session start — via `/browser connect`, `browser.cdp_url` config, a Browserbase session, or Camofox. + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `browser_cdp` | Send a raw Chrome DevTools Protocol command. Escape hatch for browser operations not covered by the higher-level `browser_*` tools. See https://chromedevtools.github.io/devtools-protocol/ | CDP endpoint | +| `browser_dialog` | Respond to a native JavaScript dialog (alert / confirm / prompt / beforeunload). Call `browser_snapshot` first — pending dialogs appear in its `pending_dialogs` field. Then call `browser_dialog(action='accept'\|'dismiss')`. | CDP endpoint | + ## `clarify` toolset | Tool | Description | Requires environment | @@ -181,4 +188,46 @@ Scoped to the Feishu document-comment handler. Drives comment read/write operati |------|-------------|----------------------| | `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… | — | +## `discord` toolset + +Registered on the `hermes-discord` platform toolset (gateway only). Uses the same bot token as the messaging adapter. + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `discord` | Read and participate in a Discord server. Actions include `search_members`, `fetch_messages`, `send_message`, `react`, `fetch_channel`, `list_channels`, and more. | `DISCORD_BOT_TOKEN` | + +## `discord_admin` toolset + +Registered on the `hermes-discord` platform toolset. Moderation actions require the bot to hold the matching Discord permissions. + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `discord_admin` | Manage a Discord server via the REST API: list guilds/channels/roles, create/edit/delete channels, manage role grants, timeouts, kicks, and bans. | `DISCORD_BOT_TOKEN` + bot permissions | + +## `spotify` toolset + +Registered by the bundled `spotify` plugin. Requires an OAuth token — run `hermes spotify setup` once to authorize. + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `spotify_playback` | Control Spotify playback, inspect the active playback state, or fetch recently played tracks. | Spotify OAuth | +| `spotify_devices` | List Spotify Connect devices or transfer playback to a different device. | Spotify OAuth | +| `spotify_queue` | Inspect the user's Spotify queue or add an item to it. | Spotify OAuth | +| `spotify_search` | Search the Spotify catalog for tracks, albums, artists, playlists, shows, or episodes. | Spotify OAuth | +| `spotify_playlists` | List, inspect, create, update, and modify Spotify playlists. | Spotify OAuth | +| `spotify_albums` | Fetch Spotify album metadata or album tracks. | Spotify OAuth | +| `spotify_library` | List, save, or remove the user's saved Spotify tracks or albums. | Spotify OAuth | + +## `hermes-yuanbao` toolset + +Registered only on the `hermes-yuanbao` platform toolset. Yuanbao is Tencent's chat app; these tools drive its DM/group/sticker APIs. + +| Tool | Description | Requires environment | +|------|-------------|----------------------| +| `yb_query_group_info` | Query basic info about a group (called "派/Pai" in the app): name, owner, member count. | Yuanbao credentials | +| `yb_query_group_members` | Query members of a group (for `@`-mentions, finding a user by name, listing bots). | Yuanbao credentials | +| `yb_send_dm` | Send a private/direct message to a user in a group, with optional media files. | Yuanbao credentials | +| `yb_search_sticker` | Search the built-in Yuanbao sticker (TIM face) catalogue by keyword. | Yuanbao credentials | +| `yb_send_sticker` | Send a built-in sticker to the current Yuanbao chat. | Yuanbao credentials | + diff --git a/website/docs/reference/toolsets-reference.md b/website/docs/reference/toolsets-reference.md index a8c0a8225c..25a343edf4 100644 --- a/website/docs/reference/toolsets-reference.md +++ b/website/docs/reference/toolsets-reference.md @@ -52,37 +52,34 @@ Or in-session: | Toolset | Tools | Purpose | |---------|-------|---------| -| `browser` | `browser_back`, `browser_cdp`, `browser_click`, `browser_console`, `browser_dialog`, `browser_get_images`, `browser_navigate`, `browser_press`, `browser_scroll`, `browser_snapshot`, `browser_type`, `browser_vision`, `web_search` | Full browser automation. Includes `web_search` as a fallback for quick lookups. `browser_cdp` and `browser_dialog` are gated on a reachable CDP endpoint — they only appear when `/browser connect` is active, `browser.cdp_url` is set, or a Browserbase session is active. `browser_dialog` works together with the `pending_dialogs` and `frame_tree` fields that `browser_snapshot` adds when a CDP supervisor is attached. | +| `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. | +| `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. | - -## Composite Toolsets - -These expand to multiple core toolsets, providing a convenient shorthand for common scenarios: - -| Toolset | Expands to | Use case | -|---------|-----------|----------| -| `debugging` | `web` + `file` + `process`, `terminal` (via `includes`) — effectively `patch`, `process`, `read_file`, `search_files`, `terminal`, `web_extract`, `web_search`, `write_file` | Debug sessions — file access, terminal, and web research without browser or delegation overhead. | -| `safe` | `image_generate`, `vision_analyze`, `web_extract`, `web_search` | Read-only research and media generation. No file writes, no terminal access, no code execution. Good for untrusted or constrained environments. | +| `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 @@ -90,11 +87,12 @@ Platform toolsets define the complete tool configuration for a deployment target | Toolset | Differences from `hermes-cli` | |---------|-------------------------------| -| `hermes-cli` | Full toolset — all 36 core tools including `clarify`. The default for interactive CLI sessions. | -| `hermes-acp` | Drops `clarify`, `cronjob`, `image_generate`, `send_message`, `text_to_speech`, homeassistant tools. Focused on coding tasks in IDE context. | -| `hermes-api-server` | Drops `clarify`, `send_message`, and `text_to_speech`. Adds everything else — suitable for programmatic access where user interaction isn't possible. | +| `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` | 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`. | @@ -104,14 +102,15 @@ Platform toolsets define the complete tool configuration for a deployment target | `hermes-sms` | Same as `hermes-cli`. | | `hermes-bluebubbles` | Same as `hermes-cli`. | | `hermes-dingtalk` | Same as `hermes-cli`. | -| `hermes-feishu` | Same as `hermes-cli`. Note: the `feishu_doc` / `feishu_drive` toolsets are used only by the document-comment handler, not by the regular Feishu chat adapter. | +| `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-homeassistant` | Same as `hermes-cli` plus the `homeassistant` toolset always on. | +| `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 the broadest possible tool set when the gateway needs to accept any message source. | +| `hermes-gateway` | Internal gateway orchestrator toolset — union of every `hermes-` toolset; used when the gateway needs to accept any message source. | ## Dynamic Toolsets diff --git a/website/docs/user-guide/checkpoints-and-rollback.md b/website/docs/user-guide/checkpoints-and-rollback.md index 77847d2ef6..ed50c011ec 100644 --- a/website/docs/user-guide/checkpoints-and-rollback.md +++ b/website/docs/user-guide/checkpoints-and-rollback.md @@ -16,7 +16,7 @@ This safety net is powered by an internal **Checkpoint Manager** that keeps a se Checkpoints are taken automatically before: - **File tools** — `write_file` and `patch` -- **Destructive terminal commands** — `rm`, `mv`, `sed -i`, `truncate`, `shred`, output redirects (`>`), and `git reset`/`clean`/`checkout` +- **Destructive terminal commands** — `rm`, `rmdir`, `cp`, `install`, `mv`, `sed -i`, `truncate`, `dd`, `shred`, output redirects (`>`), and `git reset`/`clean`/`checkout` The agent creates **at most one checkpoint per directory per turn**, so long-running sessions don't spam snapshots. diff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.md index 527a49225f..be92044fc5 100644 --- a/website/docs/user-guide/cli.md +++ b/website/docs/user-guide/cli.md @@ -358,7 +358,7 @@ auxiliary: model: "google/gemini-3-flash-preview" # Model used for summarization ``` -When compression triggers, middle turns are summarized while the first 3 and last 4 turns are always preserved. +When compression triggers, middle turns are summarized while the first 3 and last 20 turns are always preserved. ## Background Sessions diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 99c3fc6a50..18c96b8b18 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -1152,7 +1152,8 @@ This controls both the `text_to_speech` tool and spoken replies in voice mode (` display: tool_progress: all # off | new | all | verbose tool_progress_command: false # Enable /verbose slash command in messaging gateway - tool_progress_overrides: {} # Per-platform overrides (see below) + platforms: {} # Per-platform display overrides (see below) + tool_progress_overrides: {} # DEPRECATED — use display.platforms instead interim_assistant_messages: true # Gateway: send natural mid-turn assistant updates as separate messages skin: default # Built-in or custom CLI skin (see user-guide/features/skins) personality: "kawaii" # Legacy cosmetic field still surfaced in some summaries @@ -1194,18 +1195,21 @@ Only the **final** message of a turn gets the footer; interim updates stay clean ### Per-platform progress overrides -Different platforms have different verbosity needs. For example, Signal can't edit messages, so each progress update becomes a separate message — noisy. Use `tool_progress_overrides` to set per-platform modes: +Different platforms have different verbosity needs. For example, Signal can't edit messages, so each progress update becomes a separate message — noisy. Use `display.platforms` to set per-platform modes: ```yaml display: tool_progress: all # global default - tool_progress_overrides: - signal: 'off' # silence progress on Signal - telegram: verbose # detailed progress on Telegram - slack: 'off' # quiet in shared Slack workspace + platforms: + signal: + tool_progress: 'off' # silence progress on Signal + telegram: + tool_progress: verbose # detailed progress on Telegram + slack: + tool_progress: 'off' # quiet in shared Slack workspace ``` -Platforms without an override fall back to the global `tool_progress` value. Valid platform keys: `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `matrix`, `mattermost`, `email`, `sms`, `homeassistant`, `dingtalk`, `feishu`, `wecom`, `weixin`, `bluebubbles`, `qqbot`. +Platforms without an override fall back to the global `tool_progress` value. Valid platform keys: `telegram`, `discord`, `slack`, `signal`, `whatsapp`, `matrix`, `mattermost`, `email`, `sms`, `homeassistant`, `dingtalk`, `feishu`, `wecom`, `weixin`, `bluebubbles`, `qqbot`. The legacy `display.tool_progress_overrides` key still loads for backward compatibility but is deprecated and migrated into `display.platforms` on first load. `interim_assistant_messages` is gateway-only. When enabled, Hermes sends completed mid-turn assistant updates as separate chat messages. This is independent from `tool_progress` and does not require gateway streaming. diff --git a/website/docs/user-guide/docker.md b/website/docs/user-guide/docker.md index 17bd714aac..21f8246ace 100644 --- a/website/docs/user-guide/docker.md +++ b/website/docs/user-guide/docker.md @@ -39,7 +39,7 @@ docker run -d \ nousresearch/hermes-agent gateway run ``` -Port 8642 exposes the gateway's [OpenAI-compatible API server](./api-server.md) and health endpoint. It's optional if you only use chat platforms (Telegram, Discord, etc.), but required if you want the dashboard or external tools to reach the gateway. +Port 8642 exposes the gateway's [OpenAI-compatible API server](./features/api-server.md) and health endpoint. It's optional if you only use chat platforms (Telegram, Discord, etc.), but required if you want the dashboard or external tools to reach the gateway. Opening any port on an internet facing machine is a security risk. You should not do it unless you understand the risks. @@ -208,7 +208,7 @@ services: image: nousresearch/hermes-agent:latest container_name: hermes-dashboard restart: unless-stopped - command: dashboard --host 0.0.0.0 + command: dashboard --host 0.0.0.0 --insecure ports: - "9119:9119" volumes: @@ -259,10 +259,10 @@ docker run -d \ The official image is based on `debian:13.4` and includes: -- Python 3 with all Hermes dependencies (`pip install -e ".[all]"`) +- Python 3 with all Hermes dependencies (`uv pip install -e ".[all]"`) - Node.js + npm (for browser automation and WhatsApp bridge) -- Playwright with Chromium (`npx playwright install --with-deps chromium`) -- ripgrep and ffmpeg as system utilities +- Playwright with Chromium (`npx playwright install --with-deps chromium --only-shell`) +- ripgrep, ffmpeg, git, and tini as system utilities - **`docker-cli`** — so agents running inside the container can drive the host's Docker daemon (bind-mount `/var/run/docker.sock` to opt in) for `docker build`, `docker run`, container inspection, etc. - **`openssh-client`** — enables the [SSH terminal backend](/docs/user-guide/configuration#ssh-backend) from inside the container. The SSH backend shells out to the system `ssh` binary; without this, it failed silently in containerized installs. - The WhatsApp bridge (`scripts/whatsapp-bridge/`) @@ -312,7 +312,7 @@ Check logs: `docker logs hermes`. Common causes: ### "Permission denied" errors -The container runs as root by default. If your host `~/.hermes/` was created by a non-root user, permissions should work. If you get errors, ensure the data directory is writable: +The container's entrypoint drops privileges to the non-root `hermes` user (UID 10000) via `gosu`. If your host `~/.hermes/` is owned by a different UID, set `HERMES_UID`/`HERMES_GID` to match your host user, or ensure the data directory is writable: ```sh chmod -R 755 ~/.hermes diff --git a/website/docs/user-guide/features/built-in-plugins.md b/website/docs/user-guide/features/built-in-plugins.md index eb4d27e728..c6ff883948 100644 --- a/website/docs/user-guide/features/built-in-plugins.md +++ b/website/docs/user-guide/features/built-in-plugins.md @@ -51,6 +51,22 @@ hermes plugins disable disk-cleanup ## Currently shipped +The repo ships these bundled plugins under `plugins/`. All are opt-in — enable them via `hermes plugins enable `. + +| Plugin | Kind | Purpose | +|---|---|---| +| `disk-cleanup` | hooks + slash command | Auto-track ephemeral files and clean them on session end | +| `observability/langfuse` | hooks | Trace turns / LLM calls / tools to [Langfuse](https://langfuse.com) | +| `spotify` | backend (7 tools) | Native Spotify playback, queue, search, playlists, albums, library | +| `google_meet` | standalone | Join Meet calls, live-caption transcription, optional realtime duplex audio | +| `image_gen/openai` | image backend | OpenAI `gpt-image-2` image generation backend (alternative to FAL) | +| `image_gen/openai-codex` | image backend | OpenAI image generation via Codex OAuth | +| `image_gen/xai` | image backend | xAI `grok-2-image` backend | +| `example-dashboard` | dashboard example | Reference dashboard plugin for [Extending the Dashboard](./extending-the-dashboard.md) | +| `strike-freedom-cockpit` | dashboard skin | Sample custom dashboard skin | + +Memory providers (`plugins/memory/*`) and context engines (`plugins/context_engine/*`) are listed separately on [Memory Providers](./memory-providers.md) — they're managed through `hermes memory` and `hermes plugins` respectively. The full per-plugin detail for the two long-running hooks-based plugins follows. + ### disk-cleanup Auto-tracks and removes ephemeral files created during sessions — test scripts, temp outputs, cron logs, stale chrome profiles — without requiring the agent to remember to call a tool. diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md index 368c4a47cf..e74d800460 100644 --- a/website/docs/user-guide/features/cron.md +++ b/website/docs/user-guide/features/cron.md @@ -91,10 +91,10 @@ This is useful when you want a scheduled agent to inherit reusable workflows wit Cron jobs default to running detached from any repo — no `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` is loaded, and the terminal / file / code-exec tools run from whatever working directory the gateway started in. Pass `--workdir` (CLI) or `workdir=` (tool call) to change that: ```bash -# Standalone CLI -hermes cron create --schedule "every 1d at 09:00" \ - --workdir /home/me/projects/acme \ - --prompt "Audit open PRs, summarize CI health, and post to #eng" +# Standalone CLI (schedule and prompt are positional) +hermes cron create "every 1d at 09:00" \ + "Audit open PRs, summarize CI health, and post to #eng" \ + --workdir /home/me/projects/acme ``` ```python diff --git a/website/docs/user-guide/features/fallback-providers.md b/website/docs/user-guide/features/fallback-providers.md index 5ead44af14..f60faf9247 100644 --- a/website/docs/user-guide/features/fallback-providers.md +++ b/website/docs/user-guide/features/fallback-providers.md @@ -74,6 +74,12 @@ Both `provider` and `model` are **required**. If either is missing, the fallback | Arcee AI | `arcee` | `ARCEEAI_API_KEY` | | GMI Cloud | `gmi` | `GMI_API_KEY` | | Alibaba / DashScope | `alibaba` | `DASHSCOPE_API_KEY` | +| Alibaba Coding Plan | `alibaba-coding-plan` | `ALIBABA_CODING_PLAN_API_KEY` (falls back to `DASHSCOPE_API_KEY`) | +| Kimi / Moonshot (China) | `kimi-coding-cn` | `KIMI_CN_API_KEY` | +| StepFun | `stepfun` | `STEPFUN_API_KEY` | +| Tencent TokenHub | `tencent-tokenhub` | `TOKENHUB_API_KEY` | +| Azure AI Foundry | `azure-foundry` | `AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL` | +| LM Studio (local) | `lmstudio` | `LM_API_KEY` (or none for local) + `LM_BASE_URL` | | Hugging Face | `huggingface` | `HF_TOKEN` | | Custom endpoint | `custom` | `base_url` + `key_env` (see below) | diff --git a/website/docs/user-guide/features/overview.md b/website/docs/user-guide/features/overview.md index ff45a54a4a..36bebe8b02 100644 --- a/website/docs/user-guide/features/overview.md +++ b/website/docs/user-guide/features/overview.md @@ -30,8 +30,8 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch - **[Voice Mode](voice-mode.md)** — Full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels. - **[Browser Automation](browser.md)** — Full browser automation with multiple backends: Browserbase cloud, Browser Use cloud, local Chrome via CDP, or local Chromium. Navigate websites, fill forms, and extract information. - **[Vision & Image Paste](vision.md)** — Multimodal vision support. Paste images from your clipboard into the CLI and ask the agent to analyze, describe, or work with them using any vision-capable model. -- **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai. Eight models supported (FLUX 2 Klein/Pro, GPT-Image 1.5, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo); pick one via `hermes tools`. -- **[Voice & TTS](tts.md)** — Text-to-speech output and voice message transcription across all messaging platforms, with five provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, MiniMax, and NeuTTS. +- **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai. Nine models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo); pick one via `hermes tools`. +- **[Voice & TTS](tts.md)** — Text-to-speech output and voice message transcription across all messaging platforms, with nine provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, MiniMax, Mistral Voxtral, Google Gemini, xAI, NeuTTS, and KittenTTS. ## Integrations @@ -39,7 +39,7 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch - **[Provider Routing](provider-routing.md)** — Fine-grained control over which AI providers handle your requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and priority ordering. - **[Fallback Providers](fallback-providers.md)** — Automatic failover to backup LLM providers when your primary model encounters errors, including independent fallback for auxiliary tasks like vision and compression. - **[Credential Pools](credential-pools.md)** — Distribute API calls across multiple keys for the same provider. Automatic rotation on rate limits or failures. -- **[Memory Providers](memory-providers.md)** — Plug in external memory backends (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover) for cross-session user modeling and personalization beyond the built-in memory system. +- **[Memory Providers](memory-providers.md)** — Plug in external memory backends (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory) for cross-session user modeling and personalization beyond the built-in memory system. - **[API Server](api-server.md)** — Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, and more. - **[IDE Integration (ACP)](acp.md)** — Use Hermes inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Chat, tool activity, file diffs, and terminal commands render inside your editor. - **[RL Training](rl-training.md)** — Generate trajectory data from agent sessions for reinforcement learning and model fine-tuning. diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md index 7010ca637f..0e99fd12d2 100644 --- a/website/docs/user-guide/features/plugins.md +++ b/website/docs/user-guide/features/plugins.md @@ -142,6 +142,9 @@ Plugins can register callbacks for these lifecycle events. See the **[Event Hook | [`post_llm_call`](/docs/user-guide/features/hooks#post_llm_call) | Once per turn, after the LLM loop (successful turns only) | | [`on_session_start`](/docs/user-guide/features/hooks#on_session_start) | New session created (first turn only) | | [`on_session_end`](/docs/user-guide/features/hooks#on_session_end) | End of every `run_conversation` call + CLI exit handler | +| [`on_session_finalize`](/docs/user-guide/features/hooks#on_session_finalize) | CLI/gateway tears down an active session (`/new`, GC, CLI quit) | +| [`on_session_reset`](/docs/user-guide/features/hooks#on_session_reset) | Gateway swaps in a new session key (`/new`, `/reset`, `/clear`, idle rotation) | +| [`subagent_stop`](/docs/user-guide/features/hooks#subagent_stop) | Once per child after `delegate_task` finishes | | [`pre_gateway_dispatch`](/docs/user-guide/features/hooks#pre_gateway_dispatch) | Gateway received a user message, before auth + dispatch. Return `{"action": "skip" \| "rewrite" \| "allow", ...}` to influence flow. | ## Plugin types diff --git a/website/docs/user-guide/features/tool-gateway.md b/website/docs/user-guide/features/tool-gateway.md index 9b1b4f4f3a..5d702e6f9f 100644 --- a/website/docs/user-guide/features/tool-gateway.md +++ b/website/docs/user-guide/features/tool-gateway.md @@ -18,7 +18,7 @@ The **Tool Gateway** lets paid [Nous Portal](https://portal.nousresearch.com) su | Tool | What It Does | Direct Alternative | |------|--------------|--------------------| | **Web search & extract** | Search the web and extract page content via Firecrawl | `FIRECRAWL_API_KEY`, `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY` | -| **Image generation** | Generate images via FAL (8 models: FLUX 2 Klein/Pro, GPT-Image, Nano Banana Pro, Ideogram, Recraft V4 Pro, Qwen, Z-Image) | `FAL_KEY` | +| **Image generation** | Generate images via FAL (9 models: FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo) | `FAL_KEY` | | **Text-to-speech** | Convert text to speech via OpenAI TTS | `VOICE_TOOLS_OPENAI_KEY`, `ELEVENLABS_API_KEY` | | **Browser automation** | Control cloud browsers via Browser Use | `BROWSER_USE_API_KEY`, `BROWSERBASE_API_KEY` | diff --git a/website/docs/user-guide/features/tools.md b/website/docs/user-guide/features/tools.md index cc1d1f9bc1..80e1800812 100644 --- a/website/docs/user-guide/features/tools.md +++ b/website/docs/user-guide/features/tools.md @@ -48,7 +48,7 @@ hermes tools hermes tools ``` -Common toolsets include `web`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `homeassistant`, and `rl`. +Common toolsets include `web`, `search`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `moa`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `homeassistant`, `messaging`, `spotify`, `discord`, `discord_admin`, `debugging`, `safe`, 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-`. diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md index 5f6cf064fc..079dbc80bd 100644 --- a/website/docs/user-guide/features/web-dashboard.md +++ b/website/docs/user-guide/features/web-dashboard.md @@ -23,6 +23,8 @@ This starts a local web server and opens `http://127.0.0.1:9119` in your browser | `--port` | `9119` | Port to run the web server on | | `--host` | `127.0.0.1` | Bind address | | `--no-open` | — | Don't auto-open the browser | +| `--insecure` | off | Allow binding to non-localhost hosts (**DANGEROUS** — exposes API keys on the network; pair with a firewall and strong auth) | +| `--tui` | off | Expose the in-browser Chat tab (embedded `hermes --tui` via PTY/WebSocket). Alternatively set `HERMES_DASHBOARD_TUI=1`. | ```bash # Custom port diff --git a/website/docs/user-guide/messaging/bluebubbles.md b/website/docs/user-guide/messaging/bluebubbles.md index f2b240fc7f..40af59a57b 100644 --- a/website/docs/user-guide/messaging/bluebubbles.md +++ b/website/docs/user-guide/messaging/bluebubbles.md @@ -90,7 +90,8 @@ Hermes → BlueBubbles REST API → Messages.app → iMessage | `BLUEBUBBLES_HOME_CHANNEL` | No | — | Phone/email for cron delivery | | `BLUEBUBBLES_ALLOWED_USERS` | No | — | Comma-separated authorized users | | `BLUEBUBBLES_ALLOW_ALL_USERS` | No | `false` | Allow all users | -| `BLUEBUBBLES_SEND_READ_RECEIPTS` | No | `true` | Auto-mark messages as read | + +Auto-marking messages as read is controlled by the `send_read_receipts` key under `platforms.bluebubbles.extra` in `~/.hermes/config.yaml` (default: `true`). There is no corresponding environment variable. ## Features diff --git a/website/docs/user-guide/messaging/dingtalk.md b/website/docs/user-guide/messaging/dingtalk.md index 4dd51b8b70..21dd45b539 100644 --- a/website/docs/user-guide/messaging/dingtalk.md +++ b/website/docs/user-guide/messaging/dingtalk.md @@ -123,6 +123,13 @@ DINGTALK_ALLOWED_USERS=user-id-1 # Multiple allowed users (comma-separated) # DINGTALK_ALLOWED_USERS=user-id-1,user-id-2 + +# Optional: group-chat gating (mirrors Slack/Telegram/Discord/WhatsApp) +# DINGTALK_REQUIRE_MENTION=true +# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF== +# DINGTALK_MENTION_PATTERNS=^小马 +# DINGTALK_HOME_CHANNEL=cidXXXX== +# DINGTALK_ALLOW_ALL_USERS=true ``` Optional behavior settings in `~/.hermes/config.yaml`: diff --git a/website/docs/user-guide/messaging/discord.md b/website/docs/user-guide/messaging/discord.md index 898d8e7c6f..c8a2dbc5f6 100644 --- a/website/docs/user-guide/messaging/discord.md +++ b/website/docs/user-guide/messaging/discord.md @@ -292,7 +292,7 @@ Discord behavior is controlled through two files: **`~/.hermes/.env`** for crede | `DISCORD_ALLOW_MENTION_REPLIED_USER` | No | `true` | When `true` (default), replying to a message pings the original author. | | `DISCORD_PROXY` | No | — | Proxy URL for Discord connections (HTTP, WebSocket, REST). Overrides `HTTPS_PROXY`/`ALL_PROXY`. Supports `http://`, `https://`, and `socks5://` schemes. | | `HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS` | No | `0.6` | Grace window the adapter waits before flushing a queued text chunk. Useful for smoothing streamed output. | -| `HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS` | No | `0.1` | Delay between split chunks when a single message exceeds Discord's length limit. | +| `HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS` | No | `2.0` | Delay between split chunks when a single message exceeds Discord's length limit. | ### Config File (`config.yaml`) diff --git a/website/docs/user-guide/messaging/qqbot.md b/website/docs/user-guide/messaging/qqbot.md index 8da6f92def..46cef53b0f 100644 --- a/website/docs/user-guide/messaging/qqbot.md +++ b/website/docs/user-guide/messaging/qqbot.md @@ -51,8 +51,9 @@ QQ_CLIENT_SECRET=your-app-secret | `QQBOT_HOME_CHANNEL` | OpenID for cron/notification delivery | — | | `QQBOT_HOME_CHANNEL_NAME` | Display name for home channel | `Home` | | `QQ_ALLOWED_USERS` | Comma-separated user OpenIDs for DM access | open (all users) | +| `QQ_GROUP_ALLOWED_USERS` | Comma-separated group OpenIDs for group access | — | | `QQ_ALLOW_ALL_USERS` | Set to `true` to allow all DMs | `false` | -| `QQ_SANDBOX` | Route requests to the QQ sandbox gateway for development testing | `false` | +| `QQ_PORTAL_HOST` | Override the QQ portal host (set to `sandbox.q.qq.com` for sandbox routing) | `q.qq.com` | | `QQ_STT_API_KEY` | API key for voice-to-text provider | — | | `QQ_STT_BASE_URL` | Base URL for STT provider | `https://open.bigmodel.cn/api/coding/paas/v4` | | `QQ_STT_MODEL` | STT model name | `glm-asr` | diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md index ad1ec492bf..695e9815cd 100644 --- a/website/docs/user-guide/messaging/telegram.md +++ b/website/docs/user-guide/messaging/telegram.md @@ -179,15 +179,15 @@ Add the following to `~/.hermes/.env`: ```bash TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram +TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)" # required # TELEGRAM_WEBHOOK_PORT=8443 # optional, default 8443 -# TELEGRAM_WEBHOOK_SECRET=mysecret # optional, recommended ``` | Variable | Required | Description | |----------|----------|-------------| | `TELEGRAM_WEBHOOK_URL` | Yes | Public HTTPS URL where Telegram will send updates. The URL path is auto-extracted (e.g., `/telegram` from the example above). | +| `TELEGRAM_WEBHOOK_SECRET` | **Yes** (when `TELEGRAM_WEBHOOK_URL` is set) | Secret token that Telegram echoes in every webhook request for verification. The gateway refuses to start without it — see [GHSA-3vpc-7q5r-276h](https://github.com/NousResearch/hermes-agent/security/advisories/GHSA-3vpc-7q5r-276h). Generate with `openssl rand -hex 32`. | | `TELEGRAM_WEBHOOK_PORT` | No | Local port the webhook server listens on (default: `8443`). | -| `TELEGRAM_WEBHOOK_SECRET` | No | Secret token for verifying that updates actually come from Telegram. **Strongly recommended** for production deployments. | When `TELEGRAM_WEBHOOK_URL` is set, the gateway starts an HTTP webhook server instead of polling. When unset, polling mode is used — no behavior change from previous versions. diff --git a/website/docs/user-guide/messaging/wecom-callback.md b/website/docs/user-guide/messaging/wecom-callback.md index dd8331fb7f..a9c6be56b7 100644 --- a/website/docs/user-guide/messaging/wecom-callback.md +++ b/website/docs/user-guide/messaging/wecom-callback.md @@ -60,9 +60,11 @@ WECOM_CALLBACK_ALLOWED_USERS=user1,user2 ### 3. Start the Gateway ```bash -hermes gateway start +hermes gateway ``` +(Use `hermes gateway start` only after `hermes gateway install` has registered the systemd/launchd service.) + The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST. ## Configuration Reference diff --git a/website/docs/user-guide/messaging/yuanbao.md b/website/docs/user-guide/messaging/yuanbao.md index 63a5a50e90..1f1f1c18f4 100644 --- a/website/docs/user-guide/messaging/yuanbao.md +++ b/website/docs/user-guide/messaging/yuanbao.md @@ -337,5 +337,5 @@ hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code" - [Messaging Gateway Overview](./index.md) - [Slash Commands Reference](/docs/reference/slash-commands.md) -- [Cron Jobs](/docs/user-guide/features/cron-jobs.md) -- [Background Tasks](/docs/guides/tips.md#background-tasks) \ No newline at end of file +- [Cron Jobs](/docs/user-guide/features/cron.md) +- [Background Sessions](/docs/user-guide/cli#background-sessions) \ No newline at end of file diff --git a/website/docs/user-guide/profiles.md b/website/docs/user-guide/profiles.md index aef4d10b21..0dcc35db0a 100644 --- a/website/docs/user-guide/profiles.md +++ b/website/docs/user-guide/profiles.md @@ -70,7 +70,7 @@ coder setup # configure coder's settings coder gateway start # start coder's gateway coder doctor # check coder's health coder skills list # list coder's skills -coder config set model.model anthropic/claude-sonnet-4 +coder config set model.default anthropic/claude-sonnet-4 ``` The alias works with every hermes subcommand — it's just `hermes -p ` under the hood. @@ -173,7 +173,7 @@ Each profile has its own: - **`SOUL.md`** — personality and instructions ```bash -coder config set model.model anthropic/claude-sonnet-4 +coder config set model.default anthropic/claude-sonnet-4 echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md ``` diff --git a/website/docs/user-guide/security.md b/website/docs/user-guide/security.md index dfb35dd520..fa1d55e478 100644 --- a/website/docs/user-guide/security.md +++ b/website/docs/user-guide/security.md @@ -119,7 +119,7 @@ The following patterns trigger approval prompts (defined in `tools/approval.py`) | `DELETE FROM` (without WHERE) | SQL DELETE without WHERE | | `TRUNCATE TABLE` | SQL TRUNCATE | | `> /etc/` | Overwrite system config | -| `systemctl stop/disable/mask` | Stop/disable system services | +| `systemctl stop/restart/disable/mask` | Stop/restart/disable system services | | `kill -9 -1` | Kill all processes | | `pkill -9` | Force kill processes | | Fork bomb patterns | Fork bombs | diff --git a/website/docs/user-guide/sessions.md b/website/docs/user-guide/sessions.md index 7048e5870a..ec101f6b45 100644 --- a/website/docs/user-guide/sessions.md +++ b/website/docs/user-guide/sessions.md @@ -124,7 +124,7 @@ display: ``` :::tip -Session IDs follow the format `YYYYMMDD_HHMMSS_<8-char-hex>`, e.g. `20250305_091523_a1b2c3d4`. You can resume by ID or by title — both work with `-c` and `-r`. +Session IDs follow the format `YYYYMMDD_HHMMSS_` — CLI/TUI sessions use a 6-char hex suffix (e.g. `20250305_091523_a1b2c3`), gateway sessions use an 8-char suffix (e.g. `20250305_091523_a1b2c3d4`). You can resume by ID (full or unique prefix) or by title — both work with `-c` and `-r`. ::: ## Session Naming diff --git a/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md b/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md index b3a4905f07..637d56a326 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-apple-notes.md @@ -1,14 +1,14 @@ --- -title: "Apple Notes — Manage Apple Notes via the memo CLI on macOS (create, view, search, edit)" +title: "Apple Notes — Manage Apple Notes via memo CLI: create, search, edit" sidebar_label: "Apple Notes" -description: "Manage Apple Notes via the memo CLI on macOS (create, view, search, edit)" +description: "Manage Apple Notes via memo CLI: create, search, edit" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Apple Notes -Manage Apple Notes via the memo CLI on macOS (create, view, search, edit). +Manage Apple Notes via memo CLI: create, search, edit. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md b/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md index c7e01a8446..49549d369e 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-apple-reminders.md @@ -1,14 +1,14 @@ --- -title: "Apple Reminders — Manage Apple Reminders via remindctl CLI (list, add, complete, delete)" +title: "Apple Reminders — Apple Reminders via remindctl: add, list, complete" sidebar_label: "Apple Reminders" -description: "Manage Apple Reminders via remindctl CLI (list, add, complete, delete)" +description: "Apple Reminders via remindctl: add, list, complete" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Apple Reminders -Manage Apple Reminders via remindctl CLI (list, add, complete, delete). +Apple Reminders via remindctl: add, list, complete. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/apple/apple-findmy.md b/website/docs/user-guide/skills/bundled/apple/apple-findmy.md index bf193c81b3..7d75a86c0f 100644 --- a/website/docs/user-guide/skills/bundled/apple/apple-findmy.md +++ b/website/docs/user-guide/skills/bundled/apple/apple-findmy.md @@ -1,14 +1,14 @@ --- -title: "Findmy — Track Apple devices and AirTags via FindMy" +title: "Findmy — Track Apple devices/AirTags via FindMy" sidebar_label: "Findmy" -description: "Track Apple devices and AirTags via FindMy" +description: "Track Apple devices/AirTags via FindMy" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Findmy -Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture. +Track Apple devices/AirTags via FindMy.app on macOS. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md index 515f12ba89..cc02991278 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code.md @@ -1,14 +1,14 @@ --- -title: "Claude Code — Delegate coding tasks to Claude Code (Anthropic's CLI agent)" +title: "Claude Code — Delegate coding to Claude Code CLI (features, PRs)" sidebar_label: "Claude Code" -description: "Delegate coding tasks to Claude Code (Anthropic's CLI agent)" +description: "Delegate coding to Claude Code CLI (features, PRs)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Delegate coding to Claude Code CLI (features, PRs). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md index 70aa3334f3..6f21a4ae6a 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex.md @@ -1,14 +1,14 @@ --- -title: "Codex — Delegate coding tasks to OpenAI Codex CLI agent" +title: "Codex — Delegate coding to OpenAI Codex CLI (features, PRs)" sidebar_label: "Codex" -description: "Delegate coding tasks to OpenAI Codex CLI agent" +description: "Delegate coding to OpenAI Codex CLI (features, PRs)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Delegate coding to OpenAI Codex CLI (features, PRs). ## Skill metadata @@ -32,6 +32,15 @@ The following is the complete skill definition that Hermes loads when this skill Delegate coding tasks to [Codex](https://github.com/openai/codex) via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI. +## When to use + +- Building features +- Refactoring +- PR reviews +- Batch issue fixing + +Requires the codex CLI and a git repository. + ## Prerequisites - Codex installed: `npm install -g @openai/codex` diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md index 10a91f2aae..1159c64398 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md @@ -1,14 +1,14 @@ --- -title: "Hermes Agent" +title: "Hermes Agent — Configure, extend, or contribute to Hermes Agent" sidebar_label: "Hermes Agent" -description: "Complete guide to using and extending Hermes Agent — CLI usage, setup, configuration, spawning additional agents, gateway platforms, skills, voice, tools, pr..." +description: "Configure, extend, or contribute to Hermes Agent" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Hermes Agent -Complete guide to using and extending Hermes Agent — CLI usage, setup, configuration, spawning additional agents, gateway platforms, skills, voice, tools, profiles, and a concise contributor reference. Load this skill when helping users configure Hermes, troubleshoot issues, spawn agent instances, or make code contributions. +Configure, extend, or contribute to Hermes Agent. ## Skill metadata @@ -132,7 +132,7 @@ hermes tools disable NAME Disable a toolset hermes skills list List installed skills hermes skills search QUERY Search the skills hub -hermes skills install ID Install a skill +hermes skills install ID Install a skill (ID can be a hub identifier OR a direct https://…/SKILL.md URL; pass --name to override when frontmatter has no name) hermes skills inspect ID Preview without installing hermes skills config Enable/disable skills per platform hermes skills check Check for updates @@ -419,6 +419,63 @@ Tool changes take effect on `/reset` (new session). They do NOT apply mid-conver --- +## Security & Privacy Toggles + +Common "why is Hermes doing X to my output / tool calls / commands?" toggles — and the exact commands to change them. Most of these need a fresh session (`/reset` in chat, or start a new `hermes` invocation) because they're read once at startup. + +### Secret redaction in tool output + +Secret redaction is **off by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) passes through unmodified. If the user wants Hermes to auto-mask strings that look like API keys, tokens, and secrets before they enter the conversation context and logs: + +```bash +hermes config set security.redact_secrets true # enable globally +``` + +**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=true` from a tool call) will NOT take effect for the running process. Tell the user to run `hermes config set security.redact_secrets true` in a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task. + +Disable again with: +```bash +hermes config set security.redact_secrets false +``` + +### PII redaction in gateway messages + +Separate from secret redaction. When enabled, the gateway hashes user IDs and strips phone numbers from the session context before it reaches the model: + +```bash +hermes config set privacy.redact_pii true # enable +hermes config set privacy.redact_pii false # disable (default) +``` + +### Command approval prompts + +By default (`approvals.mode: manual`), Hermes prompts the user before running shell commands flagged as destructive (`rm -rf`, `git reset --hard`, etc.). The modes are: + +- `manual` — always prompt (default) +- `smart` — use an auxiliary LLM to auto-approve low-risk commands, prompt on high-risk +- `off` — skip all approval prompts (equivalent to `--yolo`) + +```bash +hermes config set approvals.mode smart # recommended middle ground +hermes config set approvals.mode off # bypass everything (not recommended) +``` + +Per-invocation bypass without changing config: +- `hermes --yolo …` +- `export HERMES_YOLO_MODE=1` + +Note: YOLO / `approvals.mode: off` does NOT turn off secret redaction. They are independent. + +### Shell hooks allowlist + +Some shell-hook integrations require explicit allowlisting before they fire. Managed via `~/.hermes/shell-hooks-allowlist.json` — prompted interactively the first time a hook wants to run. + +### Disabling the web/browser/image-gen tools + +To keep the model away from network or media tools entirely, open `hermes tools` and toggle per-platform. Takes effect on next session (`/reset`). See the Tools & Skills section above. + +--- + ## Voice & Transcription ### STT (Voice → Text) @@ -617,6 +674,7 @@ For occasional contributors and PR authors. Full developer docs: https://hermes- ### Project Layout + ``` hermes-agent/ ├── run_agent.py # AIAgent — core conversation loop @@ -637,6 +695,7 @@ hermes-agent/ ├── tests/ # ~3000 pytest tests └── website/ # Docusaurus docs site ``` + Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys). diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md index 2fe44e1293..3ce7e34e62 100644 --- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md +++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md @@ -1,14 +1,14 @@ --- -title: "Opencode" +title: "Opencode — Delegate coding to OpenCode CLI (features, PR review)" sidebar_label: "Opencode" -description: "Delegate coding tasks to OpenCode CLI agent for feature implementation, refactoring, PR review, and long-running autonomous sessions" +description: "Delegate coding to OpenCode CLI (features, PR review)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Delegate coding to OpenCode CLI (features, PR review). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md b/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md index a5a8c5084d..92df03b3fb 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-architecture-diagram.md @@ -1,14 +1,14 @@ --- -title: "Architecture Diagram" +title: "Architecture Diagram — Dark-themed SVG architecture/cloud/infra diagrams as HTML" sidebar_label: "Architecture Diagram" -description: "Generate dark-themed SVG diagrams of software systems and cloud infrastructure as standalone HTML files with inline SVG graphics" +description: "Dark-themed SVG architecture/cloud/infra diagrams as HTML" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Architecture Diagram -Generate dark-themed SVG diagrams of software systems and cloud infrastructure as standalone HTML files with inline SVG graphics. Semantic component colors (cyan=frontend, emerald=backend, violet=database, amber=cloud/AWS, rose=security, orange=message bus), JetBrains Mono font, grid background. Best suited for software architecture, cloud/VPC topology, microservice maps, service-mesh diagrams, database + API layer diagrams, security groups, message buses — anything that fits a tech-infra deck with a dark aesthetic. If a more specialized diagramming skill exists for the subject (scientific, educational, hand-drawn, animated, etc.), prefer that — otherwise this skill can also serve as a general-purpose SVG diagram fallback. Based on Cocoon AI's architecture-diagram-generator (MIT). +Dark-themed SVG architecture/cloud/infra diagrams as HTML. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md b/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md index 852fb28a4c..aea3569bf0 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-ascii-art.md @@ -1,14 +1,14 @@ --- -title: "Ascii Art" +title: "Ascii Art — ASCII art: pyfiglet, cowsay, boxes, image-to-ascii" sidebar_label: "Ascii Art" -description: "Generate ASCII art using pyfiglet (571 fonts), cowsay, boxes, toilet, image-to-ascii, remote APIs (asciified, ascii" +description: "ASCII art: pyfiglet, cowsay, boxes, image-to-ascii" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +ASCII art: pyfiglet, cowsay, boxes, image-to-ascii. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md b/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md index 18b1ca1fd0..5fa904415b 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-ascii-video.md @@ -1,14 +1,14 @@ --- -title: "Ascii Video — Production pipeline for ASCII art video — any format" +title: "Ascii Video — ASCII video: convert video/audio to colored ASCII MP4/GIF" sidebar_label: "Ascii Video" -description: "Production pipeline for ASCII art video — any format" +description: "ASCII video: convert video/audio to colored ASCII MP4/GIF" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 video+audio reactive, text/lyrics overlays, real-time terminal rendering. Use when users request: ASCII video, text art video, terminal-style video, character art animation, retro text visualization, audio visualizer in ASCII, converting video to ASCII art, matrix-style effects, or any animated ASCII output. +ASCII video: convert video/audio to colored ASCII MP4/GIF. ## Skill metadata @@ -25,6 +25,14 @@ The following is the complete skill definition that Hermes loads when this skill # ASCII Video Production Pipeline +## When to use + +Use when users request: ASCII video, text art video, terminal-style video, character art animation, retro text visualization, audio visualizer in ASCII, converting video to ASCII art, matrix-style effects, or any animated ASCII output. + +## What's inside + +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 video+audio reactive, text/lyrics overlays, real-time terminal rendering. + ## Creative Standard This is visual art. ASCII characters are the medium; cinema is the standard. diff --git a/website/docs/user-guide/skills/bundled/creative/creative-baoyu-comic.md b/website/docs/user-guide/skills/bundled/creative/creative-baoyu-comic.md index c1b37bc806..df8a0b2743 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-baoyu-comic.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-baoyu-comic.md @@ -1,14 +1,14 @@ --- -title: "Baoyu Comic — Knowledge comic creator supporting multiple art styles and tones" +title: "Baoyu Comic — Knowledge comics (知识漫画): educational, biography, tutorial" sidebar_label: "Baoyu Comic" -description: "Knowledge comic creator supporting multiple art styles and tones" +description: "Knowledge comics (知识漫画): educational, biography, tutorial" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Baoyu Comic -Knowledge comic creator supporting multiple art styles and tones. Creates original educational comics with detailed panel layouts and sequential image generation. Use when user asks to create "知识漫画", "教育漫画", "biography comic", "tutorial comic", or "Logicomix-style comic". +Knowledge comics (知识漫画): educational, biography, tutorial. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md b/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md index dcb489eb5d..d321592614 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic.md @@ -1,14 +1,14 @@ --- -title: "Baoyu Infographic — Generate professional infographics with 21 layout types and 21 visual styles" +title: "Baoyu Infographic — Infographics: 21 layouts x 21 styles (信息图, 可视化)" sidebar_label: "Baoyu Infographic" -description: "Generate professional infographics with 21 layout types and 21 visual styles" +description: "Infographics: 21 layouts x 21 styles (信息图, 可视化)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Baoyu Infographic -Generate professional infographics with 21 layout types and 21 visual styles. Analyzes content, recommends layout×style combinations, and generates publication-ready infographics. Use when user asks to create "infographic", "visual summary", "信息图", "可视化", or "高密度信息大图". +Infographics: 21 layouts x 21 styles (信息图, 可视化). ## Skill metadata @@ -139,6 +139,7 @@ If a shortcut has **Prompt Notes**, append them to the generated prompt (Step 5) ## Output Structure + ``` infographic/{topic-slug}/ ├── source-{slug}.{ext} @@ -147,6 +148,7 @@ infographic/{topic-slug}/ ├── prompts/infographic.md └── infographic.png ``` + Slug: 2-4 words kebab-case from topic. Conflict: append `-YYYYMMDD-HHMMSS`. diff --git a/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md new file mode 100644 index 0000000000..2f39a0d38a --- /dev/null +++ b/website/docs/user-guide/skills/bundled/creative/creative-claude-design.md @@ -0,0 +1,608 @@ +--- +title: "Claude Design — Design one-off HTML artifacts (landing, deck, prototype)" +sidebar_label: "Claude Design" +description: "Design one-off HTML artifacts (landing, deck, prototype)" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Claude Design + +Design one-off HTML artifacts (landing, deck, prototype). + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/creative/claude-design` | +| Version | `1.0.0` | +| Author | BadTechBandit | +| License | MIT | +| Tags | `design`, `html`, `prototype`, `ux`, `ui`, `creative`, `artifact`, `deck`, `motion`, `design-system` | +| Related skills | [`design-md`](/docs/user-guide/skills/bundled/creative/creative-design-md), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Claude Design for CLI/API Agents + +Use this skill when the user asks for design work that would normally fit Claude Design, but the agent is running in a CLI/API environment instead of the hosted Claude Design web UI. + +The goal is to preserve Claude Design's useful design behavior and taste while removing hosted-tool plumbing that does not exist in normal agent environments. + +**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below. + +## When To Use This Skill vs `popular-web-designs` vs `design-md` + +Hermes has three design-related skills under `skills/creative/`. They do different jobs — load the right one (or combine them): + +| Skill | What it gives you | Use when the user wants... | +|---|---|---| +| **claude-design** (this one) | Design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch designed artifact (landing page, prototype, deck, component lab, motion study) with no specific brand or token system dictated | +| **popular-web-designs** | 54 ready-to-paste design systems — exact colors, typography, components, CSS values for sites like Stripe, Linear, Vercel, Notion, Airbnb | "make it look like Stripe / Linear / Vercel", a page styled after a known brand, or a visual starting point pulled from a real product | +| **design-md** | Google's DESIGN.md spec format — author/validate/diff/export design-token files, WCAG contrast checking, Tailwind/DTCG export | a formal, persistent, machine-readable design-system *spec file* (tokens + rationale) that lives in a repo and gets consumed by agents over time | + +Rule of thumb: + +- **Process + taste, one-off artifact** → claude-design +- **Match a known brand's look** → popular-web-designs (and let claude-design drive the process) +- **Author the tokens spec itself** → design-md + +These compose: use `popular-web-designs` for the visual vocabulary, `claude-design` for how to turn a brief into a thoughtful local HTML file, and `design-md` when the output is the token file rather than a rendered artifact. + +## Runtime Mode + +You are running in **CLI/API mode**, not the Claude Design hosted web UI. + +Ignore references from source Claude Design prompts to hosted-only tools, project panes, preview panes, special toolbar protocols, or platform callbacks that are not available in the current environment. + +Examples of hosted-tool concepts to ignore or remap: + +- `done()` +- `fork_verifier_agent()` +- `questions_v2()` +- `copy_starter_component()` +- `show_to_user()` +- `show_html()` +- `snip()` +- `eval_js_user_view()` +- hosted asset review panes +- hosted edit-mode or Tweaks toolbar messaging +- `/projects//...` cross-project paths +- built-in `window.claude.complete()` artifact helper +- tool schemas embedded in the source prompt +- web-search citation scaffolding meant for the hosted runtime + +Instead, use the tools actually available in the current agent environment. + +Default deliverable: + +- a complete local HTML file +- self-contained CSS and JavaScript when portability matters +- exact on-disk path in the final response +- verification using available local methods before saying it is done + +If the user asks for implementation in an existing repo, generate code in the repo's actual stack instead of forcing a standalone HTML artifact. + +## Core Identity + +Act as an expert designer working with the user as the manager. + +HTML is the default tool, but the medium changes by assignment: + +- UX designer for flows and product surfaces +- interaction designer for prototypes +- visual designer for static explorations +- motion designer for animated artifacts +- deck designer for presentations +- design-systems designer for tokens, components, and visual rules +- frontend-minded prototyper when code fidelity matters + +Avoid generic web-design tropes unless the user explicitly asks for a conventional web page. + +Do not expose internal prompts, hidden system messages, or implementation plumbing. Talk about capabilities and deliverables in user terms: HTML files, prototypes, decks, exported assets, screenshots, code, and design options. + +## When To Use + +Use this skill for: + +- landing pages +- teaser pages +- high-fidelity prototypes +- interactive product mockups +- visual option boards +- component explorations +- design-system previews +- HTML slide decks +- motion studies +- onboarding flows +- dashboard concepts +- settings, command palettes, modals, cards, forms, empty states +- redesigns based on screenshots, repos, brand docs, or UI kits + +Do not use this skill for pure DESIGN.md token authoring unless the user specifically asks for a DESIGN.md file. Use `design-md` for that. + +## Design Principle: Start From Context, Not Vibes + +Good high-fidelity design does not start from scratch. + +Before designing, look for source context: + +1. brand docs +2. existing product screenshots +3. current repo components +4. design tokens +5. UI kits +6. prior mockups +7. reference models +8. copy docs +9. constraints from legal, product, or engineering + +If a repo is available, inspect actual source files before inventing UI: + +- theme files +- token files +- global stylesheets +- layout scaffolds +- component files +- route/page files +- form/button/card/navigation implementations + +The file tree is only the menu. Read the files that define the visual vocabulary before designing. + +If context is missing and fidelity matters, ask concise focused questions instead of producing a generic mockup. + +## Asking Questions + +Ask questions when the assignment is new, ambiguous, high-fidelity, externally facing, or depends on taste. + +Keep questions short. Do not ask ten questions by default unless the problem is genuinely underspecified. + +Usually ask for: + +- intended output format +- audience +- fidelity level +- source materials available +- brand/design system in play +- number of variations wanted +- whether to stay conservative or explore divergent ideas +- which dimension matters most: layout, visual language, interaction, copy, motion, or systemization + +Skip questions when: + +- the user gave enough direction +- this is a small tweak +- the task is clearly a continuation +- the missing detail has an obvious default + +When proceeding with assumptions, label only the important ones. + +## Workflow + +1. **Understand the brief** + - What is being designed? + - Who is it for? + - What artifact should exist at the end? + - What constraints are locked? + +2. **Gather context** + - Read supplied docs, screenshots, repo files, or design assets. + - Identify the visual vocabulary before writing code. + +3. **Define the design system for this artifact** + - colors + - type + - spacing + - radii + - shadows or elevation + - motion posture + - component treatment + - interaction rules + +4. **Choose the right format** + - Static visual comparison: one HTML canvas with options side by side. + - Interaction/flow: clickable prototype. + - Presentation: fixed-size HTML deck with slide navigation. + - Component exploration: component lab with variants. + - Motion: timeline or state-based animation. + +5. **Build the artifact** + - Prefer a single self-contained HTML file unless the task calls for a repo implementation. + - Preserve prior versions for major revisions. + - Avoid unnecessary dependencies. + +6. **Verify** + - Confirm files exist. + - Run any available syntax/static checks. + - If browser tools are available, open the file and check console errors. + - If visual fidelity matters and screenshot tools are available, inspect at least the primary viewport. + +7. **Report briefly** + - exact file path + - what was created + - caveats + - next decision or next iteration + +## Artifact Format Rules + +Default to local files. + +For standalone artifacts: + +- create a descriptive filename, e.g. `Landing Page.html`, `Command Palette Prototype.html`, `Design System Board.html` +- embed CSS in ` +``` + +### 4. Variant README + +Each variant's `README.md` answers: + +```markdown +## Variant: {stance name} + +### Design stance +One sentence on the principle driving this variant. + +### Key choices +- Layout: ... +- Typography: ... +- Color: ... +- Interaction: ... + +### Trade-offs +- Strong at: ... +- Weak at: ... + +### Best for +- The kind of user or use case this variant actually serves +``` + +### 5. Head-to-head + +After all variants are built, present them as a comparison. Don't just list — **opinionate**: + +```markdown +## Three takes on the home screen + +| Dimension | Calm editorial | Utilitarian dense | Playful split | +|-----------|----------------|-------------------|---------------| +| Density | Low | High | Medium | +| Primary action visibility | Low | High | Medium | +| Scan-ability | High | Medium | Low | +| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic | + +**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither. +``` + +Let the user pick a winner, or combine two into a hybrid, or ask for another round. + +## Theming (when the project has a visual identity) + +If the user has an existing theme (colors, fonts, tokens), put shared tokens in `sketches/themes/tokens.css` and `@import` them in each variant. Keep tokens minimal: + +```css +/* sketches/themes/tokens.css */ +:root { + --color-bg: #fafafa; + --color-fg: #1a1a1a; + --color-accent: #0066ff; + --color-muted: #666; + --radius: 8px; + --font-display: "Inter", sans-serif; + --font-body: -apple-system, BlinkMacSystemFont, sans-serif; +} +``` + +Don't over-tokenize a throwaway sketch — three colors and one font is usually enough. + +## Interactivity bar + +A sketch is interactive enough when the user can: + +1. **Click a primary action** and something visible happens (state change, modal, toast, navigation feint) +2. **See one meaningful state transition** (filter a list, toggle a mode, open/close a panel) +3. **Hover recognizable affordances** (buttons, rows, tabs) + +More than that is over-engineering a throwaway. Less than that is a screenshot. + +## Frontier mode (picking what to sketch next) + +If sketches already exist and the user says "what should I sketch next?": + +- **Consistency gaps** — two winning variants from different sketches made independent choices that haven't been composed together yet +- **Unsketched screens** — referenced but never explored +- **State coverage** — happy path sketched, but not empty / loading / error / 1000-items +- **Responsive gaps** — validated at one viewport; does it hold at mobile / ultrawide? +- **Interaction patterns** — static layouts exist; transitions, drag, scroll behavior don't + +Propose 2-4 named candidates. Let the user pick. + +## Output + +- Create `sketches/` (or `.planning/sketches/` if the user is using GSD conventions) in the repo root +- One subdir per variant: `NNN-stance-name/index.html` + `README.md` +- Tell the user how to open them: `open sketches/001-calm-editorial/index.html` on macOS, `xdg-open` on Linux, `start` on Windows +- Keep variants disposable — a sketch that you felt the need to preserve should be promoted into real project code, not curated as an asset + +**Typical tool sequence for one variant:** + +``` +terminal("mkdir -p sketches/001-calm-editorial") +write_file("sketches/001-calm-editorial/index.html", "...") +write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...") +browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html") +browser_vision(question="How does this look? Any obvious layout issues?") +``` + +Repeat for each variant, then present the comparison table. + +## Attribution + +Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The full GSD system ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows; install with `npx get-shit-done-cc --hermes --global`. diff --git a/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md b/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md index cd0b7fb148..159207d05a 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md @@ -1,14 +1,14 @@ --- -title: "Songwriting And Ai Music" +title: "Songwriting And Ai Music — Songwriting craft and Suno AI music prompts" sidebar_label: "Songwriting And Ai Music" -description: "Songwriting craft, AI music generation prompts (Suno focus), parody/adaptation techniques, phonetic tricks, and lessons learned" +description: "Songwriting craft and Suno AI music prompts" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Songwriting And Ai Music -Songwriting craft, AI music generation prompts (Suno focus), parody/adaptation techniques, phonetic tricks, and lessons learned. These are tools and ideas, not rules. Break any of them when the art calls for it. +Songwriting craft and Suno AI music prompts. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md b/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md index d0315a7cae..c0388e0ad5 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md @@ -221,8 +221,9 @@ win.par.winopen.pulse() | `td_input_clear` | Stop input automation | | `td_op_screen_rect` | Get screen coords of a node | | `td_click_screen_point` | Click a point in a screenshot | +| `td_screen_point_to_global` | Convert screenshot pixel to absolute screen coords | -See `references/mcp-tools.md` for full parameter schemas. +The table above covers the 32 tools used in typical creative workflows. The remaining 4 tools (`td_project_quit`, `td_test_session`, `td_dev_log`, `td_clear_dev_log`) are admin/dev-mode utilities — see `references/mcp-tools.md` for the full 36-tool reference with complete parameter schemas. ## Key Implementation Rules @@ -355,6 +356,15 @@ See `references/network-patterns.md` for complete build scripts + shader code. | `references/operator-tips.md` | Wireframe rendering, feedback TOP setup | | `references/geometry-comp.md` | Geometry COMP: instancing, POP vs SOP, morphing | | `references/audio-reactive.md` | Audio band extraction, beat detection, envelope following | +| `references/animation.md` | LFOs, timers, keyframes, easing, expression-driven motion | +| `references/midi-osc.md` | MIDI/OSC controllers, TouchOSC, multi-machine sync | +| `references/particles.md` | POPs and legacy particleSOP — emission, forces, collisions | +| `references/projection-mapping.md` | Multi-window output, corner pin, mesh warp, edge blending | +| `references/external-data.md` | HTTP, WebSocket, MQTT, Serial, TCP, webserverDAT | +| `references/panel-ui.md` | Custom params, panel COMPs, button/slider/field, panelExecuteDAT | +| `references/replicator.md` | replicatorCOMP — data-driven cloning, layouts, callbacks | +| `references/dat-scripting.md` | Execute DAT family — chop/dat/parameter/panel/op/executeDAT | +| `references/3d-scene.md` | Lighting rigs, shadows, IBL/cubemaps, multi-camera, PBR | | `scripts/setup.sh` | Automated setup script | --- diff --git a/website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md b/website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md index 027156ccdd..185efd30e3 100644 --- a/website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md +++ b/website/docs/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel.md @@ -1,14 +1,14 @@ --- -title: "Jupyter Live Kernel — Use a live Jupyter kernel for stateful, iterative Python execution via hamelnb" +title: "Jupyter Live Kernel — Iterative Python via live Jupyter kernel (hamelnb)" sidebar_label: "Jupyter Live Kernel" -description: "Use a live Jupyter kernel for stateful, iterative Python execution via hamelnb" +description: "Iterative Python via live Jupyter kernel (hamelnb)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Jupyter Live Kernel -Use a live Jupyter kernel for stateful, iterative Python execution via hamelnb. Load this skill when the task involves exploration, iteration, or inspecting intermediate results — data science, ML experimentation, API exploration, or building up complex code step-by-step. Uses terminal to run CLI commands against a live Jupyter kernel. No new tools required. +Iterative Python via live Jupyter kernel (hamelnb). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions.md b/website/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions.md index 8b5b8ade8f..a0b08decf3 100644 --- a/website/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions.md +++ b/website/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions.md @@ -1,14 +1,14 @@ --- -title: "Webhook Subscriptions" +title: "Webhook Subscriptions — Webhook subscriptions: event-driven agent runs" sidebar_label: "Webhook Subscriptions" -description: "Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost)" +description: "Webhook subscriptions: event-driven agent runs" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Webhook Subscriptions -Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats. +Webhook subscriptions: event-driven agent runs. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md b/website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md index 0ff7e72d9d..6a3edee6bb 100644 --- a/website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md +++ b/website/docs/user-guide/skills/bundled/dogfood/dogfood-dogfood.md @@ -1,14 +1,14 @@ --- -title: "Dogfood" +title: "Dogfood — Exploratory QA of web apps: find bugs, evidence, reports" sidebar_label: "Dogfood" -description: "Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports" +description: "Exploratory QA of web apps: find bugs, evidence, reports" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Dogfood -Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports +Exploratory QA of web apps: find bugs, evidence, reports. ## Skill metadata @@ -50,11 +50,13 @@ Follow this 5-phase systematic workflow: ### Phase 1: Plan 1. Create the output directory structure: + ``` {output_dir}/ ├── screenshots/ # Evidence screenshots └── report.md # Final report (generated in Phase 5) ``` + 2. Identify the testing scope based on user input. 3. Build a rough sitemap by planning which pages and features to test: - Landing/home page diff --git a/website/docs/user-guide/skills/bundled/email/email-himalaya.md b/website/docs/user-guide/skills/bundled/email/email-himalaya.md index 55178bdc98..736bfeff7c 100644 --- a/website/docs/user-guide/skills/bundled/email/email-himalaya.md +++ b/website/docs/user-guide/skills/bundled/email/email-himalaya.md @@ -1,14 +1,14 @@ --- -title: "Himalaya — CLI to manage emails via IMAP/SMTP" +title: "Himalaya — Himalaya CLI: IMAP/SMTP email from terminal" sidebar_label: "Himalaya" -description: "CLI to manage emails via IMAP/SMTP" +description: "Himalaya CLI: IMAP/SMTP email from terminal" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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). +Himalaya CLI: IMAP/SMTP email from terminal. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/gaming/gaming-minecraft-modpack-server.md b/website/docs/user-guide/skills/bundled/gaming/gaming-minecraft-modpack-server.md index d85495a181..566605fa33 100644 --- a/website/docs/user-guide/skills/bundled/gaming/gaming-minecraft-modpack-server.md +++ b/website/docs/user-guide/skills/bundled/gaming/gaming-minecraft-modpack-server.md @@ -1,14 +1,14 @@ --- -title: "Minecraft Modpack Server — Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip" +title: "Minecraft Modpack Server — Host modded Minecraft servers (CurseForge, Modrinth)" sidebar_label: "Minecraft Modpack Server" -description: "Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip" +description: "Host modded Minecraft servers (CurseForge, Modrinth)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Host modded Minecraft servers (CurseForge, Modrinth). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/gaming/gaming-pokemon-player.md b/website/docs/user-guide/skills/bundled/gaming/gaming-pokemon-player.md index ab070f8671..1c0030b5d7 100644 --- a/website/docs/user-guide/skills/bundled/gaming/gaming-pokemon-player.md +++ b/website/docs/user-guide/skills/bundled/gaming/gaming-pokemon-player.md @@ -1,14 +1,14 @@ --- -title: "Pokemon Player — Play Pokemon games autonomously via headless emulation" +title: "Pokemon Player — Play Pokemon via headless emulator + RAM reads" sidebar_label: "Pokemon Player" -description: "Play Pokemon games autonomously via headless emulation" +description: "Play Pokemon via headless emulator + RAM reads" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Play Pokemon via headless emulator + RAM reads. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md b/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md index 13c3fe4425..289404f16e 100644 --- a/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md +++ b/website/docs/user-guide/skills/bundled/github/github-codebase-inspection.md @@ -1,14 +1,14 @@ --- -title: "Codebase Inspection" +title: "Codebase Inspection — Inspect codebases w/ pygount: LOC, languages, ratios" sidebar_label: "Codebase Inspection" -description: "Inspect and analyze codebases using pygount for LOC counting, language breakdown, and code-vs-comment ratios" +description: "Inspect codebases w/ pygount: LOC, languages, ratios" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Inspect codebases w/ pygount: LOC, languages, ratios. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/github/github-github-auth.md b/website/docs/user-guide/skills/bundled/github/github-github-auth.md index 4f7360c43e..6453ea9e2a 100644 --- a/website/docs/user-guide/skills/bundled/github/github-github-auth.md +++ b/website/docs/user-guide/skills/bundled/github/github-github-auth.md @@ -1,14 +1,14 @@ --- -title: "Github Auth — Set up GitHub authentication for the agent using git (universally available) or the gh CLI" +title: "Github Auth — GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login" sidebar_label: "Github Auth" -description: "Set up GitHub authentication for the agent using git (universally available) or the gh CLI" +description: "GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 auth setup: HTTPS tokens, SSH keys, gh CLI login. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/github/github-github-code-review.md b/website/docs/user-guide/skills/bundled/github/github-github-code-review.md index 9a18c45e16..d3c14ddb40 100644 --- a/website/docs/user-guide/skills/bundled/github/github-github-code-review.md +++ b/website/docs/user-guide/skills/bundled/github/github-github-code-review.md @@ -1,14 +1,14 @@ --- -title: "Github Code Review" +title: "Github Code Review — Review PRs: diffs, inline comments via gh or REST" sidebar_label: "Github Code Review" -description: "Review code changes by analyzing git diffs, leaving inline comments on PRs, and performing thorough pre-push review" +description: "Review PRs: diffs, inline comments via gh or REST" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Review PRs: diffs, inline comments via gh or REST. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/github/github-github-issues.md b/website/docs/user-guide/skills/bundled/github/github-github-issues.md index 8493663cd5..630488dcbf 100644 --- a/website/docs/user-guide/skills/bundled/github/github-github-issues.md +++ b/website/docs/user-guide/skills/bundled/github/github-github-issues.md @@ -1,14 +1,14 @@ --- -title: "Github Issues — Create, manage, triage, and close GitHub issues" +title: "Github Issues — Create, triage, label, assign GitHub issues via gh or REST" sidebar_label: "Github Issues" -description: "Create, manage, triage, and close GitHub issues" +description: "Create, triage, label, assign GitHub issues via gh or REST" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Create, triage, label, assign GitHub issues via gh or REST. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md b/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md index f1a31e1572..fa13f3073b 100644 --- a/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md +++ b/website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md @@ -1,14 +1,14 @@ --- -title: "Github Pr Workflow" +title: "Github Pr Workflow — GitHub PR lifecycle: branch, commit, open, CI, merge" sidebar_label: "Github Pr Workflow" -description: "Full pull request lifecycle — create branches, commit changes, open PRs, monitor CI status, auto-fix failures, and merge" +description: "GitHub PR lifecycle: branch, commit, open, CI, merge" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 PR lifecycle: branch, commit, open, CI, merge. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md b/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md index 8392250346..bed4c151c6 100644 --- a/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md +++ b/website/docs/user-guide/skills/bundled/github/github-github-repo-management.md @@ -1,14 +1,14 @@ --- -title: "Github Repo Management — Clone, create, fork, configure, and manage GitHub repositories" +title: "Github Repo Management — Clone/create/fork repos; manage remotes, releases" sidebar_label: "Github Repo Management" -description: "Clone, create, fork, configure, and manage GitHub repositories" +description: "Clone/create/fork repos; manage remotes, releases" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Clone/create/fork repos; manage remotes, releases. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/mcp/mcp-native-mcp.md b/website/docs/user-guide/skills/bundled/mcp/mcp-native-mcp.md index 267c8c064c..fbece306fe 100644 --- a/website/docs/user-guide/skills/bundled/mcp/mcp-native-mcp.md +++ b/website/docs/user-guide/skills/bundled/mcp/mcp-native-mcp.md @@ -1,14 +1,14 @@ --- -title: "Native Mcp" +title: "Native Mcp — MCP client: connect servers, register tools (stdio/HTTP)" sidebar_label: "Native Mcp" -description: "Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools" +description: "MCP client: connect servers, register tools (stdio/HTTP)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 client: connect servers, register tools (stdio/HTTP). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/media/media-gif-search.md b/website/docs/user-guide/skills/bundled/media/media-gif-search.md index 67b56645db..2985c926e4 100644 --- a/website/docs/user-guide/skills/bundled/media/media-gif-search.md +++ b/website/docs/user-guide/skills/bundled/media/media-gif-search.md @@ -1,14 +1,14 @@ --- -title: "Gif Search — Search and download GIFs from Tenor using curl" +title: "Gif Search — Search/download GIFs from Tenor via curl + jq" sidebar_label: "Gif Search" -description: "Search and download GIFs from Tenor using curl" +description: "Search/download GIFs from Tenor via curl + jq" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Search/download GIFs from Tenor via curl + jq. ## Skill metadata @@ -31,6 +31,10 @@ The following is the complete skill definition that Hermes loads when this skill Search and download GIFs directly via the Tenor API using curl. No extra tools needed. +## When to use + +Useful for finding reaction GIFs, creating visual content, and sending GIFs in chat. + ## Setup Set your Tenor API key in your environment (add to `~/.hermes/.env`): diff --git a/website/docs/user-guide/skills/bundled/media/media-heartmula.md b/website/docs/user-guide/skills/bundled/media/media-heartmula.md index 85dae5e867..96df62c37b 100644 --- a/website/docs/user-guide/skills/bundled/media/media-heartmula.md +++ b/website/docs/user-guide/skills/bundled/media/media-heartmula.md @@ -1,14 +1,14 @@ --- -title: "Heartmula — Set up and run HeartMuLa, the open-source music generation model family (Suno-like)" +title: "Heartmula — HeartMuLa: Suno-like song generation from lyrics + tags" sidebar_label: "Heartmula" -description: "Set up and run HeartMuLa, the open-source music generation model family (Suno-like)" +description: "HeartMuLa: Suno-like song generation from lyrics + tags" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Heartmula -Set up and run HeartMuLa, the open-source music generation model family (Suno-like). Generates full songs from lyrics + tags with multilingual support. +HeartMuLa: Suno-like song generation from lyrics + tags. ## Skill metadata @@ -29,7 +29,7 @@ The following is the complete skill definition that Hermes loads when this skill # HeartMuLa - Open-Source Music Generation ## Overview -HeartMuLa is a family of open-source music foundation models (Apache-2.0) that generates music conditioned on lyrics and tags. Comparable to Suno for open-source. Includes: +HeartMuLa is a family of open-source music foundation models (Apache-2.0) that generates music conditioned on lyrics and tags, with multilingual support. Generates full songs from lyrics + tags. Comparable to Suno for open-source. Includes: - **HeartMuLa** - Music language model (3B/7B) for generation from lyrics + tags - **HeartCodec** - 12.5Hz music codec for high-fidelity audio reconstruction - **HeartTranscriptor** - Whisper-based lyrics transcription diff --git a/website/docs/user-guide/skills/bundled/media/media-songsee.md b/website/docs/user-guide/skills/bundled/media/media-songsee.md index 231b87ea3b..ee37f3972b 100644 --- a/website/docs/user-guide/skills/bundled/media/media-songsee.md +++ b/website/docs/user-guide/skills/bundled/media/media-songsee.md @@ -1,14 +1,14 @@ --- -title: "Songsee — Generate spectrograms and audio feature visualizations (mel, chroma, MFCC, tempogram, etc" +title: "Songsee — Audio spectrograms/features (mel, chroma, MFCC) via CLI" sidebar_label: "Songsee" -description: "Generate spectrograms and audio feature visualizations (mel, chroma, MFCC, tempogram, etc" +description: "Audio spectrograms/features (mel, chroma, MFCC) via CLI" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Audio spectrograms/features (mel, chroma, MFCC) via CLI. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/media/media-spotify.md b/website/docs/user-guide/skills/bundled/media/media-spotify.md index 4fbda84392..1a8068a68a 100644 --- a/website/docs/user-guide/skills/bundled/media/media-spotify.md +++ b/website/docs/user-guide/skills/bundled/media/media-spotify.md @@ -1,14 +1,14 @@ --- -title: "Spotify" +title: "Spotify — Spotify: play, search, queue, manage playlists and devices" sidebar_label: "Spotify" -description: "Control Spotify — play music, search the catalog, manage playlists and library, inspect devices and playback state" +description: "Spotify: play, search, queue, manage playlists and devices" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Spotify -Control Spotify — play music, search the catalog, manage playlists and library, inspect devices and playback state. Loads when the user asks to play/pause/queue music, search tracks/albums/artists, manage playlists, or check what's playing. Assumes the Hermes Spotify toolset is enabled and `hermes auth spotify` has been run. +Spotify: play, search, queue, manage playlists and devices. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/media/media-youtube-content.md b/website/docs/user-guide/skills/bundled/media/media-youtube-content.md index e94c755c98..4451c9bce4 100644 --- a/website/docs/user-guide/skills/bundled/media/media-youtube-content.md +++ b/website/docs/user-guide/skills/bundled/media/media-youtube-content.md @@ -1,14 +1,14 @@ --- -title: "Youtube Content" +title: "Youtube Content — YouTube transcripts to summaries, threads, blogs" sidebar_label: "Youtube Content" -description: "Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts)" +description: "YouTube transcripts to summaries, threads, blogs" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Youtube Content -Fetch YouTube video transcripts and transform them into structured content (chapters, summaries, threads, blog posts). Use when the user shares a YouTube URL or video link, asks to summarize a video, requests a transcript, or wants to extract and reformat content from any YouTube video. +YouTube transcripts to summaries, threads, blogs. ## Skill metadata @@ -25,6 +25,10 @@ The following is the complete skill definition that Hermes loads when this skill # YouTube Content Tool +## When to use + +Use when the user shares a YouTube URL or video link, asks to summarize a video, requests a transcript, or wants to extract and reformat content from any YouTube video. Transforms transcripts into structured content (chapters, summaries, threads, blog posts). + Extract transcripts from YouTube videos and convert them into useful formats. ## Setup diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md b/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md index 0112f747a3..096805b7c0 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-lm-evaluation-harness.md @@ -1,14 +1,14 @@ --- -title: "Evaluating Llms Harness — Evaluates LLMs across 60+ academic benchmarks (MMLU, HumanEval, GSM8K, TruthfulQA, HellaSwag)" +title: "Evaluating Llms Harness — lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc" sidebar_label: "Evaluating Llms Harness" -description: "Evaluates LLMs across 60+ academic benchmarks (MMLU, HumanEval, GSM8K, TruthfulQA, HellaSwag)" +description: "lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. Supports HuggingFace, vLLM, APIs. +lm-eval-harness: benchmark LLMs (MMLU, GSM8K, etc.). ## Skill metadata @@ -30,6 +30,10 @@ The following is the complete skill definition that Hermes loads when this skill # lm-evaluation-harness - LLM Benchmarking +## What's inside + +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. Supports HuggingFace, vLLM, APIs. + ## Quick start lm-evaluation-harness evaluates LLMs across 60+ academic benchmarks using standardized prompts and metrics. diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases.md b/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases.md index db8c4d4d71..7833eaed7e 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-evaluation-weights-and-biases.md @@ -1,14 +1,14 @@ --- -title: "Weights And Biases" +title: "Weights And Biases — W&B: log ML experiments, sweeps, model registry, dashboards" sidebar_label: "Weights And Biases" -description: "Track ML experiments with automatic logging, visualize training in real-time, optimize hyperparameters with sweeps, and manage model registry with W&B - coll..." +description: "W&B: log ML experiments, sweeps, model registry, dashboards" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 +W&B: log ML experiments, sweeps, model registry, dashboards. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub.md b/website/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub.md index 27ab41b5e2..ec0022bc8e 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-huggingface-hub.md @@ -1,14 +1,14 @@ --- -title: "Huggingface Hub" +title: "Huggingface Hub — HuggingFace hf CLI: search/download/upload models, datasets" sidebar_label: "Huggingface Hub" -description: "Hugging Face Hub CLI (hf) — search, download, and upload models and datasets, manage repos, query datasets with SQL, deploy inference endpoints, manage Space..." +description: "HuggingFace hf CLI: search/download/upload models, datasets" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Huggingface Hub -Hugging Face Hub CLI (hf) — search, download, and upload models and datasets, manage repos, query datasets with SQL, deploy inference endpoints, manage Spaces and buckets. +HuggingFace hf CLI: search/download/upload models, datasets. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-obliteratus.md b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-obliteratus.md index 25420ec5b9..ad92aa97d2 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-obliteratus.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-obliteratus.md @@ -1,14 +1,14 @@ --- -title: "Obliteratus" +title: "Obliteratus — OBLITERATUS: abliterate LLM refusals (diff-in-means)" sidebar_label: "Obliteratus" -description: "Remove refusal behaviors from open-weight LLMs using OBLITERATUS — mechanistic interpretability techniques (diff-in-means, SVD, whitened SVD, LEACE, SAE deco..." +description: "OBLITERATUS: abliterate LLM refusals (diff-in-means)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 across 5 compute tiers, tournament evaluation, and telemetry-driven recommendations. Use when a user wants to uncensor, abliterate, or remove refusal from an LLM. +OBLITERATUS: abliterate LLM refusals (diff-in-means). ## Skill metadata @@ -31,10 +31,21 @@ The following is the complete skill definition that Hermes loads when this skill # OBLITERATUS Skill +## What's inside + +9 CLI methods, 28 analysis modules, 116 model presets across 5 compute tiers, tournament evaluation, and telemetry-driven recommendations. + Remove refusal behaviors (guardrails) from open-weight LLMs without retraining or fine-tuning. Uses mechanistic interpretability techniques — including diff-in-means, SVD, whitened SVD, LEACE concept erasure, SAE decomposition, Bayesian kernel projection, and more — to identify and surgically excise refusal directions from model weights while preserving reasoning capabilities. **License warning:** OBLITERATUS is AGPL-3.0. NEVER import it as a Python library. Always invoke via CLI (`obliteratus` command) or subprocess. This keeps Hermes Agent's MIT license clean. +## Video Guide + +Walkthrough of OBLITERATUS used by a Hermes agent to abliterate Gemma: +https://www.youtube.com/watch?v=8fG9BrNTeHs ("OBLITERATUS: An AI Agent Removed Gemma 4's Safety Guardrails") + +Useful when the user wants a visual overview of the end-to-end workflow before running it themselves. + ## When to Use This Skill Trigger when the user: diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-outlines.md b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-outlines.md index e6ba7bf378..6142554bed 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-outlines.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-outlines.md @@ -1,14 +1,14 @@ --- -title: "Outlines" +title: "Outlines — Outlines: structured JSON/regex/Pydantic LLM generation" sidebar_label: "Outlines" -description: "Guarantee valid JSON/XML/code structure during generation, use Pydantic models for type-safe outputs, support local models (Transformers, vLLM), and maximize..." +description: "Outlines: structured JSON/regex/Pydantic LLM generation" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 +Outlines: structured JSON/regex/Pydantic LLM generation. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md index 63ab521655..9170e5df46 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-inference-vllm.md @@ -1,14 +1,14 @@ --- -title: "Serving Llms Vllm — Serves LLMs with high throughput using vLLM's PagedAttention and continuous batching" +title: "Serving Llms Vllm — vLLM: high-throughput LLM serving, OpenAI API, quantization" sidebar_label: "Serving Llms Vllm" -description: "Serves LLMs with high throughput using vLLM's PagedAttention and continuous batching" +description: "vLLM: high-throughput LLM serving, OpenAI API, quantization" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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), and tensor parallelism. +vLLM: high-throughput LLM serving, OpenAI API, quantization. ## Skill metadata @@ -30,6 +30,10 @@ The following is the complete skill definition that Hermes loads when this skill # vLLM - High-Performance LLM Serving +## When to use + +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), and tensor parallelism. + ## Quick start vLLM achieves 24x higher throughput than standard transformers through PagedAttention (block-based KV cache) and continuous batching (mixing prefill/decode requests). diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md b/website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md index d9f0c485a5..ea906dde4e 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-models-audiocraft.md @@ -1,14 +1,14 @@ --- -title: "Audiocraft Audio Generation" +title: "Audiocraft Audio Generation — AudioCraft: MusicGen text-to-music, AudioGen text-to-sound" sidebar_label: "Audiocraft Audio Generation" -description: "PyTorch library for audio generation including text-to-music (MusicGen) and text-to-sound (AudioGen)" +description: "AudioCraft: MusicGen text-to-music, AudioGen text-to-sound" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +AudioCraft: MusicGen text-to-music, AudioGen text-to-sound. ## Skill metadata @@ -146,6 +146,7 @@ torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000) ### Architecture overview + ``` AudioCraft Architecture: ┌──────────────────────────────────────────────────────────────┐ @@ -165,6 +166,7 @@ AudioCraft Architecture: │ Converts tokens back to audio waveform │ └──────────────────────────────────────────────────────────────┘ ``` + ### Model variants diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md b/website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md index 7ce304b116..8e9d8fc396 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-models-segment-anything.md @@ -1,14 +1,14 @@ --- -title: "Segment Anything Model — Foundation model for image segmentation with zero-shot transfer" +title: "Segment Anything Model — SAM: zero-shot image segmentation via points, boxes, masks" sidebar_label: "Segment Anything Model" -description: "Foundation model for image segmentation with zero-shot transfer" +description: "SAM: zero-shot image segmentation via points, boxes, masks" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +SAM: zero-shot image segmentation via points, boxes, masks. ## Skill metadata @@ -151,6 +151,7 @@ masks = processor.image_processor.post_process_masks( ### Model architecture + ``` SAM Architecture: @@ -163,6 +164,7 @@ SAM Architecture: (computed once) (per prompt) predictions ``` + ### Model variants diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-research-dspy.md b/website/docs/user-guide/skills/bundled/mlops/mlops-research-dspy.md index 6b84fc8ecb..57f9dc8ff8 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-research-dspy.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-research-dspy.md @@ -1,14 +1,14 @@ --- -title: "Dspy" +title: "Dspy — DSPy: declarative LM programs, auto-optimize prompts, RAG" sidebar_label: "Dspy" -description: "Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's frame..." +description: "DSPy: declarative LM programs, auto-optimize prompts, RAG" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 +DSPy: declarative LM programs, auto-optimize prompts, RAG. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-training-axolotl.md b/website/docs/user-guide/skills/bundled/mlops/mlops-training-axolotl.md index ad2fa3fb3a..408b92b610 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-training-axolotl.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-training-axolotl.md @@ -1,14 +1,14 @@ --- -title: "Axolotl" +title: "Axolotl — Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO)" sidebar_label: "Axolotl" -description: "Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support" +description: "Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Axolotl -Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support +Axolotl: YAML LLM fine-tuning (LoRA, DPO, GRPO). ## Skill metadata @@ -30,6 +30,10 @@ The following is the complete skill definition that Hermes loads when this skill # Axolotl Skill +## What's inside + +Expert guidance for fine-tuning LLMs with Axolotl — YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support. + Comprehensive assistance with axolotl development, generated from official documentation. ## When to Use This Skill diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-training-trl-fine-tuning.md b/website/docs/user-guide/skills/bundled/mlops/mlops-training-trl-fine-tuning.md index 4c0bf90ff5..766fa259ad 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-training-trl-fine-tuning.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-training-trl-fine-tuning.md @@ -1,14 +1,14 @@ --- -title: "Fine Tuning With Trl" +title: "Fine Tuning With Trl — TRL: SFT, DPO, PPO, GRPO, reward modeling for LLM RLHF" sidebar_label: "Fine Tuning With Trl" -description: "Fine-tune LLMs using reinforcement learning with TRL - SFT for instruction tuning, DPO for preference alignment, PPO/GRPO for reward optimization, and reward..." +description: "TRL: SFT, DPO, PPO, GRPO, reward modeling for LLM RLHF" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 Transformers. +TRL: SFT, DPO, PPO, GRPO, reward modeling for LLM RLHF. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/mlops/mlops-training-unsloth.md b/website/docs/user-guide/skills/bundled/mlops/mlops-training-unsloth.md index 2d936435c2..d692a81ac2 100644 --- a/website/docs/user-guide/skills/bundled/mlops/mlops-training-unsloth.md +++ b/website/docs/user-guide/skills/bundled/mlops/mlops-training-unsloth.md @@ -1,14 +1,14 @@ --- -title: "Unsloth" +title: "Unsloth — Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM" sidebar_label: "Unsloth" -description: "Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization" +description: "Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Unsloth -Expert guidance for fast fine-tuning with Unsloth - 2-5x faster training, 50-80% less memory, LoRA/QLoRA optimization +Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md b/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md new file mode 100644 index 0000000000..f1a313abb7 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md @@ -0,0 +1,242 @@ +--- +title: "Airtable — Airtable REST API via curl" +sidebar_label: "Airtable" +description: "Airtable REST API via curl" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Airtable + +Airtable REST API via curl. Records CRUD, filters, upserts. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/productivity/airtable` | +| Version | `1.1.0` | +| Author | community | +| License | MIT | +| Tags | `Airtable`, `Productivity`, `Database`, `API` | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Airtable — Bases, Tables & Records + +Work with Airtable's REST API directly via `curl` using the `terminal` tool. No MCP server, no OAuth flow, no Python SDK — just `curl` and a personal access token. + +## Prerequisites + +1. Create a **Personal Access Token (PAT)** at https://airtable.com/create/tokens (tokens start with `pat...`). +2. Grant these scopes (minimum): + - `data.records:read` — read rows + - `data.records:write` — create / update / delete rows + - `schema.bases:read` — list bases and tables +3. **Important:** in the same token UI, add each base you want to access to the token's **Access** list. PATs are scoped per-base — a valid token on the wrong base returns `403`. +4. Store the token in `~/.hermes/.env` (or via `hermes setup`): + ``` + AIRTABLE_API_KEY=pat_your_token_here + ``` + +> Note: legacy `key...` API keys were deprecated Feb 2024. Only PATs and OAuth tokens work now. + +## API Basics + +- **Endpoint:** `https://api.airtable.com/v0` +- **Auth header:** `Authorization: Bearer $AIRTABLE_API_KEY` +- **All requests** use JSON (`Content-Type: application/json` for any POST/PATCH/PUT body). +- **Object IDs:** bases `app...`, tables `tbl...`, records `rec...`, fields `fld...`. IDs never change; names can. Prefer IDs in automations. +- **Rate limit:** 5 requests/sec/base. `429` → back off. Burst on a single base will be throttled. + +Base curl pattern: +```bash +curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +`-s` suppresses curl's progress bar — keep it set for every call so the tool output stays clean for Hermes. Pipe through `python3 -m json.tool` (always present) or `jq` (if installed) for readable JSON. + +## Field Types (request body shapes) + +| Field type | Write shape | +|---|---| +| Single line text | `"Name": "hello"` | +| Long text | `"Notes": "multi\nline"` | +| Number | `"Score": 42` | +| Checkbox | `"Done": true` | +| Single select | `"Status": "Todo"` (name must already exist unless `typecast: true`) | +| Multi-select | `"Tags": ["urgent", "bug"]` | +| Date | `"Due": "2026-04-01"` | +| DateTime (UTC) | `"At": "2026-04-01T14:30:00.000Z"` | +| URL / Email / Phone | `"Link": "https://…"` | +| Attachment | `"Files": [{"url": "https://…"}]` (Airtable fetches + rehosts) | +| Linked record | `"Owner": ["recXXXXXXXXXXXXXX"]` (array of record IDs) | +| User | `"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}` | + +Pass `"typecast": true` at the top level of a create/update body to let Airtable auto-coerce values (e.g. create a new select option on the fly, convert `"42"` → `42`). + +## Common Queries + +### List bases the token can see +```bash +curl -s "https://api.airtable.com/v0/meta/bases" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +### List tables + schema for a base +```bash +curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` +Use this BEFORE mutating — confirms exact field names and IDs, surfaces `options.choices` for select fields, and shows primary-field names. + +### List records (first 10) +```bash +curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +### Get a single record +```bash +curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +### Filter records (filterByFormula) +Airtable formulas must be URL-encoded. Let Python stdlib do it — never hand-encode: +```bash +FORMULA="{Status}='Todo'" +ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA") +curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +Useful formula patterns: +- Exact match: `{Email}='user@example.com'` +- Contains: `FIND('bug', LOWER({Title}))` +- Multiple conditions: `AND({Status}='Todo', {Priority}='High')` +- Or: `OR({Owner}='alice', {Owner}='bob')` +- Not empty: `NOT({Assignee}='')` +- Date comparison: `IS_AFTER({Due}, TODAY())` + +### Sort + select specific fields +```bash +curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` +Square brackets in query params MUST be URL-encoded (`%5B` / `%5D`). + +### Use a named view +```bash +curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` +Views apply their saved filter + sort server-side. + +## Common Mutations + +### Create a record +```bash +curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool +``` + +### Create up to 10 records in one call +```bash +curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "typecast": true, + "records": [ + {"fields": {"Name": "Task A", "Status": "Todo"}}, + {"fields": {"Name": "Task B", "Status": "In progress"}} + ] + }' | python3 -m json.tool +``` +Batch endpoints are capped at **10 records per request**. For larger inserts, loop in batches of 10 with a short sleep to respect 5 req/sec/base. + +### Update a record (PATCH — merges, preserves unchanged fields) +```bash +curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool +``` + +### Upsert by a merge field (no ID needed) +```bash +curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "performUpsert": {"fieldsToMergeOn": ["Email"]}, + "records": [ + {"fields": {"Email": "user@example.com", "Status": "Active"}} + ] + }' | python3 -m json.tool +``` +`performUpsert` creates records whose merge-field values are new, patches records whose merge-field values already exist. Great for idempotent syncs. + +### Delete a record +```bash +curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +### Delete up to 10 records in one call +```bash +curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \ + -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool +``` + +## Pagination + +List endpoints return at most **100 records per page**. If the response includes `"offset": "..."`, pass it back on the next call. Loop until the field is absent: + +```bash +OFFSET="" +while :; do + URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100" + [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET" + RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY") + echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]' + OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))') + [ -z "$OFFSET" ] && break +done +``` + +## Typical Hermes Workflow + +1. **Confirm auth.** `curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY"` — expect `200`. +2. **Find the base.** List bases (step above) OR ask the user for the `app...` ID directly if the token lacks `schema.bases:read`. +3. **Inspect the schema.** `GET /v0/meta/bases/$BASE_ID/tables` — cache the exact field names and primary-field name locally in the session before mutating anything. +4. **Read before you write.** For "update X where Y", `filterByFormula` first to resolve the `rec...` ID, then `PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID`. Never guess record IDs. +5. **Batch writes.** Combine related creates into one 10-record POST to stay under the 5 req/sec budget. +6. **Destructive ops.** Deletions can't be undone via API. If the user says "delete all Xs", echo back the filter + record count and confirm before firing. + +## Pitfalls + +- **`filterByFormula` MUST be URL-encoded.** Field names with spaces or non-ASCII also need encoding (`{My Field}` → `%7BMy%20Field%7D`). Use Python stdlib (pattern above) — never hand-escape. +- **Empty fields are omitted from responses.** A missing `"Assignee"` key doesn't mean the field doesn't exist — it means this record's value is empty. Check the schema (step 3) before concluding a field is missing. +- **PATCH vs PUT.** `PATCH` merges supplied fields into the record. `PUT` replaces the record entirely and clears any field you didn't include. Default to `PATCH`. +- **Single-select options must exist.** Writing `"Status": "Shipping"` when `Shipping` isn't in the field's option list errors with `INVALID_MULTIPLE_CHOICE_OPTIONS` unless you pass `"typecast": true` (which auto-creates the option). +- **Per-base token scoping.** A `403` on one base while another works means the token's Access list doesn't include that base — not a scope or auth issue. Send the user to https://airtable.com/create/tokens to grant it. +- **Rate limits are per base, not per token.** 5 req/sec on `baseA` and 5 req/sec on `baseB` is fine; 6 req/sec on `baseA` alone will throttle. Monitor the `Retry-After` header on `429`. + +## Important Notes for Hermes + +- **Always use the `terminal` tool with `curl`.** Do NOT use `web_extract` (it can't send auth headers) or `browser_navigate` (needs UI auth and is slow). +- **`AIRTABLE_API_KEY` flows from `~/.hermes/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call. +- **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python3 urllib.parse.quote` before splicing into a URL. +- **Pretty-print with `python3 -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection. +- **Pagination is per-page, not global.** Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with `offset` until the field is absent. +- **Read the `errors` array** on non-2xx responses — Airtable returns structured error codes like `AUTHENTICATION_REQUIRED`, `INVALID_PERMISSIONS`, `MODEL_ID_NOT_FOUND`, `INVALID_MULTIPLE_CHOICE_OPTIONS` that tell you exactly what's wrong. diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md b/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md index c49ddf337d..ff7975e4c2 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md @@ -1,14 +1,14 @@ --- -title: "Google Workspace — Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes" +title: "Google Workspace — Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python" sidebar_label: "Google Workspace" -description: "Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes" +description: "Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Google Workspace -Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses Hermes-managed OAuth2 setup, prefers the Google Workspace CLI (`gws`) when available for broader API coverage, and falls back to the Python client libraries otherwise. +Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-linear.md b/website/docs/user-guide/skills/bundled/productivity/productivity-linear.md index 548537f479..f6a2d0c3e2 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-linear.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-linear.md @@ -1,14 +1,14 @@ --- -title: "Linear — Manage Linear issues, projects, and teams via the GraphQL API" +title: "Linear — Linear: manage issues, projects, teams via GraphQL + curl" sidebar_label: "Linear" -description: "Manage Linear issues, projects, and teams via the GraphQL API" +description: "Linear: manage issues, projects, teams via GraphQL + curl" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Linear -Manage Linear issues, projects, and teams via the GraphQL API. Create, update, search, and organize issues. Uses API key auth (no OAuth needed). All operations via curl — no dependencies. +Linear: manage issues, projects, teams via GraphQL + curl. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md b/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md index 0010be1500..6f15c1d778 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-maps.md @@ -1,14 +1,14 @@ --- -title: "Maps" +title: "Maps — Geocode, POIs, routes, timezones via OpenStreetMap/OSRM" sidebar_label: "Maps" -description: "Location intelligence — geocode a place, reverse-geocode coordinates, find nearby places (46 POI categories), driving/walking/cycling distance + time, turn-b..." +description: "Geocode, POIs, routes, timezones via OpenStreetMap/OSRM" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Maps -Location intelligence — geocode a place, reverse-geocode coordinates, find nearby places (46 POI categories), driving/walking/cycling distance + time, turn-by-turn directions, timezone lookup, bounding box + area for a named place, and POI search within a rectangle. Uses OpenStreetMap + Overpass + OSRM. Free, no API key. +Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md index afb7d980f1..2cec19cf59 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-nano-pdf.md @@ -1,14 +1,14 @@ --- -title: "Nano Pdf — Edit PDFs with natural-language instructions using the nano-pdf CLI" +title: "Nano Pdf — Edit PDF text/typos/titles via nano-pdf CLI (NL prompts)" sidebar_label: "Nano Pdf" -description: "Edit PDFs with natural-language instructions using the nano-pdf CLI" +description: "Edit PDF text/typos/titles via nano-pdf CLI (NL prompts)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Edit PDF text/typos/titles via nano-pdf CLI (NL prompts). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md b/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md index 20861f428c..5410808df3 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-notion.md @@ -1,14 +1,14 @@ --- -title: "Notion — Notion API for creating and managing pages, databases, and blocks via curl" +title: "Notion — Notion API via curl: pages, databases, blocks, search" sidebar_label: "Notion" -description: "Notion API for creating and managing pages, databases, and blocks via curl" +description: "Notion API via curl: pages, databases, blocks, search" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Notion -Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal. +Notion API via curl: pages, databases, blocks, search. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md b/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md index be97d1adb6..be23630c92 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-ocr-and-documents.md @@ -1,14 +1,14 @@ --- -title: "Ocr And Documents — Extract text from PDFs and scanned documents" +title: "Ocr And Documents — Extract text from PDFs/scans (pymupdf, marker-pdf)" sidebar_label: "Ocr And Documents" -description: "Extract text from PDFs and scanned documents" +description: "Extract text from PDFs/scans (pymupdf, marker-pdf)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Extract text from PDFs/scans (pymupdf, marker-pdf). ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md index 5b32f86f49..602a9bedb3 100644 --- a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md +++ b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md @@ -1,14 +1,14 @@ --- -title: "Powerpoint — Use this skill any time a" +title: "Powerpoint — Create, read, edit" sidebar_label: "Powerpoint" -description: "Use this skill any time a" +description: "Create, read, edit" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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 an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill. +Create, read, edit .pptx decks, slides, notes, templates. ## Skill metadata @@ -26,6 +26,10 @@ The following is the complete skill definition that Hermes loads when this skill # Powerpoint Skill +## When to use + +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 an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill. + ## Quick Reference | Task | Guide | diff --git a/website/docs/user-guide/skills/bundled/red-teaming/red-teaming-godmode.md b/website/docs/user-guide/skills/bundled/red-teaming/red-teaming-godmode.md index c71b5fdce6..b0d6b7f047 100644 --- a/website/docs/user-guide/skills/bundled/red-teaming/red-teaming-godmode.md +++ b/website/docs/user-guide/skills/bundled/red-teaming/red-teaming-godmode.md @@ -1,14 +1,14 @@ --- -title: "Godmode" +title: "Godmode — Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN" sidebar_label: "Godmode" -description: "Jailbreak API-served LLMs using G0DM0D3 techniques — Parseltongue input obfuscation (33 techniques), GODMODE CLASSIC system prompt templates, ULTRAPLINIAN mu..." +description: "Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Godmode -Jailbreak API-served LLMs using G0DM0D3 techniques — Parseltongue input obfuscation (33 techniques), GODMODE CLASSIC system prompt templates, ULTRAPLINIAN multi-model racing, encoding escalation, and Hermes-native prefill/system prompt integration. Use when a user wants to bypass safety filters, jailbreak a model, or red-team model robustness. +Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/research/research-arxiv.md b/website/docs/user-guide/skills/bundled/research/research-arxiv.md index 6141dc0968..ea415500df 100644 --- a/website/docs/user-guide/skills/bundled/research/research-arxiv.md +++ b/website/docs/user-guide/skills/bundled/research/research-arxiv.md @@ -1,14 +1,14 @@ --- -title: "Arxiv — Search and retrieve academic papers from arXiv using their free REST API" +title: "Arxiv — Search arXiv papers by keyword, author, category, or ID" sidebar_label: "Arxiv" -description: "Search and retrieve academic papers from arXiv using their free REST API" +description: "Search arXiv papers by keyword, author, category, or ID" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Search arXiv papers by keyword, author, category, or ID. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/research/research-blogwatcher.md b/website/docs/user-guide/skills/bundled/research/research-blogwatcher.md index b49fe43d5e..ddd044b247 100644 --- a/website/docs/user-guide/skills/bundled/research/research-blogwatcher.md +++ b/website/docs/user-guide/skills/bundled/research/research-blogwatcher.md @@ -1,14 +1,14 @@ --- -title: "Blogwatcher — Monitor blogs and RSS/Atom feeds for updates using the blogwatcher-cli tool" +title: "Blogwatcher — Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool" sidebar_label: "Blogwatcher" -description: "Monitor blogs and RSS/Atom feeds for updates using the blogwatcher-cli tool" +description: "Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Blogwatcher -Monitor blogs and RSS/Atom feeds for updates using the blogwatcher-cli tool. Add blogs, scan for new articles, track read status, and filter by category. +Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md b/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md index a44bde173e..ce31d7a721 100644 --- a/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md +++ b/website/docs/user-guide/skills/bundled/research/research-llm-wiki.md @@ -1,14 +1,14 @@ --- -title: "Llm Wiki — Karpathy's LLM Wiki — build and maintain a persistent, interlinked markdown knowledge base" +title: "Llm Wiki — Karpathy's LLM Wiki: build/query interlinked markdown KB" sidebar_label: "Llm Wiki" -description: "Karpathy's LLM Wiki — build and maintain a persistent, interlinked markdown knowledge base" +description: "Karpathy's LLM Wiki: build/query interlinked markdown KB" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Llm Wiki -Karpathy's LLM Wiki — build and maintain a persistent, interlinked markdown knowledge base. Ingest sources, query compiled knowledge, and lint for consistency. +Karpathy's LLM Wiki: build/query interlinked markdown KB. ## Skill metadata @@ -64,6 +64,7 @@ any editor. No database, no special tooling required. ## Architecture: Three Layers + ``` wiki/ ├── SCHEMA.md # Conventions, structure rules, domain config @@ -79,6 +80,7 @@ wiki/ ├── comparisons/ # Layer 2: Side-by-side analyses └── queries/ # Layer 2: Filed query results worth keeping ``` + **Layer 1 — Raw Sources:** Immutable. The agent reads but never modifies these. **Layer 2 — The Wiki:** Agent-owned markdown files. Created, updated, and diff --git a/website/docs/user-guide/skills/bundled/research/research-polymarket.md b/website/docs/user-guide/skills/bundled/research/research-polymarket.md index 1d7ca2de10..b0aa23715c 100644 --- a/website/docs/user-guide/skills/bundled/research/research-polymarket.md +++ b/website/docs/user-guide/skills/bundled/research/research-polymarket.md @@ -1,14 +1,14 @@ --- -title: "Polymarket — Query Polymarket prediction market data — search markets, get prices, orderbooks, and price history" +title: "Polymarket — Query Polymarket: markets, prices, orderbooks, history" sidebar_label: "Polymarket" -description: "Query Polymarket prediction market data — search markets, get prices, orderbooks, and price history" +description: "Query Polymarket: markets, prices, orderbooks, history" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Polymarket -Query Polymarket prediction market data — search markets, get prices, orderbooks, and price history. Read-only via public REST APIs, no API key needed. +Query Polymarket: markets, prices, orderbooks, history. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md index 790b00d3cb..9dc216ebac 100644 --- a/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md +++ b/website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md @@ -1,14 +1,14 @@ --- -title: "Research Paper Writing" +title: "Research Paper Writing — Write ML papers for NeurIPS/ICML/ICLR: design→submit" sidebar_label: "Research Paper Writing" -description: "End-to-end pipeline for writing ML/AI research papers — from experiment design through analysis, drafting, revision, and submission" +description: "Write ML papers for NeurIPS/ICML/ICLR: design→submit" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Research Paper Writing -End-to-end pipeline for writing ML/AI research papers — from experiment design through analysis, drafting, revision, and submission. Covers NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Integrates automated experiment monitoring, statistical analysis, iterative writing, and citation verification. +Write ML papers for NeurIPS/ICML/ICLR: design→submit. ## Skill metadata @@ -36,6 +36,7 @@ End-to-end pipeline for producing publication-ready ML/AI research papers target This is **not a linear pipeline** — it is an iterative loop. Results trigger new experiments. Reviews trigger new analysis. The agent must handle these feedback loops. + ``` ┌─────────────────────────────────────────────────────────────┐ @@ -57,6 +58,7 @@ This is **not a linear pipeline** — it is an iterative loop. Results trigger n └─────────────────────────────────────────────────────────────┘ ``` + --- @@ -739,6 +741,7 @@ Any output in this pipeline — paper drafts, experiment scripts, analysis — c **Core insight**: Autoreason's value depends on the gap between a model's generation capability and its self-evaluation capability. + ``` Model Tier │ Generation │ Self-Eval │ Gap │ Autoreason Value ──────────────────┼────────────┼───────────┼────────┼───────────────── @@ -748,6 +751,7 @@ Mid (Gemini Flash)│ Decent │ Moderate │ Large │ High — wins 2/3 Strong (Sonnet 4) │ Good │ Decent │ Medium │ Moderate — wins 3/5 Frontier (S4.6) │ Excellent │ Good │ Small │ Only with constraints ``` + This gap is structural, not temporary. As costs drop, today's frontier becomes tomorrow's mid-tier. The sweet spot moves but never disappears. diff --git a/website/docs/user-guide/skills/bundled/smart-home/smart-home-openhue.md b/website/docs/user-guide/skills/bundled/smart-home/smart-home-openhue.md index b420bb19ac..1088dd808b 100644 --- a/website/docs/user-guide/skills/bundled/smart-home/smart-home-openhue.md +++ b/website/docs/user-guide/skills/bundled/smart-home/smart-home-openhue.md @@ -1,14 +1,14 @@ --- -title: "Openhue — Control Philips Hue lights, rooms, and scenes via the OpenHue CLI" +title: "Openhue — Control Philips Hue lights, scenes, rooms via OpenHue CLI" sidebar_label: "Openhue" -description: "Control Philips Hue lights, rooms, and scenes via the OpenHue CLI" +description: "Control Philips Hue lights, scenes, rooms via OpenHue CLI" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Openhue -Control Philips Hue lights, rooms, and scenes via the OpenHue CLI. Turn lights on/off, adjust brightness, color, color temperature, and activate scenes. +Control Philips Hue lights, scenes, rooms via OpenHue CLI. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md index 25b51603de..15ab18eea7 100644 --- a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md +++ b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md @@ -1,14 +1,14 @@ --- -title: "Xurl — Interact with X/Twitter via xurl, the official X API CLI" +title: "Xurl — X/Twitter via xurl CLI: post, search, DM, media, v2 API" sidebar_label: "Xurl" -description: "Interact with X/Twitter via xurl, the official X API CLI" +description: "X/Twitter via xurl CLI: post, search, DM, media, v2 API" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Xurl -Interact with X/Twitter via xurl, the official X API CLI. Use for posting, replying, quoting, searching, timelines, mentions, likes, reposts, bookmarks, follows, DMs, media upload, and raw v2 endpoint access. +X/Twitter via xurl CLI: post, search, DM, media, v2 API. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands.md b/website/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands.md new file mode 100644 index 0000000000..daa92ee2ef --- /dev/null +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands.md @@ -0,0 +1,171 @@ +--- +title: "Debugging Hermes Tui Commands — Debug Hermes TUI slash commands: Python, gateway, Ink UI" +sidebar_label: "Debugging Hermes Tui Commands" +description: "Debug Hermes TUI slash commands: Python, gateway, Ink UI" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Debugging Hermes Tui Commands + +Debug Hermes TUI slash commands: Python, gateway, Ink UI. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/software-development/debugging-hermes-tui-commands` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Tags | `debugging`, `hermes-agent`, `tui`, `slash-commands`, `typescript`, `python` | +| Related skills | [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Debugging Hermes TUI Slash Commands + +## Overview + +Hermes slash commands span three layers — Python command registry, tui_gateway JSON-RPC bridge, and the Ink/TypeScript frontend. When a command misbehaves (missing from autocomplete, works in CLI but not TUI, config persists but UI doesn't update), the bug is almost always one layer being out of sync with another. + +Use this skill when you encounter issues with slash commands in the Hermes TUI, particularly when commands aren't showing in autocomplete, aren't working properly in the TUI, or need to be added/updated. + +## When to Use + +- A slash command exists in one part of the codebase but doesn't work fully +- A command needs to be added to both backend and frontend +- Command autocomplete isn't working for specific commands +- Command behavior is inconsistent between CLI and TUI +- A command persists config but doesn't apply live in the TUI + +## Architecture Overview + + +``` +Python backend (hermes_cli/commands.py) <- canonical COMMAND_REGISTRY + │ + ▼ +TUI gateway (tui_gateway/server.py) <- slash.exec / command.dispatch + │ + ▼ +TUI frontend (ui-tui/src/app/slash/) <- local handlers + fallthrough +``` + + +Command definitions must be registered consistently across Python and TypeScript to work properly. The Python `COMMAND_REGISTRY` is the source of truth for: CLI dispatch, gateway help, Telegram BotCommand menu, Slack subcommand map, and autocomplete data shipped to Ink. + +## Investigation Steps + +1. **Check if the command exists in the TUI frontend:** + ```bash + search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/ + search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-tui/ + ``` + +2. **Examine the TUI command definition:** + ```bash + read_file ui-tui/src/app/slash/commands/core.ts + # If not there: + search_files --pattern "commandname" --path ui-tui/src/app/slash/commands --target files + ``` + +3. **Check if the command exists in the Python backend:** + ```bash + search_files --pattern "CommandDef" --file_glob "*.py" --path hermes_cli/ + search_files --pattern "commandname" --path hermes_cli/commands.py --context 3 + ``` + +4. **Examine the gateway implementation:** + ```bash + search_files --pattern "complete.slash|slash.exec" --path tui_gateway/ + ``` + +## Fix: Missing Command Autocomplete + +If a command exists in the TUI but doesn't show in autocomplete: + +1. Add a `CommandDef` entry to `COMMAND_REGISTRY` in `hermes_cli/commands.py`: + ```python + CommandDef("commandname", "Description of the command", "Session", + cli_only=True, aliases=("alias",), + args_hint="[arg1|arg2|arg3]", + subcommands=("arg1", "arg2", "arg3")), + ``` + +2. Pick `cli_only` vs gateway availability carefully: + - `cli_only=True` — only in the interactive CLI/TUI + - `gateway_only=True` — only in messaging platforms + - neither — available everywhere + - `gateway_config_gate="display.foo"` — config-gated availability in the gateway + +3. Ensure `subcommands` matches the expected tab-completion options shown by the TUI. + +4. If the command runs server-side, add a handler in `HermesCLI.process_command()` in `cli.py`: + ```python + elif canonical == "commandname": + self._handle_commandname(cmd_original) + ``` + +5. For gateway-available commands, add a handler in `gateway/run.py`: + ```python + if canonical == "commandname": + return await self._handle_commandname(event) + ``` + +## Common Issues + +1. **Command shows in TUI but not in autocomplete.** The command is defined in the TUI codebase but missing from `COMMAND_REGISTRY` in `hermes_cli/commands.py`. Autocomplete data ships from Python. + +2. **Command shows in autocomplete but doesn't work.** Check the command handler in `tui_gateway/server.py` and the frontend handler in `ui-tui/src/app/createSlashHandler.ts`. If the command is local-only in Ink, it must be handled in `app.tsx` built-in branch; otherwise it falls through to `slash.exec` and must have a Python handler. + +3. **Command behavior differs between CLI and TUI.** The command might have different implementations. Check both `cli.py::process_command` and the TUI's local handler. Local TUI handlers take precedence over gateway dispatch. + +4. **Command persists config but doesn't apply live.** For TUI-local commands, updating `config.set` is not enough. Also patch the relevant nanostore state immediately (usually `patchUiState(...)`) and pass any new state through rendering components. Example: `/details collapsed` must update live detail visibility, not just save `details_mode`; in-session global `/details ` may need a separate command-override flag so live commands can override built-in section defaults while startup/config sync preserves default-expanded thinking/tools behavior. + +5. **Gateway dispatch silently ignores the command.** The gateway only dispatches commands it knows about. Check `GATEWAY_KNOWN_COMMANDS` (derived from `COMMAND_REGISTRY` automatically) includes the canonical name. If the command is `cli_only` with a `gateway_config_gate`, verify the gated config value is truthy. + +## Debugging Tactics + +When surface-level inspection doesn't reveal the bug: + +- **Python side hangs or misbehaves:** use the `python-debugpy` skill to break inside `_SlashWorker.exec` or the command handler. `remote-pdb` set at the handler entry is the fastest path. +- **Ink side not reacting:** use the `node-inspect-debugger` skill to break in `app.tsx`'s slash dispatch or the local command branch. `sb('dist/app.js', )` after `npm run build`. +- **Registry mismatch / unclear which side is wrong:** compare the canonical `COMMAND_REGISTRY` entry against the TUI's local command list side-by-side. + +## Pitfalls + +- Don't forget to set the appropriate category for the command in `CommandDef` (e.g., "Session", "Configuration", "Tools & Skills", "Info", "Exit") +- Make sure any aliases are properly registered in the `aliases` tuple — no other file changes are needed, everything downstream (Telegram menu, Slack mapping, autocomplete, help) derives from it +- For commands with subcommands, ensure the `subcommands` tuple in `CommandDef` matches what's in the TUI code +- `cli_only=True` commands won't work in gateway/messaging platforms — unless you add a `gateway_config_gate` and the gate is truthy +- After adding live UI state, search every consumer of the old prop/helper and thread the new state through all render paths, not just the active streaming path. TUI detail rendering has at least two important paths: live `StreamingAssistant`/`ToolTrail` and transcript/pending `MessageLine` rows. A `/clean` pass should explicitly check both. +- Rebuild the TUI (`npm --prefix ui-tui run build`) before testing — tsx watch mode may lag on first launch + +## Verification + +After fixing: + +1. Rebuild the TUI: + ```bash + cd /home/bb/hermes-agent && npm --prefix ui-tui run build + ``` + +2. Run the TUI and test the command: + ```bash + hermes --tui + ``` + +3. Type `/` and verify the command appears in autocomplete suggestions with the expected description and args hint. + +4. Execute the command and confirm: + - Expected behavior fires + - Any persisted config updates correctly (`read_file ~/.hermes/config.yaml`) + - Live UI state reflects the change immediately (not just after restart) + +5. If the command is also gateway-available, test it from at least one messaging platform (or run the gateway tests: `scripts/run_tests.sh tests/gateway/`). diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md new file mode 100644 index 0000000000..68741b060d --- /dev/null +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring.md @@ -0,0 +1,182 @@ +--- +title: "Hermes Agent Skill Authoring — Author in-repo SKILL" +sidebar_label: "Hermes Agent Skill Authoring" +description: "Author in-repo SKILL" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Hermes Agent Skill Authoring + +Author in-repo SKILL.md: frontmatter, validator, structure. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/software-development/hermes-agent-skill-authoring` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Tags | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` | +| Related skills | [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Authoring Hermes-Agent Skills (in-repo) + +## Overview + +There are two places a SKILL.md can live: + +1. **User-local:** `~/.hermes/skills///SKILL.md` — personal, not shared. Created via `skill_manage(action='create')`. +2. **In-repo (this skill is about this case):** `/home/bb/hermes-agent/skills///SKILL.md` — committed, shipped with the package. Use `write_file` + `git add`. `skill_manage(action='create')` does NOT target this tree. + +## When to Use + +- User asks you to add a skill "in this branch / repo / commit" +- You're committing a reusable workflow that should ship with hermes-agent +- You're editing an existing skill under `/home/bb/hermes-agent/skills/` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`) + +## Required Frontmatter + +Source of truth: `tools/skill_manager_tool.py::_validate_frontmatter`. Hard requirements: + +- Starts with `---` as the first bytes (no leading blank line). +- Closes with `\n---\n` before the body. +- Parses as a YAML mapping. +- `name` field present. +- `description` field present, ≤ **1024 chars** (`MAX_DESCRIPTION_LENGTH`). +- Non-empty body after the closing `---`. + +Peer-matched shape used by every skill under `skills/software-development/`: + +```yaml +--- +name: my-skill-name # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH) +description: Use when . . +version: 1.0.0 +author: Hermes Agent +license: MIT +metadata: + hermes: + tags: [short, descriptive, tags] + related_skills: [other-skill, another-skill] +--- +``` + +`version` / `author` / `license` / `metadata` are NOT enforced by the validator, but every peer has them — omit and your skill sticks out. + +## Size Limits + +- Description: ≤ 1024 chars (enforced). +- Full SKILL.md: ≤ 100,000 chars (enforced as `MAX_SKILL_CONTENT_CHARS`, ~36k tokens). +- Peer skills in `software-development/` sit at **8-14k chars**. Aim for that range. If you're pushing past 20k, split into `references/*.md` and reference them from SKILL.md. + +## Peer-Matched Structure + +Every in-repo skill follows roughly: + +``` +# + +## Overview +One or two paragraphs: what and why. + +## When to Use +- Bulleted triggers +- "Don't use for:" counter-triggers + +## <Topic sections specific to the skill> +- Quick-reference tables are common +- Code blocks with exact commands +- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.) + +## Common Pitfalls +Numbered list of mistakes and their fixes. + +## Verification Checklist +- [ ] Checkbox list of post-action verifications + +## One-Shot Recipes (optional) +Named scenarios → concrete command sequences. +``` + +Not every section is mandatory, but `Overview` + `When to Use` + actionable body + pitfalls are the minimum for the skill to feel like a peer. + +## Directory Placement + +``` +skills/<category>/<skill-name>/SKILL.md +``` + +Categories currently in repo (confirm with `ls skills/`): `autonomous-ai-agents`, `creative`, `data-science`, `devops`, `dogfood`, `email`, `gaming`, `github`, `leisure`, `mcp`, `media`, `mlops/*`, `note-taking`, `productivity`, `red-teaming`, `research`, `smart-home`, `social-media`, `software-development`. + +Pick the closest existing category. Don't invent new top-level categories casually. + +## Workflow + +1. **Survey peers** in the target category: + ``` + ls skills/<category>/ + ``` + Read 2-3 peer SKILL.md files to match tone and structure. +2. **Check validator constraints** in `tools/skill_manager_tool.py` if unsure. +3. **Draft** with `write_file` to `skills/<category>/<name>/SKILL.md`. +4. **Validate locally**: + ```python + import yaml, re, pathlib + content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text() + assert content.startswith("---") + m = re.search(r'\n---\s*\n', content[3:]) + fm = yaml.safe_load(content[3:m.start()+3]) + assert "name" in fm and "description" in fm + assert len(fm["description"]) <= 1024 + assert len(content) <= 100_000 + ``` +5. **Git add + commit** on the active branch. +6. **Note:** the CURRENT session's skill loader is cached — `skill_view` / `skills_list` will not see the new skill until a new session. This is expected, not a bug. + +## Cross-Referencing Other Skills + +`metadata.hermes.related_skills` unions both trees (`skills/` in-repo and `~/.hermes/skills/`) at load time. You CAN reference a user-local skill from an in-repo skill, but it won't resolve for other users who clone the repo fresh. Prefer referencing only in-repo skills from in-repo skills. If a frequently-referenced skill lives only in `~/.hermes/skills/`, consider promoting it to the repo. + +## Editing Existing In-Repo Skills + +- **Small fix (typo, added pitfall, tightened trigger):** `skill_manage(action='patch', name=..., old_string=..., new_string=...)` works fine on in-repo skills. +- **Major rewrite:** `write_file` the whole SKILL.md. `skill_manage(action='edit')` also works but requires supplying the full new content. +- **Adding supporting files:** `write_file` to `skills/<category>/<name>/references/<file>.md`, `templates/<file>`, or `scripts/<file>`. `skill_manage(action='write_file')` also works and enforces the references/templates/scripts/assets subdir allowlist. +- **Always commit** the edit — in-repo skills are source, not runtime state. + +## Common Pitfalls + +1. **Using `skill_manage(action='create')` for an in-repo skill.** It writes to `~/.hermes/skills/`, not the repo tree. Use `write_file` for in-repo creation. + +2. **Leading whitespace before `---`.** The validator checks `content.startswith("---")`; any leading blank line or BOM fails validation. + +3. **Description too generic.** Peer descriptions start with "Use when ..." and describe the *trigger class*, not the one task. "Use when debugging X" > "Debug X". + +4. **Forgetting the author/license/metadata block.** Not validator-enforced, but every peer has it; omitting makes the skill look half-finished. + +5. **Writing a skill that duplicates a peer.** Before creating, `ls skills/<category>/` and open 2-3 peers. Prefer extending an existing skill to creating a narrow sibling. + +6. **Expecting the current session to see the new skill.** It won't. The skill loader is initialized at session start. Verify in a fresh session or via `skill_view` using the exact path. + +7. **Linking to skills that don't exist in-repo.** `related_skills: [some-user-local-skill]` works for you but breaks for other clones. Prefer only in-repo links. + +## Verification Checklist + +- [ ] File is at `skills/<category>/<name>/SKILL.md` (not in `~/.hermes/skills/`) +- [ ] Frontmatter starts at byte 0 with `---`, closes with `\n---\n` +- [ ] `name`, `description`, `version`, `author`, `license`, `metadata.hermes.{tags, related_skills}` all present +- [ ] Name ≤ 64 chars, lowercase + hyphens +- [ ] Description ≤ 1024 chars and starts with "Use when ..." +- [ ] Total file ≤ 100,000 chars (aim for 8-15k) +- [ ] Structure: `# Title` → `## Overview` → `## When to Use` → body → `## Common Pitfalls` → `## Verification Checklist` +- [ ] `related_skills` references resolve in-repo (or are explicitly OK to be user-local) +- [ ] `git add skills/<category>/<name>/ && git commit` completed on the intended branch diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md new file mode 100644 index 0000000000..575c5edaa4 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md @@ -0,0 +1,336 @@ +--- +title: "Node Inspect Debugger — Debug Node" +sidebar_label: "Node Inspect Debugger" +description: "Debug Node" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Node Inspect Debugger + +Debug Node.js via --inspect + Chrome DevTools Protocol CLI. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/software-development/node-inspect-debugger` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` | +| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Node.js Inspect Debugger + +## Overview + +When `console.log` isn't enough, drive Node's built-in V8 inspector programmatically from the terminal. You get real breakpoints, step in/over/out, call-stack walking, local/closure scope dumps, and arbitrary expression evaluation in the paused frame. + +Two tools, pick one: + +- **`node inspect`** — built-in, zero install, CLI REPL. Best for quick poking. +- **`ndb` / CDP via `chrome-remote-interface`** — scriptable from Node/Python; best when you want to automate many breakpoints, collect state across runs, or debug non-interactively from an agent loop. + +**Prefer `node inspect` first.** It's always available and the REPL is fast. + +## When to Use + +- A Node test fails and you need to see intermediate state +- ui-tui crashes or behaves wrong and you want to inspect React/Ink state pre-render +- tui_gateway child processes (`_SlashWorker`, PTY bridge workers) misbehave +- You need to inspect a value in a closure that `console.log` can't reach without patching +- Perf: attach to a running process to capture a CPU profile or heap snapshot + +**Don't use for:** things `console.log` solves in under a minute. Breakpoint-driven debugging is heavier; use it when the payoff is real. + +## Quick Reference: `node inspect` REPL + +Launch paused on first line: + +```bash +node inspect path/to/script.js +# or with tsx +node --inspect-brk $(which tsx) path/to/script.ts +``` + +The `debug>` prompt accepts: + +| Command | Action | +|---|---| +| `c` or `cont` | continue | +| `n` or `next` | step over | +| `s` or `step` | step into | +| `o` or `out` | step out | +| `pause` | pause running code | +| `sb('file.js', 42)` | set breakpoint at file.js line 42 | +| `sb(42)` | set breakpoint at line 42 of current file | +| `sb('functionName')` | break when function is called | +| `cb('file.js', 42)` | clear breakpoint | +| `breakpoints` | list all breakpoints | +| `bt` | backtrace (call stack) | +| `list(5)` | show 5 lines of source around current position | +| `watch('expr')` | evaluate expr on every pause | +| `watchers` | show watched expressions | +| `repl` | drop into REPL in current scope (Ctrl+C to exit REPL) | +| `exec expr` | evaluate expression once | +| `restart` | restart script | +| `kill` | kill the script | +| `.exit` | quit debugger | + +**In the `repl` sub-mode:** type any JS expression, including access to locals/closure variables. `Ctrl+C` exits back to `debug>`. + +## Attaching to a Running Process + +When the process is already running (e.g. a long-lived dev server or the TUI gateway): + +```bash +# 1. Send SIGUSR1 to enable the inspector on an existing process +kill -SIGUSR1 <pid> +# Node prints: Debugger listening on ws://127.0.0.1:9229/<uuid> + +# 2. Attach the debugger CLI +node inspect -p <pid> +# or by URL +node inspect ws://127.0.0.1:9229/<uuid> +``` + +To start a process with the inspector from the beginning: + +```bash +node --inspect script.js # listen on 127.0.0.1:9229, keep running +node --inspect-brk script.js # listen AND pause on first line +node --inspect=0.0.0.0:9230 script.js # custom host:port +``` + +For TypeScript via tsx: + +```bash +node --inspect-brk --import tsx script.ts +# or older tsx +node --inspect-brk -r tsx/cjs script.ts +``` + +## Programmatic CDP (scripting from terminal) + +When you want to automate — set many breakpoints, capture scope state, script a repro — use `chrome-remote-interface`: + +```bash +npm i -g chrome-remote-interface # or project-local +# Start your target: +node --inspect-brk=9229 target.js & +``` + +Driver script (save as `/tmp/cdp-debug.js`): + +```javascript +const CDP = require('chrome-remote-interface'); + +(async () => { + const client = await CDP({ port: 9229 }); + const { Debugger, Runtime } = client; + + Debugger.paused(async ({ callFrames, reason }) => { + const top = callFrames[0]; + console.log(`PAUSED: ${reason} @ ${top.url}:${top.location.lineNumber + 1}`); + + // Walk scopes for locals + for (const scope of top.scopeChain) { + if (scope.type === 'local' || scope.type === 'closure') { + const { result } = await Runtime.getProperties({ + objectId: scope.object.objectId, + ownProperties: true, + }); + for (const p of result) { + console.log(` ${scope.type}.${p.name} =`, p.value?.value ?? p.value?.description); + } + } + } + + // Evaluate an expression in the paused frame + const { result } = await Debugger.evaluateOnCallFrame({ + callFrameId: top.callFrameId, + expression: 'typeof state !== "undefined" ? JSON.stringify(state) : "n/a"', + }); + console.log('state =', result.value ?? result.description); + + await Debugger.resume(); + }); + + await Runtime.enable(); + await Debugger.enable(); + + // Set a breakpoint by URL regex + line + await Debugger.setBreakpointByUrl({ + urlRegex: '.*app\\.tsx$', + lineNumber: 119, // 0-indexed + columnNumber: 0, + }); + + await Runtime.runIfWaitingForDebugger(); +})(); +``` + +Run it: + +```bash +node /tmp/cdp-debug.js +``` + +Hermes-specific note: `chrome-remote-interface` is NOT in `ui-tui/package.json`. Install it to a throwaway location if you don't want to dirty the project: + +```bash +mkdir -p /tmp/cdp-tools && cd /tmp/cdp-tools && npm i chrome-remote-interface +NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.js +``` + +## Debugging Hermes ui-tui + +The TUI is built Ink + tsx. Two common scenarios: + +### Debugging a single Ink component under dev + +`ui-tui/package.json` has `npm run dev` (tsx --watch). Add `--inspect-brk` by running tsx directly: + +```bash +cd /home/bb/hermes-agent/ui-tui +npm run build # produce dist/ once so transpile isn't needed on first load +node --inspect-brk dist/entry.js +# In another terminal: +node inspect -p <node pid> +``` + +Then inside `debug>`: + +``` +sb('dist/app.js', 220) # or wherever the suspect render is +cont +``` + +When it pauses, `repl` → inspect `props`, state refs, `useInput` handler values, etc. + +### Debugging a running `hermes --tui` + +The TUI spawns Node from the Python CLI. Easiest path: + +```bash +# 1. Launch TUI +hermes --tui & +TUI_PID=$(pgrep -f 'ui-tui/dist/entry' | head -1) + +# 2. Enable inspector on that Node PID +kill -SIGUSR1 "$TUI_PID" + +# 3. Find the WS URL +curl -s http://127.0.0.1:9229/json/list | jq -r '.[0].webSocketDebuggerUrl' + +# 4. Attach +node inspect ws://127.0.0.1:9229/<uuid> +``` + +Interacting with the TUI (typing in its window) continues to advance execution; your debugger can pause it on a breakpoint at any `sb(...)`. + +### Debugging `_SlashWorker` / PTY child processes + +Those are Python, not Node — use the `python-debugpy` skill for them. Only Node portions (Ink UI, tui_gateway client, tsx-run tests under `ui-tui/`) use this skill. + +## Running Vitest Tests Under the Debugger + +```bash +cd /home/bb/hermes-agent/ui-tui +# Run a single test file paused on entry +node --inspect-brk ./node_modules/vitest/vitest.mjs run --no-file-parallelism src/app/foo.test.tsx +``` + +In another terminal: `node inspect -p <pid>`, then `sb('src/app/foo.tsx', 42)`, `cont`. + +Use `--no-file-parallelism` (vitest) or `--runInBand` (jest) so only one worker exists — debugging a pool is painful. + +## Heap Snapshots & CPU Profiles (Non-interactive) + +From the CDP driver above, swap Debugger for `HeapProfiler` / `Profiler`: + +```javascript +// CPU profile for 5 seconds +await client.Profiler.enable(); +await client.Profiler.start(); +await new Promise(r => setTimeout(r, 5000)); +const { profile } = await client.Profiler.stop(); +require('fs').writeFileSync('/tmp/cpu.cpuprofile', JSON.stringify(profile)); +// Open /tmp/cpu.cpuprofile in Chrome DevTools → Performance tab +``` + +```javascript +// Heap snapshot +await client.HeapProfiler.enable(); +const chunks = []; +client.HeapProfiler.addHeapSnapshotChunk(({ chunk }) => chunks.push(chunk)); +await client.HeapProfiler.takeHeapSnapshot({ reportProgress: false }); +require('fs').writeFileSync('/tmp/heap.heapsnapshot', chunks.join('')); +``` + +## Common Pitfalls + +1. **Wrong line numbers in TS source.** Breakpoints hit the emitted JS, not the `.ts`. Either (a) break in the built `dist/*.js`, or (b) enable sourcemaps (`node --enable-source-maps`) and use `sb('src/app.tsx', N)` — but only with CDP clients that follow sourcemaps. `node inspect` CLI does not. + +2. **`--inspect` vs `--inspect-brk`.** `--inspect` starts the inspector but doesn't pause; your script races past your first breakpoint if you attach too late. Use `--inspect-brk` when you need to set breakpoints before any code runs. + +3. **Port collisions.** Default is `9229`. If multiple Node processes are inspecting, pass `--inspect=0` (random port) and read the actual URL from `/json/list`: + ```bash + curl -s http://127.0.0.1:9229/json/list # lists all inspectable targets on the host + ``` + +4. **Child processes.** `--inspect` on a parent does NOT inspect its children. Use `NODE_OPTIONS='--inspect-brk' node parent.js` to propagate to every child; be aware they all need unique ports (Node auto-increments when `NODE_OPTIONS='--inspect'` is inherited). + +5. **Background kills.** If you `Ctrl+C` out of `node inspect` while the target is paused, the target stays paused. Either `cont` first, or `kill` the target explicitly. + +6. **Running `node inspect` through an agent terminal.** It's a PTY-friendly REPL. In Hermes, launch it with `terminal(pty=true)` or `background=true` + `process(action='submit', data='...')`. Non-PTY foreground mode will work for one-shot commands but not for interactive stepping. + +7. **Security.** `--inspect=0.0.0.0:9229` exposes arbitrary code execution. Always bind to `127.0.0.1` (the default) unless you have an isolated network. + +## Verification Checklist + +After setting up a debug session, verify: + +- [ ] `curl -s http://127.0.0.1:9229/json/list` returns exactly the target you expect +- [ ] First breakpoint actually hits (if it doesn't, you likely missed `--inspect-brk` or attached after execution completed) +- [ ] Source listing at pause shows the right file (mismatch = sourcemap issue, see pitfall 1) +- [ ] `exec process.pid` in `repl` returns the PID you meant to attach to + +## One-Shot Recipes + +**"Why is this variable undefined at line X?"** +```bash +node --inspect-brk script.js & +node inspect -p $! +# debug> +sb('script.js', X) +cont +# paused. Now: +repl +> myVariable +> Object.keys(this) +``` + +**"What's the call path into this function?"** +``` +debug> sb('suspectFn') +debug> cont +# paused on entry +debug> bt +``` + +**"This async chain hangs — where?"** +``` +# Start with --inspect (no -brk), let it run to the hang, then: +debug> pause +debug> bt +# Now you see the stuck frame +``` diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md b/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md index 1f9c6d2aba..7c8a62a033 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-plan.md @@ -1,14 +1,14 @@ --- -title: "Plan — Plan mode for Hermes — inspect context, write a markdown plan into the active workspace's `" +title: "Plan — Plan mode: write markdown plan to" sidebar_label: "Plan" -description: "Plan mode for Hermes — inspect context, write a markdown plan into the active workspace's `" +description: "Plan mode: write markdown plan to" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Plan -Plan mode for Hermes — inspect context, write a markdown plan into the active workspace's `.hermes/plans/` directory, and do not execute the work. +Plan mode: write markdown plan to .hermes/plans/, no exec. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md new file mode 100644 index 0000000000..289991eeff --- /dev/null +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md @@ -0,0 +1,392 @@ +--- +title: "Python Debugpy — Debug Python: pdb REPL + debugpy remote (DAP)" +sidebar_label: "Python Debugpy" +description: "Debug Python: pdb REPL + debugpy remote (DAP)" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Python Debugpy + +Debug Python: pdb REPL + debugpy remote (DAP). + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/software-development/python-debugpy` | +| Version | `1.0.0` | +| Author | Hermes Agent | +| License | MIT | +| Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` | +| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Python Debugger (pdb + debugpy) + +## Overview + +Three tools, picked by situation: + +| Tool | When | +|---|---| +| **`breakpoint()` + pdb** | Local, interactive, simplest. Add `breakpoint()` in the source, run normally, get a REPL at that line. | +| **`python -m pdb`** | Launch an existing script under pdb with no source edits. Useful for quick poking. | +| **`debugpy`** | Remote / headless / "attach to already-running process." Talks DAP, scriptable from terminal, works for long-lived processes (gateway, daemon, PTY children). | + +**Start with `breakpoint()`.** It's the cheapest thing that works. + +## When to Use + +- A test fails and the traceback doesn't reveal why a value is wrong +- You need to step through a function and watch a collection mutate +- A long-running process (hermes gateway, tui_gateway) misbehaves and you can't restart it +- Post-mortem: an exception fired in prod-ish code and you want to inspect locals at the crash site +- A subprocess / child (Python `_SlashWorker`, PTY bridge worker) is the actual bug site + +**Don't use for:** things `print()` / `logging.debug` solve in under a minute, or things `pytest -vv --tb=long --showlocals` already reveals. + +## pdb Quick Reference + +Inside any pdb prompt (`(Pdb)`): + +| Command | Action | +|---|---| +| `h` / `h cmd` | help | +| `n` | next line (step over) | +| `s` | step into | +| `r` | return from current function | +| `c` | continue | +| `unt N` | continue until line N | +| `j N` | jump to line N (same function only) | +| `l` / `ll` | list source around current line / full function | +| `w` | where (stack trace) | +| `u` / `d` | move up / down in the stack | +| `a` | print args of the current function | +| `p expr` / `pp expr` | print / pretty-print expression | +| `display expr` | auto-print expr on every stop | +| `b file:line` | set breakpoint | +| `b func` | break on function entry | +| `b file:line, cond` | conditional breakpoint | +| `cl N` | clear breakpoint N | +| `tbreak file:line` | one-shot breakpoint | +| `!stmt` | execute arbitrary Python (assignments included) | +| `interact` | drop into full Python REPL in current scope (Ctrl+D to exit) | +| `q` | quit | + +The `interact` command is the most powerful — you can import anything, inspect complex objects, even call methods that mutate state. Locals are read-only by default; use `!x = 42` from the `(Pdb)` prompt to mutate. + +## Recipe 1: Local breakpoint + +Easiest. Edit the file: + +```python +def compute(x, y): + result = some_helper(x) + breakpoint() # <-- drops into pdb here + return result + y +``` + +Run the code normally. You land at the `breakpoint()` line with full access to locals. + +**Don't forget to remove `breakpoint()` before committing.** Use `git diff` or a pre-commit grep: +```bash +rg -n 'breakpoint\(\)' --type py +``` + +## Recipe 2: Launch a script under pdb (no source edits) + +```bash +python -m pdb path/to/script.py arg1 arg2 +# Lands at first line of script +(Pdb) b path/to/script.py:42 +(Pdb) c +``` + +## Recipe 3: Debug a pytest test + +The hermes test runner and pytest both support this: + +```bash +# Drop to pdb on failure (or on any raised exception): +scripts/run_tests.sh tests/path/to/test_file.py::test_name --pdb + +# Drop to pdb at the START of the test: +scripts/run_tests.sh tests/path/to/test_file.py::test_name --trace + +# Show locals in tracebacks without pdb: +scripts/run_tests.sh tests/path/to/test_file.py --showlocals --tb=long +``` + +Note: `scripts/run_tests.sh` uses xdist (`-n 4`) by default, and pdb does NOT work under xdist. Add `-p no:xdist` or run a single test with `-n 0`: + +```bash +scripts/run_tests.sh tests/foo_test.py::test_bar --pdb -p no:xdist +# or +source .venv/bin/activate +python -m pytest tests/foo_test.py::test_bar --pdb +``` + +This bypasses the hermetic-env guarantees — fine for debugging, but re-run under the wrapper to confirm before pushing. + +## Recipe 4: Post-mortem on any exception + +```python +import pdb, sys +try: + run_the_thing() +except Exception: + pdb.post_mortem(sys.exc_info()[2]) +``` + +Or wrap a whole script: + +```bash +python -m pdb -c continue script.py +# When it crashes, pdb catches it and you're in the frame of the exception +``` + +Or set a global hook in a repl/jupyter: + +```python +import sys +def excepthook(etype, value, tb): + import pdb; pdb.post_mortem(tb) +sys.excepthook = excepthook +``` + +## Recipe 5: Remote debug with debugpy (attach to running process) + +For long-lived processes: Hermes gateway, tui_gateway, a daemon, a process that's already misbehaving and can't be restarted clean. + +### Setup + +```bash +source /home/bb/hermes-agent/.venv/bin/activate +pip install debugpy +``` + +### Pattern A: Source-edit — process waits for debugger at launch + +Add near the top of the entry point (or inside the function you want to debug): + +```python +import debugpy +debugpy.listen(("127.0.0.1", 5678)) +print("debugpy listening on 5678, waiting for client...", flush=True) +debugpy.wait_for_client() +debugpy.breakpoint() # optional: pause immediately once attached +``` + +Start the process; it blocks on `wait_for_client()`. + +### Pattern B: No source edit — launch with `-m debugpy` + +```bash +python -m debugpy --listen 127.0.0.1:5678 --wait-for-client your_script.py arg1 +``` + +Equivalent for module entry: + +```bash +python -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m your.module +``` + +### Pattern C: Attach to an already-running process + +Needs the PID and debugpy preinstalled in the target's environment: + +```bash +python -m debugpy --listen 127.0.0.1:5678 --pid <pid> +# debugpy injects itself into the process. Then attach a client as below. +``` + +Some kernels/security configs block the ptrace-based injection (`/proc/sys/kernel/yama/ptrace_scope`). Fix with: +```bash +echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope +``` + +### Connecting a client from the terminal + +The easiest terminal-side DAP client is VS Code CLI or a small script. From inside Hermes you have two practical options: + +**Option 1: `debugpy`'s own CLI REPL** — not an official feature, but a tiny DAP client script: + +```python +# /tmp/dap_client.py +import socket, json, itertools, time, sys + +HOST, PORT = "127.0.0.1", 5678 +s = socket.create_connection((HOST, PORT)) +seq = itertools.count(1) + +def send(msg): + msg["seq"] = next(seq) + body = json.dumps(msg).encode() + s.sendall(f"Content-Length: {len(body)}\r\n\r\n".encode() + body) + +def recv(): + header = b"" + while b"\r\n\r\n" not in header: + header += s.recv(1) + length = int(header.decode().split("Content-Length:")[1].split("\r\n")[0].strip()) + body = b"" + while len(body) < length: + body += s.recv(length - len(body)) + return json.loads(body) + +send({"type": "request", "command": "initialize", "arguments": {"adapterID": "python"}}) +print(recv()) +send({"type": "request", "command": "attach", "arguments": {}}) +print(recv()) +send({"type": "request", "command": "setBreakpoints", + "arguments": {"source": {"path": sys.argv[1]}, + "breakpoints": [{"line": int(sys.argv[2])}]}}) +print(recv()) +send({"type": "request", "command": "configurationDone"}) +# ... loop reading events and sending continue/stepIn/etc. +``` + +This is fine for one-off automation but painful as an interactive UX. + +**Option 2: Attach from VS Code / Cursor / Zed** — if the user has one open, they can add a `launch.json`: + +```json +{ + "name": "Attach to Hermes", + "type": "debugpy", + "request": "attach", + "connect": { "host": "127.0.0.1", "port": 5678 }, + "justMyCode": false, + "pathMappings": [ + { "localRoot": "${workspaceFolder}", "remoteRoot": "/home/bb/hermes-agent" } + ] +} +``` + +**Option 3: Ditch DAP, use `remote-pdb`** — usually what you actually want from a terminal agent: + +```bash +pip install remote-pdb +``` + +In your code: +```python +from remote_pdb import set_trace +set_trace(host="127.0.0.1", port=4444) # blocks until connection +``` + +Then from the terminal: +```bash +nc 127.0.0.1 4444 +# You get a (Pdb) prompt exactly as if debugging locally. +``` + +`remote-pdb` is the cleanest agent-friendly choice when `debugpy`'s DAP protocol is overkill. Use `debugpy` only when you actually need IDE integration. + +## Debugging Hermes-specific Processes + +### Tests +See Recipe 3. Always add `-p no:xdist` or run single tests without xdist. + +### `run_agent.py` / CLI — one-shot +Easiest: add `breakpoint()` near the suspect line, then run `hermes` normally. Control returns to your terminal at the pause point. + +### `tui_gateway` subprocess (spawned by `hermes --tui`) +The gateway runs as a child of the Node TUI. Options: + +**A. Source-edit the gateway:** +```python +# tui_gateway/server.py near the top of serve() +import debugpy +debugpy.listen(("127.0.0.1", 5678)) +debugpy.wait_for_client() +``` +Start `hermes --tui`. The TUI will appear frozen (its backend is waiting). Attach a client; execution resumes when you `continue`. + +**B. Use `remote-pdb` at a specific handler:** +```python +from remote_pdb import set_trace +set_trace(host="127.0.0.1", port=4444) # in the RPC handler you want to trap +``` +Trigger the matching slash command from the TUI, then `nc 127.0.0.1 4444` in another terminal. + +### `_SlashWorker` subprocess +Same pattern — `remote-pdb` with `set_trace()` inside the worker's `exec` path. The worker is persistent across slash commands, so the first trigger blocks until you connect; subsequent slash commands pass through normally unless you re-arm. + +### Gateway (`gateway/run.py`) +Long-lived. Use `remote-pdb` at a handler, or `debugpy` with `--wait-for-client` if you're restarting the gateway anyway. + +## Common Pitfalls + +1. **pdb under pytest-xdist silently does nothing.** You won't see the prompt, the test just hangs. Always use `-p no:xdist` or `-n 0`. + +2. **`breakpoint()` in CI / non-TTY contexts hangs the process.** Safe locally; never commit it. Add a pre-commit grep as a safety net. + +3. **`PYTHONBREAKPOINT=0`** disables all `breakpoint()` calls. Check the env if your breakpoint isn't hitting: + ```bash + echo $PYTHONBREAKPOINT + ``` + +4. **`debugpy.listen` blocks only if you also call `wait_for_client()`.** Without it, execution continues and your first breakpoint may fire before the client is attached. + +5. **Attach to PID fails on hardened kernels.** `ptrace_scope=1` (Ubuntu default) allows only same-user ptrace of child processes. Workaround: `echo 0 > /proc/sys/kernel/yama/ptrace_scope` (needs root) or launch under `debugpy` from the start. + +6. **Threads.** `pdb` only debugs the current thread. For multithreaded code, use `debugpy` (thread-aware DAP) or set `threading.settrace()` per thread. + +7. **asyncio.** `pdb` works in coroutines but `await` inside pdb requires Python 3.13+ or `await` from `interact` mode on older versions. For 3.11/3.12, use `asyncio.run_coroutine_threadsafe` tricks or `!stmt`-based awaits via `asyncio.ensure_future`. + +8. **`scripts/run_tests.sh` strips credentials and sets `HOME=<tmpdir>`.** If your bug depends on user config or real API keys, it won't reproduce under the wrapper. Debug with raw `pytest` first to repro, then re-confirm under the wrapper. + +9. **Forking / multiprocessing.** pdb does not follow forks. Each child needs its own `breakpoint()` or `set_trace()`. For Hermes subagents, debug one process at a time. + +## Verification Checklist + +- [ ] After `pip install debugpy`, confirm: `python -c "import debugpy; print(debugpy.__version__)"` +- [ ] For remote debug, confirm the port is actually listening: `ss -tlnp | grep 5678` +- [ ] First breakpoint actually hits (if it doesn't, you likely have `PYTHONBREAKPOINT=0`, you're under xdist, or execution finished before attach) +- [ ] `where` / `w` shows the expected call stack +- [ ] Post-debug cleanup: no stray `breakpoint()` / `set_trace()` in committed code + ```bash + rg -n 'breakpoint\(\)|set_trace\(|debugpy\.listen' --type py + ``` + +## One-Shot Recipes + +**"Why is this dict missing a key?"** +```python +# add above the KeyError site +breakpoint() +# then in pdb: +(Pdb) pp d +(Pdb) pp list(d.keys()) +(Pdb) w # how did we get here +``` + +**"This test passes in isolation but fails in the suite."** +```bash +scripts/run_tests.sh tests/the_test.py --pdb -p no:xdist +# But if it only fails WITH other tests: +source .venv/bin/activate +python -m pytest tests/ -x --pdb -p no:xdist +# Now it pdb-traps at the exact failing test after state accumulated. +``` + +**"My async handler deadlocks."** +```python +# Add at handler entry +import remote_pdb; remote_pdb.set_trace(host="127.0.0.1", port=4444) +``` +Trigger the handler. `nc 127.0.0.1 4444`, then `w` to see the suspended frame, `!import asyncio; asyncio.all_tasks()` to see what else is pending. + +**"Post-mortem on a crash in an Ink child process / subprocess."** +```bash +PYTHONFAULTHANDLER=1 python -m pdb -c continue path/to/entrypoint.py +# On crash, pdb lands at the frame of the exception with full locals +``` diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md index e56aac0258..04f4c2c10c 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-requesting-code-review.md @@ -1,14 +1,14 @@ --- -title: "Requesting Code Review" +title: "Requesting Code Review — Pre-commit review: security scan, quality gates, auto-fix" sidebar_label: "Requesting Code Review" -description: "Pre-commit verification pipeline — static security scan, baseline-aware quality gates, independent reviewer subagent, and auto-fix loop" +description: "Pre-commit review: security scan, quality gates, auto-fix" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Requesting Code Review -Pre-commit verification pipeline — static security scan, baseline-aware quality gates, independent reviewer subagent, and auto-fix loop. Use after code changes and before committing, pushing, or opening a PR. +Pre-commit review: security scan, quality gates, auto-fix. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md new file mode 100644 index 0000000000..f61c7c2213 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-spike.md @@ -0,0 +1,216 @@ +--- +title: "Spike — Throwaway experiments to validate an idea before build" +sidebar_label: "Spike" +description: "Throwaway experiments to validate an idea before build" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Spike + +Throwaway experiments to validate an idea before build. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/software-development/spike` | +| Version | `1.0.0` | +| Author | Hermes Agent (adapted from gsd-build/get-shit-done) | +| License | MIT | +| Tags | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` | +| Related skills | [`sketch`](/docs/user-guide/skills/bundled/creative/creative-sketch), [`writing-plans`](/docs/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Spike + +Use this skill when the user wants to **feel out an idea** before committing to a real build — validating feasibility, comparing approaches, or surfacing unknowns that no amount of research will answer. Spikes are disposable by design. Throw them away once they've paid their debt. + +Load this when the user says things like "let me try this", "I want to see if X works", "spike this out", "before I commit to Y", "quick prototype of Z", "is this even possible?", or "compare A vs B". + +## When NOT to use this + +- The answer is knowable from docs or reading code — just do research, don't build +- The work is production path — use `writing-plans` / `plan` instead +- The idea is already validated — jump straight to implementation + +## If the user has the full GSD system installed + +If `gsd-spike` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), prefer **`gsd-spike`** when the user wants the full GSD workflow: persistent `.planning/spikes/` state, MANIFEST tracking across sessions, Given/When/Then verdict format, and commit patterns that integrate with the rest of GSD. This skill is the lightweight standalone version for users who don't have (or don't want) the full system. + +## Core method + +Regardless of scale, every spike follows this loop: + +``` +decompose → research → build → verdict + ↑__________________________________________↓ + iterate on findings +``` + +### 1. Decompose + +Break the user's idea into **2-5 independent feasibility questions**. Each question is one spike. Present them as a table with Given/When/Then framing: + +| # | Spike | Validates (Given/When/Then) | Risk | +|---|-------|----------------------------|------| +| 001 | websocket-streaming | Given a WS connection, when LLM streams tokens, then client receives chunks < 100ms | High | +| 002a | pdf-parse-pdfjs | Given a multi-page PDF, when parsed with pdfjs, then structured text is extractable | Medium | +| 002b | pdf-parse-camelot | Given a multi-page PDF, when parsed with camelot, then structured text is extractable | Medium | + +**Spike types:** +- **standard** — one approach answering one question +- **comparison** — same question, different approaches (shared number, letter suffix `a`/`b`/`c`) + +**Good spike questions:** specific feasibility with observable output. +**Bad spike questions:** too broad, no observable output, or just "read the docs about X". + +**Order by risk.** The spike most likely to kill the idea runs first. No point prototyping the easy parts if the hard part doesn't work. + +**Skip decomposition** only if the user already knows exactly what they want to spike and says so. Then take their idea as a single spike. + +### 2. Align (for multi-spike ideas) + +Present the spike table. Ask: "Build all in this order, or adjust?" Let the user drop, reorder, or re-frame before you write any code. + +### 3. Research (per spike, before building) + +Spikes are not research-free — you research enough to pick the right approach, then you build. Per spike: + +1. **Brief it.** 2-3 sentences: what this spike is, why it matters, key risk. +2. **Surface competing approaches** if there's real choice: + + | Approach | Tool/Library | Pros | Cons | Status | + |----------|-------------|------|------|--------| + | ... | ... | ... | ... | maintained / abandoned / beta | + +3. **Pick one.** State why. If 2+ are credible, build quick variants within the spike. +4. **Skip research** for pure logic with no external dependencies. + +Use Hermes tools for the research step: + +- `web_search("python websocket streaming libraries 2025")` — find candidates +- `web_extract(urls=["https://websockets.readthedocs.io/..."])` — read the actual docs (returns markdown) +- `terminal("pip show websockets | grep Version")` — check what's installed in the project's venv + +For libraries without docs pages, clone and read their `README.md` / `examples/` via `read_file`. Context7 MCP (if the user has it configured) is also a good source — `mcp_*_resolve-library-id` then `mcp_*_query-docs`. + +### 4. Build + +One directory per spike. Keep it standalone. + +<!-- ascii-guard-ignore --> +``` +spikes/ +├── 001-websocket-streaming/ +│ ├── README.md +│ └── main.py +├── 002a-pdf-parse-pdfjs/ +│ ├── README.md +│ └── parse.js +└── 002b-pdf-parse-camelot/ + ├── README.md + └── parse.py +``` +<!-- ascii-guard-ignore-end --> + +**Bias toward something the user can interact with.** Spikes fail when the only output is a log line that says "it works." The user wants to *feel* the spike working. Default choices, in order of preference: + +1. A runnable CLI that takes input and prints observable output +2. A minimal HTML page that demonstrates the behavior +3. A small web server with one endpoint +4. A unit test that exercises the question with recognizable assertions + +**Depth over speed.** Never declare "it works" after one happy-path run. Test edge cases. Follow surprising findings. The verdict is only trustworthy when the investigation was honest. + +**Avoid** unless the spike specifically requires it: complex package management, build tools/bundlers, Docker, env files, config systems. Hardcode everything — it's a spike. + +**Building one spike** — a typical tool sequence: + +``` +terminal("mkdir -p spikes/001-websocket-streaming") +write_file("spikes/001-websocket-streaming/README.md", "# 001: websocket-streaming\n\n...") +write_file("spikes/001-websocket-streaming/main.py", "...") +terminal("cd spikes/001-websocket-streaming && python3 main.py") +# Observe output, iterate. +``` + +**Parallel comparison spikes (002a / 002b) — delegate.** When two approaches can run in parallel and both need real engineering (not 10-line prototypes), fan out with `delegate_task`: + +``` +delegate_task(tasks=[ + {"goal": "Build 002a-pdf-parse-pdfjs: ...", "toolsets": ["terminal", "file", "web"]}, + {"goal": "Build 002b-pdf-parse-camelot: ...", "toolsets": ["terminal", "file", "web"]}, +]) +``` + +Each subagent returns its own verdict; you write the head-to-head. + +### 5. Verdict + +Each spike's `README.md` closes with: + +```markdown +## Verdict: VALIDATED | PARTIAL | INVALIDATED + +### What worked +- ... + +### What didn't +- ... + +### Surprises +- ... + +### Recommendation for the real build +- ... +``` + +**VALIDATED** = the core question was answered yes, with evidence. +**PARTIAL** = it works under constraints X, Y, Z — document them. +**INVALIDATED** = doesn't work, for this reason. This is a successful spike. + +## Comparison spikes + +When two approaches answer the same question (002a / 002b), build them **back to back**, then do a head-to-head comparison at the end: + +```markdown +## Head-to-head: pdfjs vs camelot + +| Dimension | pdfjs (002a) | camelot (002b) | +|-----------|--------------|----------------| +| Extraction quality | 9/10 structured | 7/10 table-only | +| Setup complexity | npm install, 1 line | pip + ghostscript | +| Perf on 100-page PDF | 3s | 18s | +| Handles rotated text | no | yes | + +**Winner:** pdfjs for our use case. Camelot if we need table-first extraction later. +``` + +## Frontier mode (picking what to spike next) + +If spikes already exist and the user says "what should I spike next?", walk the existing directories and look for: + +- **Integration risks** — two validated spikes that touch the same resource but were tested independently +- **Data handoffs** — spike A's output was assumed compatible with spike B's input; never proven +- **Gaps in the vision** — capabilities assumed but unproven +- **Alternative approaches** — different angles for PARTIAL or INVALIDATED spikes + +Propose 2-4 candidates as Given/When/Then. Let the user pick. + +## Output + +- Create `spikes/` (or `.planning/spikes/` if the user is using GSD conventions) in the repo root +- One dir per spike: `NNN-descriptive-name/` +- `README.md` per spike captures question, approach, results, verdict +- Keep the code throwaway — a spike that takes 2 days to "clean up for production" was a bad spike + +## Attribution + +Adapted from the GSD (Get Shit Done) project's `/gsd-spike` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The full GSD system offers persistent spike state, MANIFEST tracking, and integration with a broader spec-driven development pipeline; install with `npx get-shit-done-cc --hermes --global`. diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development.md b/website/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development.md index 35d8442d54..3e90160547 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development.md @@ -1,14 +1,14 @@ --- -title: "Subagent Driven Development — Use when executing implementation plans with independent tasks" +title: "Subagent Driven Development — Execute plans via delegate_task subagents (2-stage review)" sidebar_label: "Subagent Driven Development" -description: "Use when executing implementation plans with independent tasks" +description: "Execute plans via delegate_task subagents (2-stage review)" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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). +Execute plans via delegate_task subagents (2-stage review). ## Skill metadata @@ -358,3 +358,12 @@ Catch issues early ``` **Quality is not an accident. It's the result of systematic process.** + +## Further reading (load when relevant) + +When the orchestration involves significant context usage, long review loops, or complex validation checkpoints, load these references for the specific discipline: + +- **`references/context-budget-discipline.md`** — Four-tier context degradation model (PEAK / GOOD / DEGRADING / POOR), read-depth rules that scale with context window size, and early warning signs of silent degradation. Load when a run will clearly consume significant context (multi-phase plans, many subagents, large artifacts). +- **`references/gates-taxonomy.md`** — The four canonical gate types (Pre-flight, Revision, Escalation, Abort) with behavior, recovery, and examples. Load when designing or reviewing any workflow that has validation checkpoints — use the vocabulary explicitly so each gate has defined entry, failure behavior, and resumption rules. + +Both references adapted from gsd-build/get-shit-done (MIT © 2025 Lex Christopherson). diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md index bc75d52934..508bce440b 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md @@ -1,14 +1,14 @@ --- -title: "Systematic Debugging — Use when encountering any bug, test failure, or unexpected behavior" +title: "Systematic Debugging — 4-phase root cause debugging: understand bugs before fixing" sidebar_label: "Systematic Debugging" -description: "Use when encountering any bug, test failure, or unexpected behavior" +description: "4-phase root cause debugging: understand bugs before fixing" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Systematic Debugging -Use when encountering any bug, test failure, or unexpected behavior. 4-phase root cause investigation — NO fixes without understanding the problem first. +4-phase root cause debugging: understand bugs before fixing. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md index 93e9b55a08..0ed4480e2b 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-test-driven-development.md @@ -1,14 +1,14 @@ --- -title: "Test Driven Development — Use when implementing any feature or bugfix, before writing implementation code" +title: "Test Driven Development — TDD: enforce RED-GREEN-REFACTOR, tests before code" sidebar_label: "Test Driven Development" -description: "Use when implementing any feature or bugfix, before writing implementation code" +description: "TDD: enforce RED-GREEN-REFACTOR, tests before code" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # Test Driven Development -Use when implementing any feature or bugfix, before writing implementation code. Enforces RED-GREEN-REFACTOR cycle with test-first approach. +TDD: enforce RED-GREEN-REFACTOR, tests before code. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/software-development/software-development-writing-plans.md b/website/docs/user-guide/skills/bundled/software-development/software-development-writing-plans.md index 226f8f2202..3cb448f7ba 100644 --- a/website/docs/user-guide/skills/bundled/software-development/software-development-writing-plans.md +++ b/website/docs/user-guide/skills/bundled/software-development/software-development-writing-plans.md @@ -1,14 +1,14 @@ --- -title: "Writing Plans — Use when you have a spec or requirements for a multi-step task" +title: "Writing Plans — Write implementation plans: bite-sized tasks, paths, code" sidebar_label: "Writing Plans" -description: "Use when you have a spec or requirements for a multi-step task" +description: "Write implementation plans: bite-sized tasks, paths, code" --- {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} # 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. +Write implementation plans: bite-sized tasks, paths, code. ## Skill metadata diff --git a/website/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md b/website/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md new file mode 100644 index 0000000000..122e6b9837 --- /dev/null +++ b/website/docs/user-guide/skills/bundled/yuanbao/yuanbao-yuanbao.md @@ -0,0 +1,124 @@ +--- +title: "Yuanbao — Yuanbao (元宝) groups: @mention users, query info/members" +sidebar_label: "Yuanbao" +description: "Yuanbao (元宝) groups: @mention users, query info/members" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Yuanbao + +Yuanbao (元宝) groups: @mention users, query info/members. + +## Skill metadata + +| | | +|---|---| +| Source | Bundled (installed by default) | +| Path | `skills/yuanbao` | +| Version | `1.0.0` | +| Tags | `yuanbao`, `mention`, `at`, `group`, `members`, `元宝`, `派`, `艾特` | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Yuanbao Group Interaction + +## CRITICAL: How Messaging Works + +**Your text reply IS the message sent to the group/user.** The gateway automatically delivers your response text to the chat. You do NOT need any special "send message" tool — just reply normally and it gets sent. + +When you include `@nickname` in your reply text, the gateway automatically converts it into a real @mention that notifies the user. This is built-in — you have full @mention capability. + +**NEVER say you cannot send messages or @mention users. NEVER suggest the user do it manually. NEVER add disclaimers about permissions. Just reply with the text you want sent.** + +## Available Tools + +| Tool | When to use | +|------|------------| +| `yb_query_group_info` | Query group name, owner, member count | +| `yb_query_group_members` | Find a user, list bots, list all members, or get nickname for @mention | +| `yb_send_dm` | Send a private/direct message (DM / 私信) to a user, with optional media files | + +## @Mention Workflow + +When you need to @mention / 艾特 someone: + +1. Call `yb_query_group_members` with `action="find"`, `name="<target name>"`, `mention=true` +2. Get the exact nickname from the response +3. Include `@nickname` in your reply text — the gateway handles the rest + +Example: user says "帮我艾特元宝" + +Step 1 — tool call: +```json +{ "group_code": "328306697", "action": "find", "name": "元宝", "mention": true } +``` + +Step 2 — your reply (this gets sent to the group with a working @mention): +``` +@元宝 你好，有人找你！ +``` + +**That's it.** No extra explanation needed. Keep it short and natural. + +**Rules:** +- Call `yb_query_group_members` first to get the exact nickname — do NOT guess +- The @mention format: `@nickname` with a space before the @ sign +- Your reply text IS the message — it WILL be sent and the @mention WILL work +- Be concise. Do NOT explain how @mention works to the user. + +## Send DM (Private Message) Workflow + +When someone asks to send a private message / 私信 / DM to a user: + +1. Call `yb_send_dm` with `group_code`, `name` (target user's name), and `message` +2. The tool automatically finds the user and sends the DM +3. Report the result to the user + +Example: user says "给 @用户aea3 私信发一个 hello" + +```json +yb_send_dm({ "group_code": "535168412", "name": "用户aea3", "message": "hello" }) +``` + +Example with media: user says "给 @用户aea3 私信发一张图片" + +```json +yb_send_dm({ + "group_code": "535168412", + "name": "用户aea3", + "message": "Here is the image", + "media_files": [{"path": "/tmp/photo.jpg"}] +}) +``` + +**Rules:** +- Extract `group_code` from the current chat_id (e.g. `group:535168412` → `535168412`) +- If you already know the user_id, pass it directly via the `user_id` parameter to skip lookup +- If multiple users match the name, the tool returns candidates — ask the user to clarify +- Do NOT use `send_message` tool for Yuanbao DMs — use `yb_send_dm` instead +- Supports media: images (.jpg/.png/.gif/.webp/.bmp) sent as image messages, other files as documents + +## Query Group Info + +```json +yb_query_group_info({ "group_code": "328306697" }) +``` + +## Query Members + +| Action | Description | +|--------|-------------| +| `find` | Search by name (partial match, case-insensitive) | +| `list_bots` | List bots and Yuanbao AI assistants | +| `list_all` | List all members | + +## Notes + +- `group_code` comes from chat_id: `group:328306697` → `328306697` +- Groups are called "派 (Pai)" in the Yuanbao app +- Member roles: `user`, `yuanbao_ai`, `bot` diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-hermes-atropos-environments.md b/website/docs/user-guide/skills/optional/mlops/mlops-hermes-atropos-environments.md index 748ee2dbb6..058614b0b4 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-hermes-atropos-environments.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-hermes-atropos-environments.md @@ -34,6 +34,7 @@ Guide for building RL environments in the hermes-agent repo that integrate with ## Architecture Overview +<!-- ascii-guard-ignore --> ``` Atropos BaseEnv (atroposlib/envs/base.py) └── HermesAgentBaseEnv (environments/hermes_base_env.py) @@ -44,6 +45,7 @@ Atropos BaseEnv (atroposlib/envs/base.py) Only implements: setup, get_next_item, format_prompt, compute_reward, evaluate, wandb_log ``` +<!-- ascii-guard-ignore-end --> Hermes environments are special because they run a **multi-turn agent loop with tool calling** — not just single-turn completions. The base env handles the loop; you implement the task and scoring. diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md b/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md index 4c5eef553f..d71f597f1b 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-lambda-labs.md @@ -293,6 +293,7 @@ Filesystems must be attached at instance launch time: ### Best practices +<!-- ascii-guard-ignore --> ```bash # Store on filesystem (persists) /lambda/nfs/storage/ @@ -305,6 +306,7 @@ Filesystems must be attached at instance launch time: /home/ubuntu/ └── working/ # Temporary files ``` +<!-- ascii-guard-ignore-end --> ## SSH configuration diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-slime.md b/website/docs/user-guide/skills/optional/mlops/mlops-slime.md index c86d741379..9ab156dae4 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-slime.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-slime.md @@ -54,6 +54,7 @@ slime is an LLM post-training framework from Tsinghua's THUDM team, powering GLM ## Architecture Overview +<!-- ascii-guard-ignore --> ``` ┌─────────────────────────────────────────────────────────┐ │ Data Buffer │ @@ -69,6 +70,7 @@ slime is an LLM post-training framework from Tsinghua's THUDM team, powering GLM │ - Weight sync to rollout│ │ - Multi-turn support │ └─────────────────────────┘ └─────────────────────────────┘ ``` +<!-- ascii-guard-ignore-end --> ## Installation diff --git a/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md b/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md index 6986499a1b..3e0eba3f90 100644 --- a/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md +++ b/website/docs/user-guide/skills/optional/mlops/mlops-stable-diffusion.md @@ -118,6 +118,7 @@ image = pipe( Diffusers is built around three core components: +<!-- ascii-guard-ignore --> ``` Pipeline (orchestration) ├── Model (neural networks) @@ -126,6 +127,7 @@ Pipeline (orchestration) │ └── Text Encoder (CLIP/T5) └── Scheduler (denoising algorithm) ``` +<!-- ascii-guard-ignore-end --> ### Pipeline inference flow diff --git a/website/docs/user-guide/skills/optional/research/research-parallel-cli.md b/website/docs/user-guide/skills/optional/research/research-parallel-cli.md index d8bcfc28bb..7f796b950e 100644 --- a/website/docs/user-guide/skills/optional/research/research-parallel-cli.md +++ b/website/docs/user-guide/skills/optional/research/research-parallel-cli.md @@ -131,6 +131,7 @@ If auth requires browser interaction, run with `pty=true`. ## Quick reference +<!-- ascii-guard-ignore --> ```text parallel-cli ├── auth @@ -143,6 +144,7 @@ parallel-cli ├── findall run|ingest|status|poll|result|enrich|extend|schema|cancel └── monitor create|list|get|update|delete|events|event-group|simulate ``` +<!-- ascii-guard-ignore-end --> ## Common flags and patterns diff --git a/website/sidebars.ts b/website/sidebars.ts index 6f43cdb272..4cd17c1ea5 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -137,13 +137,18 @@ const sidebars: SidebarsConfig = { 'user-guide/skills/bundled/creative/creative-ascii-video', 'user-guide/skills/bundled/creative/creative-baoyu-comic', 'user-guide/skills/bundled/creative/creative-baoyu-infographic', + 'user-guide/skills/bundled/creative/creative-claude-design', + 'user-guide/skills/bundled/creative/creative-comfyui', 'user-guide/skills/bundled/creative/creative-creative-ideation', 'user-guide/skills/bundled/creative/creative-design-md', 'user-guide/skills/bundled/creative/creative-excalidraw', + 'user-guide/skills/bundled/creative/creative-humanizer', 'user-guide/skills/bundled/creative/creative-manim-video', 'user-guide/skills/bundled/creative/creative-p5js', 'user-guide/skills/bundled/creative/creative-pixel-art', 'user-guide/skills/bundled/creative/creative-popular-web-designs', + 'user-guide/skills/bundled/creative/creative-pretext', + 'user-guide/skills/bundled/creative/creative-sketch', 'user-guide/skills/bundled/creative/creative-songwriting-and-ai-music', 'user-guide/skills/bundled/creative/creative-touchdesigner-mcp', ], @@ -255,6 +260,7 @@ const sidebars: SidebarsConfig = { label: 'productivity', collapsed: true, items: [ + 'user-guide/skills/bundled/productivity/productivity-airtable', 'user-guide/skills/bundled/productivity/productivity-google-workspace', 'user-guide/skills/bundled/productivity/productivity-linear', 'user-guide/skills/bundled/productivity/productivity-maps', @@ -305,13 +311,26 @@ const sidebars: SidebarsConfig = { label: 'software-development', collapsed: true, items: [ + 'user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands', + 'user-guide/skills/bundled/software-development/software-development-hermes-agent-skill-authoring', + 'user-guide/skills/bundled/software-development/software-development-node-inspect-debugger', 'user-guide/skills/bundled/software-development/software-development-plan', + 'user-guide/skills/bundled/software-development/software-development-python-debugpy', 'user-guide/skills/bundled/software-development/software-development-requesting-code-review', + 'user-guide/skills/bundled/software-development/software-development-spike', 'user-guide/skills/bundled/software-development/software-development-subagent-driven-development', 'user-guide/skills/bundled/software-development/software-development-systematic-debugging', 'user-guide/skills/bundled/software-development/software-development-test-driven-development', 'user-guide/skills/bundled/software-development/software-development-writing-plans', ], + }, + { + type: 'category', + label: 'yuanbao', + collapsed: true, + items: [ + 'user-guide/skills/bundled/yuanbao/yuanbao-yuanbao', + ], }, ], },