159 lines
13 KiB
Markdown
159 lines
13 KiB
Markdown
---
|
|
name: ask-hermes
|
|
description: Persistent peer Hermes agent for delegated work. `ask hermes <instructions>` delegates a task with full context via headless one-shot commands. Session persists across all turns in one Hermes session via --resume.
|
|
version: 4.0.0
|
|
author: Hermes Agent
|
|
license: MIT
|
|
platforms: [linux]
|
|
metadata:
|
|
hermes:
|
|
tags: [hermes, peer, delegation, parallel, review, validation]
|
|
related_skills: [ask-claude, claude-code, hermes-agent]
|
|
---
|
|
|
|
# ask-hermes — Peer Hermes Agent for Delegated Work
|
|
|
|
## Overview
|
|
|
|
A persistent peer Hermes agent session for delegated work. The peer runs on the general profile (`hermes -p general`) — a separate agent instance with its own workspace, SOUL.md, AGENTS.md, and all tools (terminal, file, web search, MCP). Fresh context, no memory of this session. Used for parallel work, peer review, validation, and delegated tasks.
|
|
|
|
Each `ask hermes` is a one-shot headless command that runs, returns a clean response, and exits. Continuity (the peer remembering prior turns) comes from `--resume <session_id>`, not from a live process. No start/stop needed — the session starts on the first ask and ends when the Hermes session ends.
|
|
|
|
## When to Use
|
|
|
|
- Want a second agent to do real work in parallel: read files, run tests, validate, search
|
|
- Want peer review of my recommendation with full tool access
|
|
- Multi-turn task: peer can iterate, push back (via --resume)
|
|
- Want local delegation without leaving the terminal
|
|
|
|
## When NOT to Use
|
|
|
|
- Question is factual and I can answer it
|
|
- Task needs my exact context state (use delegate_task on THIS profile)
|
|
- You want to see the peer's chat directly (this is relay-only — full text in `hermes sessions list`)
|
|
|
|
## Command
|
|
|
|
### `ask hermes <instructions>`
|
|
|
|
**First ask (starts the session):**
|
|
```
|
|
hermes -p general chat -q "<composed prompt>" -Q --max-turns 20 --yolo
|
|
```
|
|
- Output line 1: `session_id: <id>` — capture this
|
|
- Output line 2+: the peer's response
|
|
- Hold the session_id in conversation context for all subsequent asks
|
|
|
|
**Subsequent asks (resume the session):**
|
|
```
|
|
hermes -p general chat --resume <session_id> -q "<composed prompt>" -Q --max-turns 20 --yolo
|
|
```
|
|
- Compose prompt with full context (see Prompt Composition)
|
|
- Run command. Parse response (after the session_id line). Relay to operator.
|
|
- Spot-check side-effects (see Spot-check rule).
|
|
|
|
## Session Persistence
|
|
|
|
**HARD RULE: Always --resume the prior session for follow-up asks.** The session_id is captured from output line 1 of the first ask. Every subsequent ask in the same line of work MUST use `--resume <session_id>`, not start a fresh session. Starting fresh discards the peer's context, wastes tokens re-establishing state, and breaks multi-turn workflows. If you don't have the session_id, you failed to capture it — that's a separate failure. The session_id lives in conversation context; hold it there.
|
|
|
|
The session_id lives in conversation context. No state file. If the LXC crashes, we both crash — next session starts fresh.
|
|
|
|
## Prompt Composition
|
|
|
|
Peer has NO memory of this session beyond what --resume carries. Every `ask hermes` includes:
|
|
- Operator's exact instructions (quoted)
|
|
- All relevant absolute file paths
|
|
- Constraints: investigation-first, real testing, scoped workspaces, privacy-first
|
|
- Background: what's already done, what's decided
|
|
- Expected output format (e.g. "return a 1-paragraph summary + list of files changed")
|
|
- Verification handle: "return absolute path / exit code for any side-effect"
|
|
|
|
**HARD RULE: Never paste file content into the prompt.** The peer can read any file by absolute path — point at the path instead (e.g. "read /home/n8n/workspace/dev/hindsight_issue.md and validate it"). Pasting wastes tokens and introduces transcription errors: shell expansion of backticks, encoding issues, and prompt bloat. This is the #1 ask-hermes failure mode. Only paste inline when the content is under ~5 lines or the peer genuinely can't access the path.
|
|
|
|
## Pre-Send Audit
|
|
|
|
Before executing ANY `ask hermes` command, run this 3-question checklist:
|
|
|
|
1. **Is this a follow-up to a prior ask?** If yes, am I using `--resume <session_id>`? Am I sure I have the session_id from the prior output's first line? Starting fresh when I should resume is the #2 failure mode.
|
|
|
|
2. **Am I pasting file content the peer could read from an absolute path?** If yes, replace with a path reference. Only paste inline when content is under ~5 lines or the peer genuinely can't access the path.
|
|
|
|
3. **Does this task involve verifying external facts, docs, or behavior?** If yes, include the web search mandate line: "Use `mcp_searxng_searxng_web_search` for every claim and cite the source URL. Do not rely on parametric knowledge or reason about what a command 'would show.' Run the real command, run the real search."
|
|
|
|
**ALWAYS insist on detailed, multiple web searches.** The peer has the searxng MCP tool (`mcp_searxng_searxng_web_search`). This is non-negotiable — see the **Web Search Mandate** section below for the canonical, must-follow form. Every `ask hermes` prompt that involves verifying facts, docs, or external behavior MUST include the mandate line (specified below).
|
|
|
|
## Web Search Mandate
|
|
|
|
The peer MUST confirm every external fact with a live web search. Parametric knowledge is not enough. The peer has the `mcp_searxng_searxng_web_search` tool — it MUST use it.
|
|
|
|
**What the peer must search for (non-exhaustive):**
|
|
- Version numbers, port numbers, env var names, config keys → official docs (hermes-agent.nousresearch.com, docs.openwebui.com, etc.)
|
|
- Package availability, install commands, library APIs → PyPI, GitHub, official README
|
|
- Behavior claims about a service or tool → vendor docs, GitHub issues, changelog
|
|
- Bug claims, "X is broken" verdicts → live probe + cited source
|
|
|
|
**How the peer must search:**
|
|
- Multiple searches per claim, different angles. A single search is not enough. Official docs + GitHub + PyPI/API reference is the minimum for version-sensitive claims.
|
|
- For every verdict, cite the source URL inline. No URL = unverified = do not relay.
|
|
- Direct the peer to local files by absolute path, not pasted content. Saves tokens and avoids transcription errors.
|
|
|
|
**Hard rule for the calling agent (you):** Every `ask hermes` prompt that involves verifying facts, docs, or external behavior MUST include the line: "Use `mcp_searxng_searxng_web_search` for every claim and cite the source URL. Do not rely on parametric knowledge or reason about what a command 'would show.' Run the real command, run the real search."
|
|
|
|
This section is the canonical form of the web-search requirement. The abbreviated guidance in Prompt Composition above references it and does not override or weaken it.
|
|
|
|
## Turn Budget
|
|
|
|
Max 20 turns per question, enforced by `--max-turns 20` at the CLI level — hard cap. Peer follows up autonomously (tool calls, iterations) without reporting back each turn — only the final result comes back. If the peer hits the 20-turn cap before finishing, it returns what it has — relay that and the operator decides whether to continue with a follow-up ask.
|
|
|
|
## Peer Cross-Validation Pattern
|
|
|
|
When the user wants a deliverable validated, use TWO independent peer passes:
|
|
|
|
1. **Build the deliverable yourself** (research, write, verify).
|
|
2. **Dispatch peer to build the SAME deliverable independently.** Give the peer the same goal, your file path to read first, and the instruction "find what I missed." Do NOT give the peer your conclusions — let it discover independently.
|
|
3. **Spot-check the peer's claims** against source (file:line, live commands). The peer may find real gaps AND may overstate some findings.
|
|
4. **Report the delta** — what the peer added, what was wrong, what was confirmed.
|
|
|
|
This is NOT the same as Delegate-Fix-Then-Validate (where the peer does the work and you verify). Here both agents build independently, then you compare.
|
|
|
|
## Relay Rule
|
|
|
|
Do not silently paraphrase. Relay the peer's actual response — if long, chunk it. Call out unverified "I did X" claims.
|
|
|
|
## Spot-check Rule
|
|
|
|
Peer self-reports are not verified fact. If the peer reports a file write, `read_file` the path to confirm. If it reports a test pass, re-run the test if the result matters.
|
|
|
|
**Peer verdicts can be WRONG.** A peer may flag a profile as BROKEN when it's actually healthy, or claim PASS on something that's broken. Always independently verify the peer's conclusions — don't relay them as fact. Concrete example: peer claimed `general` profile was BROKEN (bank_id leak), but the daemon log showed `general` was actively writing to `hermes-general` with successful retain + consolidation. The peer's logic was confused — it assumed the bank_id convention was violated when it wasn't. The daemon log is the source of truth, not the peer's reasoning.
|
|
|
|
## Delegate-Fix-Then-Validate Pattern
|
|
|
|
When the user says "ask hermes to fix X, then YOU validate," follow this exact sequence:
|
|
|
|
1. **Compose findings + goal.** Write a clear prompt with: what's broken, what the correct state should be, file paths, constraints (read-only vs. allowed changes), and expected output format.
|
|
2. **Dispatch peer to fix.** Run `hermes -p general chat -q "..." -Q --max-turns 20 --yolo`. The peer does the work.
|
|
3. **Independently validate.** Do NOT trust the peer's self-report. Verify every claim: stat files, curl endpoints, read configs, check daemon logs. The peer may claim "PASS" on things that are actually broken, or flag things as BROKEN that are correct.
|
|
4. **Report the validated results** — not the peer's raw self-report.
|
|
|
|
**CRITICAL: Do NOT jump in and do the fix yourself.** If the user said "ask hermes to fix it," the peer does the fixing. You only validate afterward. Doing the fix yourself violates the user's explicit instruction and skips the peer review step.
|
|
|
|
## Common Pitfalls
|
|
|
|
1. **Profile flag required.** Use `-p general` — the sticky default may be dev, which would spawn a clone of this agent, not a peer. Always pin the profile explicitly.
|
|
2. **--yolo is required.** The peer runs headless (one-shot, no TTY). Without `--yolo`, dangerous-command approval prompts fail closed (60s timeout → deny) and the peer can't complete tasks that trigger them. `--yolo` bypasses all approval prompts for the peer session only. The hardline blocklist (rm -rf /, fork bombs, mkfs on root, dd to block devices) still applies — no flag overrides that. This does NOT change the general profile's config; it only affects the peer session.
|
|
3. **Peer skill_manage writes to the peer's profile, not yours.** If the peer patches a skill via skill_manage, it lands in the peer's profile (general), not the calling agent's profile (dev). The peer's `skill_manage` uses its own profile context. To sync changes back to dev, the calling agent must apply the same patches to its own copy. This is the #3 ask-hermes failure mode — assuming peer changes are global.
|
|
4. **Do NOT use interactive REPL mode.** Running `hermes -p general` without `chat -q` (interactive REPL) was tried and failed — the TUI produces unreadable ANSI redraw noise when driven via `terminal(pty=true)`. The output is garbled and responses cannot be extracted. Always use headless `chat -q "..." -Q` instead.
|
|
5. **Peer is headless.** Operator sees my relay, not the peer's chat. Full text in `hermes sessions list` if needed.
|
|
6. **Peer self-reports are not verified fact.** Spot-check file writes, test passes before confirming to operator.
|
|
7. **Peer's workspace is its own.** Files written to the peer's workspace are NOT in this agent's workspace. Give ABSOLUTE paths (e.g. `/home/n8n/workspace/dev/<path>`) if the peer should write to our workspace.
|
|
8. **Blast radius.** Peer has ALL tools (terminal, web, MCP) — can rm, exfil, burn tokens. Bound with prompt-level constraints. State the blast radius to operator for sensitive tasks.
|
|
9. **Turn budget is hard-capped.** `--max-turns 20` enforces it. If the peer hits 20 before finishing, it returns what it has — operator decides whether to continue.
|
|
10. **Don't silently paraphrase.** Relay the peer's actual response. If long, chunk it. Call out unverified claims.
|
|
11. **Peers can overstate findings.** A peer may correctly identify real gaps AND incorrectly flag things that aren't actually broken. In this session, the peer correctly identified the tool_executor.py ThreadPoolExecutor as the root cause of the Ctrl+C hang, but also flagged cli.py:9452 (account-usage fetch) as a second culprit — that one uses a `with` context manager that properly joins, so it's not a leak. Always verify each claim independently; don't assume all of a peer's findings are correct just because some are.
|
|
|
|
## Verification Checklist
|
|
|
|
- [x] First `ask hermes <task>` returns peer's response showing real tool use
|
|
- [x] `session_id:` captured from output line 1
|
|
- [x] Second ask with `--resume` — peer remembers prior turn
|
|
- [x] Spot-check: peer reports "wrote file at /path" → I `read_file` /path and confirm content matches |