Timmy_Foundation/hermes-agent
16
0
Fork 0
Code Issues 55 Pull Requests 1 Actions 46 Packages Projects Releases Wiki Activity

docs: fix stale and incorrect documentation across 18 files

Browse Source 
Cross-referenced all 84 docs pages against the actual codebase and
corrected every discrepancy found.

Reference docs:
- faq.md: Fix non-existent commands (/stats→/usage, /context→/usage,
  hermes models→hermes model, hermes config get→hermes config show,
  hermes gateway logs→cat gateway.log, async→sync chat() call)
- cli-commands.md: Fix --provider choices list (remove providers not
  in argparse), add undocumented -s/--skills flag
- slash-commands.md: Add missing /queue and /resume commands, fix
  /approve args_hint to show [session|always]
- tools-reference.md: Remove duplicate vision and web toolset sections
- environment-variables.md: Fix HERMES_INFERENCE_PROVIDER list (add
  copilot-acp, remove alibaba to match actual argparse choices)

Configuration & user guide:
- configuration.md: Fix approval_mode→approvals.mode (manual not ask),
  checkpoints.enabled default true not false, human_delay defaults
  (500/2000→800/2500), remove non-existent delegation.max_iterations
  and delegation.default_toolsets, fix website_blocklist nesting
  under security:, add .hermes.md and CLAUDE.md to context files
  table with priority system explanation
- security.md: Fix website_blocklist nesting under security:
- context-files.md: Add .hermes.md/HERMES.md and CLAUDE.md support,
  document priority-based first-match-wins loading behavior
- cli.md: Fix personalities config nesting (top-level, not under agent:)
- delegation.md: Fix model override docs (config-level, not per-call
  tool parameter)
- rl-training.md: Fix log directory (tinker-atropos/logs/→
  ~/.hermes/logs/rl_training/)
- tts.md: Fix Discord delivery format (voice bubble with fallback,
  not just file attachment)
- git-worktrees.md: Remove outdated v0.2.0 version reference

Developer guide:
- prompt-assembly.md: Add .hermes.md, CLAUDE.md, document priority
  system for context files
- agent-loop.md: Fix callback list (remove non-existent
  message_callback, add stream_delta_callback, tool_gen_callback,
  status_callback)

Messaging & guides:
- webhooks.md: Fix command (hermes setup gateway→hermes gateway setup)
- tips.md: Fix session idle timeout (120min→24h), config file
  (gateway.json→config.yaml)
- build-a-hermes-plugin.md: Fix plugin.yaml provides: format
  (provides_tools/provides_hooks as lists), note register_command()
  as not yet implemented
This commit is contained in:
Teknium
2026-03-24 07:53:07 -07:00
committed by GitHub
parent 02b38b93cb
commit ee3f3e756d
18 changed files with 86 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
website/docs/developer-guide/agent-loop.md
View File

@@ -75,7 +75,9 @@ Concurrent tool execution preserves message/result ordering when reinserting too
- `reasoning_callback`
- `clarify_callback`
- `step_callback`
- `message_callback`
- `stream_delta_callback`
- `tool_gen_callback`
- `status_callback`
These are how the CLI, gateway, and ACP integrations stream intermediate progress and interactive approval/clarification flows.

9
website/docs/developer-guide/prompt-assembly.md
View File

@@ -58,11 +58,12 @@ Local memory and user profile data are injected as frozen snapshots at session s
## Context files
`agent/prompt_builder.py` scans and sanitizes:
`agent/prompt_builder.py` scans and sanitizes project context files using a **priority system** — only one type is loaded (first match wins):
- `AGENTS.md`
- `.cursorrules`
- `.cursor/rules/*.mdc`
1. `.hermes.md` / `HERMES.md` (walks to git root)
2. `AGENTS.md` (recursive directory walk)
3. `CLAUDE.md` (CWD only)
4. `.cursorrules` / `.cursor/rules/*.mdc` (CWD only)
`SOUL.md` is loaded separately via `load_soul_md()` for the identity slot. When it loads successfully, `build_context_files_prompt(skip_soul=True)` prevents it from appearing twice.

12
website/docs/guides/build-a-hermes-plugin.md
View File

@@ -29,12 +29,14 @@ Create `plugin.yaml`:
name: calculator
version: 1.0.0
description: Math calculator — evaluate expressions and convert units
provides:
tools: true
hooks: true
provides_tools:
- calculate
- unit_convert
provides_hooks:
- post_tool_call
```
This tells Hermes: "I'm a plugin called calculator, I provide tools and hooks." That's all the manifest needs.
This tells Hermes: "I'm a plugin called calculator, I provide tools and hooks." The `provides_tools` and `provides_hooks` fields are lists of what the plugin registers.
Optional fields you could add:
```yaml
@@ -232,7 +234,7 @@ def register(ctx):
- Called exactly once at startup
- `ctx.register_tool()` puts your tool in the registry — the model sees it immediately
- `ctx.register_hook()` subscribes to lifecycle events
- `ctx.register_command()` adds a slash command to `/help`, autocomplete, and gateway dispatch
- `ctx.register_command()` — _planned but not yet implemented_
- If this function crashes, the plugin is disabled but Hermes continues fine
## Step 6: Test it

2
website/docs/guides/tips.md
View File

@@ -170,7 +170,7 @@ Instead of manually collecting user IDs for allowlists, enable DM pairing. When
Use `/verbose` to control how much tool activity you see. In messaging platforms, less is usually more — keep it on "new" to see just new tool calls. In the CLI, "all" gives you a satisfying live view of everything the agent does.
:::tip
On messaging platforms, sessions auto-reset after idle time (default: 120 min) or daily at 4 AM. Adjust per-platform in `~/.hermes/gateway.json` if you need longer sessions.
On messaging platforms, sessions auto-reset after idle time (default: 24 hours) or daily at 4 AM. Adjust per-platform in `~/.hermes/config.yaml` if you need longer sessions.
:::
## Security

3
website/docs/reference/cli-commands.md
View File

@@ -66,7 +66,8 @@ Common options:
| `-q`, `--query "..."` | One-shot, non-interactive prompt. |
| `-m`, `--model <model>` | Override the model for this run. |
| `-t`, `--toolsets <csv>` | Enable a comma-separated set of toolsets. |
| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `opencode-zen`, `opencode-go`, `ai-gateway`, `kilocode`, `alibaba`. |
| `--provider <provider>` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`. |
| `-s`, `--skills <name>` | Preload one or more skills for the session (can be repeated or comma-separated). |
| `-v`, `--verbose` | Verbose output. |
| `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. |
| `--resume <session>` / `--continue [name]` | Resume a session directly from `chat`. |

2
website/docs/reference/environment-variables.md
View File

@@ -61,7 +61,7 @@ For native Anthropic auth, Hermes prefers Claude Code's own credential files whe
| Variable | Description |
|----------|-------------|
| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`, `alibaba` (default: `auto`) |
| `HERMES_INFERENCE_PROVIDER` | Override provider selection: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot`, `copilot-acp`, `anthropic`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode` (default: `auto`) |
| `HERMES_PORTAL_BASE_URL` | Override Nous Portal URL (for development/testing) |
| `NOUS_INFERENCE_BASE_URL` | Override Nous inference API URL |
| `HERMES_NOUS_MIN_KEY_TTL_SECONDS` | Min agent key TTL before re-mint (default: 1800 = 30min) |

21
website/docs/reference/faq.md
View File

@@ -93,7 +93,7 @@ Yes. Import the `AIAgent` class and use Hermes programmatically:
from hermes.agent import AIAgent
agent = AIAgent(model="openrouter/nous/hermes-3-llama-3.1-70b")
response = await agent.chat("Explain quantum computing briefly")
response = agent.chat("Explain quantum computing briefly")
```
See the [Python Library guide](../user-guide/features/code-execution.md) for full API usage.
@@ -175,8 +175,8 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri
**Solution:**
```bash
# Check which keys are set
hermes config get OPENROUTER_API_KEY
# Check your configuration
hermes config show
# Re-configure your provider
hermes model
@@ -196,7 +196,7 @@ Make sure the key matches the provider. An OpenAI key won't work with OpenRouter
**Solution:**
```bash
# List available models for your provider
hermes models
hermes model
# Set a valid model
hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b
@@ -232,10 +232,7 @@ hermes chat --model openrouter/google/gemini-2.0-flash-001
If this happens on the first long conversation, Hermes may have the wrong context length for your model. Check what it detected:
```bash
# Look at the status bar — it shows the detected context length
/context
```
Look at the CLI startup line — it shows the detected context length (e.g., `📊 Context limit: 128000 tokens`). You can also check with `/usage` during a session.
To fix context detection, set it explicitly:
@@ -318,7 +315,7 @@ hermes gateway status
hermes gateway start
# Check logs for errors
hermes gateway logs
cat ~/.hermes/logs/gateway.log | tail -50
```
#### Messages not delivering
@@ -327,7 +324,7 @@ hermes gateway logs
**Solution:**
- Verify your bot token is valid with `hermes gateway setup`
- Check gateway logs: `hermes gateway logs`
- Check gateway logs: `cat ~/.hermes/logs/gateway.log | tail -50`
- For webhook-based platforms (Slack, WhatsApp), ensure your server is publicly accessible
#### Allowlist confusion — who can talk to the bot?
@@ -383,8 +380,8 @@ hermes config show
# Compress the conversation to reduce tokens
/compress
# Check session token count
/stats
# Check session token usage
/usage
```
:::tip

4
website/docs/reference/slash-commands.md
View File

@@ -31,6 +31,8 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
| `/compress` | Manually compress conversation context (flush memories + summarize) |
| `/rollback` | List or restore filesystem checkpoints (usage: /rollback [number]) |
| `/stop` | Kill all running background processes |
| `/queue <prompt>` (alias: `/q`) | Queue a prompt for the next turn (doesn't interrupt the current agent response) |
| `/resume [name]` | Resume a previously-named session |
| `/statusbar` (alias: `/sb`) | Toggle the context/model status bar on or off |
| `/background <prompt>` | 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). |
| `/plan [request]` | Load the bundled `plan` skill to write a markdown plan instead of executing the work. Plans are saved under `.hermes/plans/` relative to the active workspace/backend working directory. |
@@ -115,7 +117,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
| `/background <prompt>` | 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). |
| `/plan [request]` | Load the bundled `plan` skill to write a markdown plan instead of executing the work. Plans are saved under `.hermes/plans/` relative to the active workspace/backend working directory. |
| `/reload-mcp` | Reload MCP servers from config. |
| `/approve` | Approve and execute a pending dangerous command (terminal commands flagged for review). |
| `/approve [session\|always]` | Approve and execute a pending dangerous command. `session` approves for this session only; `always` adds to permanent allowlist. |
| `/deny` | Reject a pending dangerous command. |
| `/update` | Update Hermes Agent to the latest version. |
| `/help` | Show messaging help. |

11
website/docs/reference/tools-reference.md
View File

@@ -160,15 +160,4 @@ This page documents the built-in Hermes tool registry as it exists in code. Avai
|------|-------------|----------------------|
| `text_to_speech` | Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider… | — |
## `vision` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `vision_analyze` | Analyze images using AI vision. Provides a comprehensive description and answers a specific question about the image content. | — |
## `web` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `web_extract` | Extract content from web page URLs. Returns page content in markdown format. Also works with PDF URLs (arxiv papers, documents, etc.) — pass the PDF link directly and it converts to markdown text. Pages under 5000 chars return full markdow… | FIRECRAWL_API_KEY |
| `web_search` | Search the web for information on any topic. Returns up to 5 relevant results with titles, URLs, and descriptions. | FIRECRAWL_API_KEY |

11
website/docs/user-guide/cli.md
View File

@@ -179,12 +179,11 @@ Built-in personalities include: `helpful`, `concise`, `technical`, `creative`, `
You can also define custom personalities in `~/.hermes/config.yaml`:
```yaml
agent:
personalities:
helpful: "You are a helpful, friendly AI assistant."
kawaii: "You are a kawaii assistant! Use cute expressions..."
pirate: "Arrr! Ye be talkin' to Captain Hermes..."
# Add your own!
personalities:
helpful: "You are a helpful, friendly AI assistant."
kawaii: "You are a kawaii assistant! Use cute expressions..."
pirate: "Arrr! Ye be talkin' to Captain Hermes..."
# Add your own!
```
## Multi-line Input

44
website/docs/user-guide/configuration.md
View File

@@ -1336,8 +1336,8 @@ Simulate human-like response pacing in messaging platforms:
```yaml
human_delay:
mode: "off" # off | natural | custom
min_ms: 500 # Minimum delay (custom mode)
max_ms: 2000 # Maximum delay (custom mode)
min_ms: 800 # Minimum delay (custom mode)
max_ms: 2500 # Maximum delay (custom mode)
```
## Code Execution
@@ -1367,14 +1367,15 @@ The browser toolset supports multiple providers. See the [Browser feature page](
Block specific domains from being accessed by the agent's web and browser tools:
```yaml
website_blocklist:
enabled: false # Enable URL blocking (default: false)
domains: # List of blocked domain patterns
- "*.internal.company.com"
- "admin.example.com"
- "*.local"
shared_files: # Load additional rules from external files
- "/etc/hermes/blocked-sites.txt"
security:
website_blocklist:
enabled: false # Enable URL blocking (default: false)
domains: # List of blocked domain patterns
- "*.internal.company.com"
- "admin.example.com"
- "*.local"
shared_files: # Load additional rules from external files
- "/etc/hermes/blocked-sites.txt"
```
When enabled, any URL matching a blocked domain pattern is rejected before the web or browser tool executes. This applies to `web_search`, `web_extract`, `browser_navigate`, and any tool that accesses URLs.
@@ -1393,19 +1394,20 @@ The policy is cached for 30 seconds, so config changes take effect quickly witho
Control how Hermes handles potentially dangerous commands:
```yaml
approval_mode: ask # ask | smart | off
approvals:
mode: manual # manual | smart | off
```
| Mode | Behavior |
|------|----------|
| `ask` (default) | Prompt the user before executing any flagged command. In the CLI, shows an interactive approval dialog. In messaging, queues a pending approval request. |
| `manual` (default) | Prompt the user before executing any flagged command. In the CLI, shows an interactive approval dialog. In messaging, queues a pending approval request. |
| `smart` | Use an auxiliary LLM to assess whether a flagged command is actually dangerous. Low-risk commands are auto-approved with session-level persistence. Genuinely risky commands are escalated to the user. |
| `off` | Skip all approval checks. Equivalent to `HERMES_YOLO_MODE=true`. **Use with caution.** |
Smart mode is particularly useful for reducing approval fatigue — it lets the agent work more autonomously on safe operations while still catching genuinely destructive commands.
:::warning
Setting `approval_mode: off` disables all safety checks for terminal commands. Only use this in trusted, sandboxed environments.
Setting `approvals.mode: off` disables all safety checks for terminal commands. Only use this in trusted, sandboxed environments.
:::
## Checkpoints
@@ -1414,7 +1416,7 @@ Automatic filesystem snapshots before destructive file operations. See the [Chec
```yaml
checkpoints:
enabled: false # Enable automatic checkpoints (also: hermes --checkpoints)
enabled: true # Enable automatic checkpoints (also: hermes --checkpoints)
max_snapshots: 50 # Max checkpoints to keep per directory
```
@@ -1425,11 +1427,6 @@ Configure subagent behavior for the delegate tool:
```yaml
delegation:
max_iterations: 50 # Max iterations per subagent
default_toolsets: # Toolsets available to subagents
- terminal
- file
- web
# model: "google/gemini-3-flash-preview" # Override model (empty = inherit parent)
# provider: "openrouter" # Override provider (empty = inherit parent)
# base_url: "http://localhost:1234/v1" # Direct OpenAI-compatible endpoint (takes precedence over provider)
@@ -1460,12 +1457,15 @@ Hermes uses two different context scopes:
| File | Purpose | Scope |
|------|---------|-------|
| `SOUL.md` | **Primary agent identity** — defines who the agent is (slot #1 in the system prompt) | `~/.hermes/SOUL.md` or `$HERMES_HOME/SOUL.md` |
| `AGENTS.md` | Project-specific instructions, coding conventions | Working directory / project tree |
| `.cursorrules` | Cursor IDE rules (also detected) | Working directory |
| `.cursor/rules/*.mdc` | Cursor rule files (also detected) | Working directory |
| `.hermes.md` / `HERMES.md` | Project-specific instructions (highest priority) | Walks to git root |
| `AGENTS.md` | Project-specific instructions, coding conventions | Recursive directory walk |
| `CLAUDE.md` | Claude Code context files (also detected) | Working directory only |
| `.cursorrules` | Cursor IDE rules (also detected) | Working directory only |
| `.cursor/rules/*.mdc` | Cursor rule files (also detected) | Working directory only |
- **SOUL.md** is the agent's primary identity. It occupies slot #1 in the system prompt, completely replacing the built-in default identity. Edit it to fully customize who the agent is.
- If SOUL.md is missing, empty, or cannot be loaded, Hermes falls back to a built-in default identity.
- **Project context files use a priority system** — only ONE type is loaded (first match wins): `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. SOUL.md is always loaded independently.
- **AGENTS.md** is hierarchical: if subdirectories also have AGENTS.md, all are combined.
- Hermes automatically seeds a default `SOUL.md` if one does not already exist.
- All loaded context files are capped at 20,000 characters with smart truncation.

12
website/docs/user-guide/features/context-files.md
View File

@@ -1,7 +1,7 @@
---
sidebar_position: 8
title: "Context Files"
description: "Project context files — AGENTS.md, global SOUL.md, and .cursorrules — automatically injected into every conversation"
description: "Project context files — .hermes.md, AGENTS.md, CLAUDE.md, global SOUL.md, and .cursorrules — automatically injected into every conversation"
---
# Context Files
@@ -11,12 +11,18 @@ Hermes Agent automatically discovers and loads context files that shape how it b
## Supported Context Files
| File | Purpose | Discovery |
|------|---------|-----------|
|------|---------|-----------|
| **.hermes.md** / **HERMES.md** | Project instructions (highest priority) | Walks to git root |
| **AGENTS.md** | Project instructions, conventions, architecture | Recursive (walks subdirectories) |
| **CLAUDE.md** | Claude Code context files (also detected) | CWD only |
| **SOUL.md** | Global personality and tone customization for this Hermes instance | `HERMES_HOME/SOUL.md` only |
| **.cursorrules** | Cursor IDE coding conventions | CWD only |
| **.cursor/rules/*.mdc** | Cursor IDE rule modules | CWD only |
:::info Priority system
Only **one** project context type is loaded per session (first match wins): `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. **SOUL.md** is always loaded independently as the agent identity (slot #1).
:::
## AGENTS.md
`AGENTS.md` is the primary project context file. It tells the agent how your project is structured, what conventions to follow, and any special instructions.
@@ -86,7 +92,7 @@ Important details:
## .cursorrules
Hermes is compatible with Cursor IDE's `.cursorrules` file and `.cursor/rules/*.mdc` rule modules. If these files exist in your project root, they're loaded alongside AGENTS.md.
Hermes is compatible with Cursor IDE's `.cursorrules` file and `.cursor/rules/*.mdc` rule modules. If these files exist in your project root and no higher-priority context file (`.hermes.md`, `AGENTS.md`, or `CLAUDE.md`) is found, they're loaded as the project context.
This means your existing Cursor conventions automatically apply when using Hermes.

14
website/docs/user-guide/features/delegation.md
View File

@@ -131,15 +131,13 @@ Single-task delegation runs directly without thread pool overhead.
## Model Override
You can use a different model for subagents — useful for delegating simple tasks to cheaper/faster models:
You can configure a different model for subagents via `config.yaml` — useful for delegating simple tasks to cheaper/faster models:
```python
delegate_task(
goal="Summarize this README file",
context="File at /project/README.md",
toolsets=["file"],
model="google/gemini-flash-2.0" # Cheaper model for simple tasks
)
```yaml
# In ~/.hermes/config.yaml
delegation:
model: "google/gemini-flash-2.0" # Cheaper model for subagents
provider: "openrouter" # Optional: route subagents to a different provider
```
If omitted, subagents use the same model as the parent.

2
website/docs/user-guide/features/rl-training.md
View File

@@ -219,7 +219,7 @@ Training runs log to Weights & Biases with these key metrics:
## Log Files
Each training run generates log files in `tinker-atropos/logs/`:
Each training run generates log files in `~/.hermes/logs/rl_training/`:
```
logs/

2
website/docs/user-guide/features/tts.md
View File

@@ -24,7 +24,7 @@ Convert text to speech with four providers:
| Platform | Delivery | Format |
|----------|----------|--------|
| Telegram | Voice bubble (plays inline) | Opus `.ogg` |
| Discord | Audio file attachment | MP3 |
| Discord | Voice bubble (Opus/OGG), falls back to file attachment | Opus/MP3 |
| WhatsApp | Audio file attachment | MP3 |
| CLI | Saved to `~/.hermes/audio_cache/` | MP3 |

2
website/docs/user-guide/git-worktrees.md
View File

@@ -169,5 +169,5 @@ This combination gives you:
- Strong guarantees that different agents and experiments do not step on each other.
- Fast iteration cycles with easy recovery from bad edits.
- Clean, reviewable pull requests targeted at v0.2.0’s new capabilities.
- Clean, reviewable pull requests.

4
website/docs/user-guide/messaging/webhooks.md
View File

@@ -14,7 +14,7 @@ The agent processes the event and can respond by posting comments on PRs, sendin
## Quick Start
1. Enable via `hermes setup gateway` or environment variables
1. Enable via `hermes gateway setup` or environment variables
2. Define webhook routes in `config.yaml`
3. Point your service at `http://your-server:8644/webhooks/<route-name>`
@@ -27,7 +27,7 @@ There are two ways to enable the webhook adapter.
### Via setup wizard
```bash
hermes setup gateway
hermes gateway setup
```
Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.

15
website/docs/user-guide/security.md
View File

@@ -296,13 +296,14 @@ You can restrict which websites the agent can access through its web and browser
```yaml
# In ~/.hermes/config.yaml
website_blocklist:
enabled: true
domains:
- "*.internal.company.com"
- "admin.example.com"
shared_files:
- "/etc/hermes/blocked-sites.txt"
security:
website_blocklist:
enabled: true
domains:
- "*.internal.company.com"
- "admin.example.com"
shared_files:
- "/etc/hermes/blocked-sites.txt"
```
When a blocked URL is requested, the tool returns an error explaining the domain is blocked by policy. The blocklist is enforced across `web_search`, `web_extract`, `browser_navigate`, and all URL-capable tools.