Timmy_Foundation/hermes-agent
15
0
Fork 0
Code Issues 41 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: comprehensive accuracy audit fixes (35+ corrections)

Browse Source 
CRITICAL fixes:
- Installation: Remove false prerequisites (installer auto-installs everything except git)
- Tools: Remove non-existent 'web_crawl' tool from tools table
- Memory: Remove non-existent 'read' action (only add/replace/remove exist)
- Code execution: Fix 'search' to 'search_files' in sandbox tools list
- CLI commands: Fix --model/--provider/--toolsets/--verbose as chat subcommand flags

IMPORTANT fixes:
- Installation: Add missing installer features (Node.js, ripgrep, ffmpeg, skills seeding)
- Installation: Add 6 missing package extras to table (mcp, honcho, tts-premium, etc)
- Installation: Fix mkdir to include all directories the installer creates
- Quickstart: Add OpenAI Codex to provider table
- CLI: Fix all 'hermes --flag' to 'hermes chat --flag' across all docs
- Configuration: Remove non-existent --max-turns CLI flag
- Tools: Fix 'search' to 'search_files', add missing 'process' tool
- Skills: Remove skills_categories() (not a registered tool)
- Cron: Remove unsupported 'daily at 9am' schedule format
- TTS: Fix output directory to ~/.hermes/audio_cache/
- Delegation: Clarify depth limit wording
- Architecture: Fix default model, chat() signature, file names
- Contributing: Fix Python requirement from 3.11+ to 3.10+
- CLI reference: Add missing commands (login, tools, sessions subcommands)
- Env vars: Fix TERMINAL_DOCKER_IMAGE default, add HERMES_MODEL
This commit is contained in:
teknium1
2026-03-05 06:50:22 -08:00
parent f2624a1426
commit d578d06f59
16 changed files with 76 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
website/docs/developer-guide/architecture.md
View File

@@ -50,7 +50,8 @@ hermes-agent/
│ ├── code_execution_tool.py # Sandboxed Python with RPC tool access
│ ├── session_search_tool.py # Search past conversations
│ ├── cronjob_tools.py # Scheduled task management
│ ├── skill_tools.py # Skill search, load, manage
│ ├── skills_tool.py # Skill search and load
│ ├── skill_manager_tool.py # Skill management
│ └── environments/ # Terminal execution backends
│ ├── base.py # BaseEnvironment ABC
│ ├── local.py, docker.py, ssh.py, singularity.py, modal.py
@@ -114,7 +115,7 @@ while turns < max_turns:
class AIAgent:
def __init__(
self,
model: str = "anthropic/claude-sonnet-4",
model: str = "anthropic/claude-opus-4.6",
api_key: str = None,
base_url: str = "https://openrouter.ai/api/v1",
max_iterations: int = 60,
@@ -126,7 +127,7 @@ class AIAgent:
):
...
def chat(self, user_message: str, task_id: str = None) -> str:
def chat(self, message: str) -> str:
# Main entry point - runs the agent loop
...
```

2
website/docs/developer-guide/contributing.md
View File

@@ -27,7 +27,7 @@ We value contributions in this order:
| Requirement | Notes |
|-------------|-------|
| **Git** | With `--recurse-submodules` support |
| **Python 3.11+** | uv will install it if missing |
| **Python 3.10+** | uv will install it if missing |
| **uv** | Fast Python package manager ([install](https://docs.astral.sh/uv/)) |
| **Node.js 18+** | Optional — needed for browser tools and WhatsApp bridge |

2
website/docs/developer-guide/creating-skills.md
View File

@@ -95,7 +95,7 @@ For XML/JSON parsing or complex logic, include helper scripts in `scripts/` —
Run the skill and verify the agent follows the instructions correctly:
```bash
hermes --toolsets skills -q "Use the X skill to do Y"
hermes chat --toolsets skills -q "Use the X skill to do Y"
```
## Should the Skill Be Bundled?

56
website/docs/getting-started/installation.md
View File

@@ -26,9 +26,15 @@ The installer handles everything automatically:
- Installs [uv](https://docs.astral.sh/uv/) (fast Python package manager) if not present
- Installs Python 3.11 via uv if not already available (no sudo needed)
- Installs Node.js v22 if not present (needed for browser automation and WhatsApp bridge)
- Installs ripgrep if not present (fast file search)
- Installs ffmpeg if not present (audio format conversion for TTS)
- Clones to `~/.hermes/hermes-agent` (with submodules: mini-swe-agent, tinker-atropos)
- Creates a virtual environment with Python 3.11
- Installs all dependencies and submodule packages
- Installs WhatsApp bridge npm dependencies
- Seeds bundled skills into `~/.hermes/skills/`
- Creates a default `SOUL.md` personality file
- Sets up the `hermes` command globally (no venv activation needed)
- Runs the interactive setup wizard
@@ -46,38 +52,18 @@ hermes # Start chatting!
## Prerequisites
| Requirement | Minimum Version | Check Command | Notes |
|-------------|----------------|---------------|-------|
| **Git** | Any recent | `git --version` | Required |
| **Node.js** | 18+ | `node --version` | Optional — needed for browser automation and WhatsApp bridge |
| **ripgrep** | Any | `rg --version` | Optional — faster file search (falls back to grep) |
The only prerequisite is **Git**. The installer automatically handles everything else:
- **uv** (fast Python package manager)
- **Python 3.11** (via uv, no sudo needed)
- **Node.js v22** (for browser automation and WhatsApp bridge)
- **ripgrep** (fast file search)
- **ffmpeg** (audio format conversion for TTS)
:::info
Python and pip are **not** prerequisites. The installer uses [uv](https://docs.astral.sh/uv/) to provision Python 3.11 automatically (no sudo needed). If you already have Python 3.11+ installed, uv will use it.
You do **not** need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure `git` is available (`git --version`).
:::
<details>
<summary><strong>Installing prerequisites by platform</strong></summary>
**Ubuntu / Debian:**
```bash
sudo apt update && sudo apt install git
# Optional:
sudo apt install ripgrep nodejs npm
```
**macOS (Homebrew):**
```bash
brew install git
# Optional:
brew install ripgrep node
```
**Windows:**
Native Windows is not supported. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and follow the Ubuntu/Debian instructions above.
</details>
---
## Manual Installation
@@ -137,6 +123,12 @@ uv pip install -e "."
| `cron` | Cron expression parsing for scheduled tasks | `uv pip install -e ".[cron]"` |
| `cli` | Terminal menu UI for setup wizard | `uv pip install -e ".[cli]"` |
| `modal` | Modal cloud execution backend | `uv pip install -e ".[modal]"` |
| `tts-premium` | ElevenLabs premium voices | `uv pip install -e ".[tts-premium]"` |
| `pty` | PTY terminal support | `uv pip install -e ".[pty]"` |
| `honcho` | AI-native memory (Honcho integration) | `uv pip install -e ".[honcho]"` |
| `mcp` | Model Context Protocol support | `uv pip install -e ".[mcp]"` |
| `homeassistant` | Home Assistant integration | `uv pip install -e ".[homeassistant]"` |
| `slack` | Slack messaging | `uv pip install -e ".[slack]"` |
| `dev` | pytest & test utilities | `uv pip install -e ".[dev]"` |
You can combine extras: `uv pip install -e ".[messaging,cron]"`
@@ -157,7 +149,7 @@ Both are optional — if you skip them, the corresponding toolsets simply won't
### Step 5: Install Node.js Dependencies (Optional)
Only needed for **browser automation** (Browserbase-powered):
Only needed for **browser automation** (Browserbase-powered) and **WhatsApp bridge**:
```bash
npm install
@@ -167,7 +159,7 @@ npm install
```bash
# Create the directory structure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
# Copy the example config file
cp cli-config.yaml.example ~/.hermes/config.yaml
@@ -251,10 +243,10 @@ export VIRTUAL_ENV="$(pwd)/venv"
uv pip install -e ".[all]"
uv pip install -e "./mini-swe-agent"
uv pip install -e "./tinker-atropos"
npm install # optional, for browser tools
npm install # optional, for browser tools and WhatsApp
# Configure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

3
website/docs/getting-started/quickstart.md
View File

@@ -40,6 +40,7 @@ This walks you through selecting an inference provider:
| Provider | What it is | How to set up |
|----------|-----------|---------------|
| **Nous Portal** | Subscription-based, zero-config | OAuth login via `hermes model` |
| **OpenAI Codex** | ChatGPT OAuth, uses Codex models | Device code auth via `hermes model` |
| **OpenRouter** | 200+ models, pay-per-use | Enter your API key |
| **Custom Endpoint** | VLLM, SGLang, any OpenAI-compatible API | Set base URL + API key |
@@ -161,7 +162,7 @@ mcp_servers:
| `hermes` | Start chatting |
| `hermes setup` | Configure providers and settings |
| `hermes model` | Switch provider or model |
| `hermes tools` | See all available tools |
| `hermes tools` | Configure which tools are enabled per platform |
| `hermes doctor` | Diagnose issues |
| `hermes update` | Update to latest version |
| `hermes gateway` | Start the messaging gateway |

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

@@ -16,18 +16,19 @@ These are commands you run from your shell.
|---------|-------------|
| `hermes` | Start interactive chat (default) |
| `hermes chat -q "Hello"` | Single query mode (non-interactive) |
| `hermes --continue` / `-c` | Resume the most recent session |
| `hermes --resume <id>` / `-r <id>` | Resume a specific session |
| `hermes --model <name>` | Use a specific model |
| `hermes --provider <name>` | Force a provider (`nous`, `openrouter`) |
| `hermes --toolsets "web,terminal"` | Use specific toolsets |
| `hermes --verbose` | Enable verbose/debug output |
| `hermes chat --continue` / `-c` | Resume the most recent session |
| `hermes chat --resume <id>` / `-r <id>` | Resume a specific session |
| `hermes chat --model <name>` | Use a specific model |
| `hermes chat --provider <name>` | Force a provider (`nous`, `openrouter`) |
| `hermes chat --toolsets "web,terminal"` / `-t` | Use specific toolsets |
| `hermes chat --verbose` | Enable verbose/debug output |
### Provider & Model Management
| Command | Description |
|---------|-------------|
| `hermes model` | Switch provider and model interactively |
| `hermes login` | OAuth login to a provider (use `--provider` to specify) |
| `hermes logout` | Clear stored OAuth credentials |
### Configuration
@@ -40,6 +41,7 @@ These are commands you run from your shell.
| `hermes config set KEY VAL` | Set a specific value |
| `hermes config check` | Check for missing config (useful after updates) |
| `hermes config migrate` | Interactively add missing options |
| `hermes tools` | Interactive tool configuration per platform |
| `hermes status` | Show configuration status (including auth) |
| `hermes doctor` | Diagnose issues |
@@ -62,6 +64,7 @@ These are commands you run from your shell.
| `hermes gateway stop` | Stop the service |
| `hermes gateway restart` | Restart the service |
| `hermes gateway status` | Check service status |
| `hermes gateway uninstall` | Uninstall the system service |
| `hermes whatsapp` | Pair WhatsApp via QR code |
### Skills
@@ -88,15 +91,21 @@ These are commands you run from your shell.
|---------|-------------|
| `hermes cron list` | View scheduled jobs |
| `hermes cron status` | Check if cron scheduler is running |
| `hermes cron tick` | Manually trigger a cron tick |
| `hermes pairing list` | View pending + approved users |
| `hermes pairing approve <platform> <code>` | Approve a pairing code |
| `hermes pairing revoke <platform> <user_id>` | Remove user access |
| `hermes pairing clear-pending` | Clear all pending pairing requests |
### Sessions
| Command | Description |
|---------|-------------|
| `hermes sessions list` | Browse past sessions |
| `hermes sessions export <id>` | Export a session |
| `hermes sessions delete <id>` | Delete a specific session |
| `hermes sessions prune` | Remove old sessions |
| `hermes sessions stats` | Show session statistics |
---

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

@@ -15,6 +15,7 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
| `OPENROUTER_API_KEY` | OpenRouter API key (recommended for flexibility) |
| `OPENAI_API_KEY` | API key for custom OpenAI-compatible endpoints (used with `OPENAI_BASE_URL`) |
| `OPENAI_BASE_URL` | Base URL for custom endpoint (VLLM, SGLang, etc.) |
| `HERMES_MODEL` | Preferred model name (checked before `LLM_MODEL`, used by gateway) |
| `LLM_MODEL` | Default model name (fallback when not set in config.yaml) |
| `VOICE_TOOLS_OPENAI_KEY` | OpenAI key for TTS and voice transcription (separate from custom endpoint) |
| `HERMES_HOME` | Override Hermes config directory (default: `~/.hermes`) |
@@ -47,9 +48,12 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
| Variable | Description |
|----------|-------------|
| `TERMINAL_ENV` | Backend: `local`, `docker`, `ssh`, `singularity`, `modal` |
| `TERMINAL_DOCKER_IMAGE` | Docker image (default: `python:3.11-slim`) |
| `TERMINAL_DOCKER_IMAGE` | Docker image (default: `python:3.11`) |
| `TERMINAL_DOCKER_VOLUMES` | Additional Docker volume mounts (comma-separated `host:container` pairs) |
| `TERMINAL_SINGULARITY_IMAGE` | Singularity image or `.sif` path |
| `TERMINAL_MODAL_IMAGE` | Modal container image |
| `TERMINAL_TIMEOUT` | Command timeout in seconds |
| `TERMINAL_LIFETIME_SECONDS` | Max lifetime for terminal sessions in seconds |
| `TERMINAL_CWD` | Working directory for all terminal sessions |
| `SUDO_PASSWORD` | Enable sudo without interactive prompt |

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

@@ -18,21 +18,21 @@ hermes
hermes chat -q "Hello"
# With a specific model
hermes --model "anthropic/claude-sonnet-4"
hermes chat --model "anthropic/claude-sonnet-4"
# With a specific provider
hermes --provider nous # Use Nous Portal
hermes --provider openrouter # Force OpenRouter
hermes chat --provider nous # Use Nous Portal
hermes chat --provider openrouter # Force OpenRouter
# With specific toolsets
hermes --toolsets "web,terminal,skills"
hermes chat --toolsets "web,terminal,skills"
# Resume previous sessions
hermes --continue # Resume the most recent CLI session (-c)
hermes --resume <session_id> # Resume a specific session by ID (-r)
# Verbose mode (debug output)
hermes --verbose
hermes chat --verbose
```
## Interface Layout
@@ -264,5 +264,5 @@ By default, the CLI runs in quiet mode which:
For debug output:
```bash
hermes --verbose
hermes chat --verbose
```

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

@@ -46,7 +46,7 @@ The `hermes config set` command automatically routes values to the right file
Settings are resolved in this order (highest priority first):
1. **CLI arguments** — `hermes chat --max-turns 100` (per-invocation override)
1. **CLI arguments** — e.g., `hermes chat --model anthropic/claude-sonnet-4` (per-invocation override)
2. **`~/.hermes/config.yaml`** — the primary config file for all non-secret settings
3. **`~/.hermes/.env`** — fallback for env vars; **required** for secrets (API keys, tokens, passwords)
4. **Built-in defaults** — hardcoded safe defaults when nothing else is set

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

@@ -21,7 +21,7 @@ for r in results["data"]["web"]:
print(summary)
```
**Available tools in sandbox:** `web_search`, `web_extract`, `read_file`, `write_file`, `search`, `patch`, `terminal` (foreground only).
**Available tools in sandbox:** `web_search`, `web_extract`, `read_file`, `write_file`, `search_files`, `patch`, `terminal` (foreground only).
## When the Agent Uses This

3
website/docs/user-guide/features/cron.md
View File

@@ -65,8 +65,9 @@ The agent knows your connected platforms and home channels — it'll choose sens
## Schedule Formats
- **Relative:** `30m`, `2h`, `1d`
- **Human-readable:** `"every 2 hours"`, `"daily at 9am"`
- **Interval:** `"every 30m"`, `"every 2h"`
- **Cron expressions:** `"0 9 * * *"` (standard 5-field cron syntax)
- **ISO timestamps:** `"2026-03-15T09:00:00"` (one-time scheduled execution)
## Managing Jobs

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

@@ -33,7 +33,7 @@ delegate_task(tasks=[
## Key Properties
- Each subagent gets its **own terminal session** (separate from the parent)
- **Depth limit of 2** — no grandchildren
- **No nested delegation** — children cannot delegate further (no grandchildren)
- Subagents **cannot** call: `delegate_task`, `clarify`, `memory`, `send_message`, `execute_code`
- **Interrupt propagation** — interrupting the parent interrupts all active children
- Only the final summary enters the parent's context, keeping token usage efficient

3
website/docs/user-guide/features/memory.md
View File

@@ -41,7 +41,8 @@ The agent uses the `memory` tool with these actions:
- **add** — Add a new memory entry
- **replace** — Replace an existing entry with updated content
- **remove** — Remove an entry that's no longer relevant
- **read** — Read current memory contents
Memory content is automatically injected into the system prompt at session start — there is no `read` action. The agent sees its memories as part of the conversation context.
## Session Search

11
website/docs/user-guide/features/skills.md
View File

@@ -27,8 +27,8 @@ Every installed skill is automatically available as a slash command:
You can also interact with skills through natural conversation:
```bash
hermes --toolsets skills -q "What skills do you have?"
hermes --toolsets skills -q "Show me the axolotl skill"
hermes chat --toolsets skills -q "What skills do you have?"
hermes chat --toolsets skills -q "Show me the axolotl skill"
```
## Progressive Disclosure
@@ -36,10 +36,9 @@ hermes --toolsets skills -q "Show me the axolotl skill"
Skills use a token-efficient loading pattern:
```
Level 0: skills_categories() → ["mlops", "devops"] (~50 tokens)
Level 1: skills_list(category) → [{name, description}, ...] (~3k tokens)
Level 2: skill_view(name) → Full content + metadata (varies)
Level 3: skill_view(name, path) → Specific reference file (varies)
Level 0: skills_list() → [{name, description}, ...] (~3k tokens)
Level 1: skill_view(name) → Full content + metadata (varies)
Level 2: skill_view(name, path) → Specific reference file (varies)
```
The agent only loads the full skill content when it actually needs it.

10
website/docs/user-guide/features/tools.md
View File

@@ -12,9 +12,9 @@ Tools are functions that extend the agent's capabilities. They're organized into
| Category | Tools | Description |
|----------|-------|-------------|
| **Web** | `web_search`, `web_extract`, `web_crawl` | Search the web, extract page content, crawl sites |
| **Terminal** | `terminal` | Execute commands (local/docker/singularity/modal/ssh backends) |
| **File** | `read_file`, `write_file`, `patch`, `search` | Read, write, edit, and search files |
| **Web** | `web_search`, `web_extract` | Search the web, extract page content |
| **Terminal** | `terminal`, `process` | Execute commands (local/docker/singularity/modal/ssh backends), manage background processes |
| **File** | `read_file`, `write_file`, `patch`, `search_files` | Read, write, edit, and search files |
| **Browser** | `browser_navigate`, `browser_click`, `browser_type`, etc. | Full browser automation via Browserbase |
| **Vision** | `vision_analyze` | Image analysis via multimodal models |
| **Image Gen** | `image_generate` | Generate images (FLUX via FAL) |
@@ -27,14 +27,14 @@ Tools are functions that extend the agent's capabilities. They're organized into
| **Cronjob** | `schedule_cronjob`, `list_cronjobs`, `remove_cronjob` | Scheduled task management |
| **Code Execution** | `execute_code` | Run Python scripts that call tools via RPC sandbox |
| **Delegation** | `delegate_task` | Spawn subagents with isolated context |
| **Clarify** | `clarify` | Ask the user multiple-choice or open-ended questions (CLI-only) |
| **Clarify** | `clarify` | Ask the user multiple-choice or open-ended questions |
| **MCP** | Auto-discovered | External tools from MCP servers |
## Using Toolsets
```bash
# Use specific toolsets
hermes --toolsets "web,terminal"
hermes chat --toolsets "web,terminal"
# See all available tools
hermes tools

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

@@ -25,7 +25,7 @@ Convert text to speech with three providers:
| Telegram | Voice bubble (plays inline) | Opus `.ogg` |
| Discord | Audio file attachment | MP3 |
| WhatsApp | Audio file attachment | MP3 |
| CLI | Saved to `~/voice-memos/` | MP3 |
| CLI | Saved to `~/.hermes/audio_cache/` | MP3 |
### Configuration