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.
# 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`)
## Critical Evaluation — You Are the Final Authority
**The peer's output is input, not a decision.** You are the engineer — you own the code, the system, and the final call. The peer is a separate agent with no memory of your conversation, no access to your context, and no ability to verify its own claims against your environment. Treat every finding as a hypothesis to be tested, not a conclusion to be implemented.
**Mandatory before acting on the peer's output:**
1.**Do your own reasoning first.** Before relaying the peer's answer, ask yourself: does this make sense? Is there a simpler way? Would this actually work in our environment? The peer may flag things as BROKEN that are actually correct, or claim PASS on things that are broken.
2.**Push back when the peer is wrong.** If the peer's analysis doesn't hold up, tell it so in a follow-up `--resume` turn. "Your claim about X is wrong because Y. Re-examine." The peer corrects itself when challenged; it doubles down when unchallenged. Do not silently discard a wrong finding — make the peer confront it.
3.**Do your own web searches to validate.** The peer has SearXNG but its interpretation may be wrong. For any claim about API behavior, version compatibility, or tool capabilities, run your own `mcp_searxng_searxng_web_search` and compare. The peer has been wrong about config keys, endpoint behavior, and system state in real sessions.
4.**Involve the user when there's genuine ambiguity.** If the peer and you disagree after a round of pushback, or if the right approach depends on constraints only the user knows, surface the disagreement with both positions stated clearly. Don't silently pick the peer's answer over your own judgment.
5.**Watch for overcomplication.** Peers, like any agent, can overengineer. If the peer proposes a multi-step protocol, a new abstraction layer, or a refactor that touches 10 files for a 1-line bug — ask: "Is there a simpler way?" The best fix is usually the simplest one that actually works.
## Peer Limitations
**The peer has no memory of your conversation.** The peer runs on the general profile with its own workspace, SOUL.md, and AGENTS.md. It knows nothing about what you've discussed, what files you've created, or what decisions you've made — unless you tell it via the prompt or it reads files by path. Every `ask hermes` must be self-contained with all relevant context.
**The peer may fabricate plausible-sounding analysis when it can't verify.** If the peer can't read a file, reach an endpoint, or confirm a claim, it may still produce confident-sounding analysis based on assumptions. When the peer prefaces a claim with "based on the description" or "assuming the config is..." without having actually read the source, treat it as unverified.
**The peer's environment is not your environment.** The peer has its own terminal session, its own working directory, and its own tool state. A command that works in the peer's session may fail in yours. Always test the peer's suggestions locally before deploying.
**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. If it reports an endpoint returning 200, curl it yourself. The peer may claim "PASS" on things that are actually broken, or flag things as BROKEN that are correct. 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.
**HARD RULE: Same topic = resume. New topic = new session.**
- **Same topic / same line of work:** Always `--resume <session_id>`. 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.
- **New topic / new line of work:** Start a fresh session. Do NOT resume an unrelated session — the peer's context is polluted with the old topic and will confuse it.
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.)
- 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.
**Default:** `--max-turns 20` per `ask-hermes` invocation. Hard cap. Fine for short delegation, plan reviews, and quick peer checks. If the peer hits 20 before finishing, it returns what it has — operator decides whether to continue with a follow-up ask.
**Override — 600 turns (operator standing rule):** For accurate, evidence-based plan-building, deep research-style multi-phase work, or any task where the operator's intent is thoroughness, use `--max-turns 600 --yolo` instead. The 600 is a safety net, not a budget — the operator's exact rule: *"I don't want to be turn restricted. I just want a safety net. I mostly want the job done right. Not concerned with time or tokens when building accurate plan."* The `create-plan` skill's curator invocation always uses 600. Default to 20 only for short factual lookups or quick peer checks. See `writing-plans` skill §"Turn Budget" for the canonical rule.
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.
**Do NOT silently accept the peer's recommendations. Do NOT silently drop suggestions you disagree with. Both are failure modes.**
For every peer response, before applying or moving on, do this scan:
**1. Disagreement check.** Walk through the peer's findings. For each:
- **Agree + will apply** → no action this step
- **Agree + will skip** → state explicitly WHY you're skipping (overkill, environment constraint, contradicts operator's standing rule, etc.). Do not just drop it.
- **Disagree** → push back via `--resume`. Either (a) decide it's not worth the round-trip cost and state your reason, or (b) send a follow-up turn challenging the peer's claim. **If you don't push back on at least one item per multi-finding response, you're accepting the peer's framing wholesale — which defeats the purpose of asking.**
**2. Web-reference check for weak conclusions.** For any peer claim that is:
- a tool version, API behavior, library status, or compatibility statement
- a system state assertion ("profile X is broken", "service Y is down")
- a "best practice" assertion
- any concrete factual claim that the plan or system will depend on
…and where the peer did NOT cite a source URL inline OR run a live command to verify, send a follow-up demanding the verification. Pattern: "Show me the command output that supports X. I want a URL or a live test, not reasoning." This combines with the Web Search Mandate above — the peer MUST search, not reason.
**3. Internal consistency check.** Does the peer's response contradict itself, or contradict a prior turn in this peer session? If yes, point it out in the next follow-up. Don't apply a contradictory recommendation.
**Output format for the scan (use this when relaying the peer's response to the operator):**
```
[Peer's findings as-is]
## My disagreement scan
- **Agreed and applied:** [list]
- **Agreed but skipped:** [item] — [reason]
- **Disagreed and pushed back:** [item] — [what I said]
- **Web references / live tests requested:** [items where I demanded a URL or run]
- **Disagreed silently dropped:** (should be empty — if not, justify)
```
If `Disagreed silently dropped` is non-empty, that's a bug. Surface it.
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 examples:
- 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.
- Peer claimed `default` profile "does not exist on this system" because `ls ~/.hermes/profiles/default/` returned ENOENT. But `hermes -p default skills update` works — the `default` profile uses base `~/.hermes/`, not a `profiles/default/` directory. The peer didn't test the actual command before declaring it broken. Always verify peer claims about system state with a live command, not just filesystem inspection.
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.
2.**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.
3.**Peer is headless.** Operator sees my relay, not the peer's chat. Full text in `hermes sessions list` if needed.
4.**Peer self-reports are not verified fact.** Spot-check file writes, test passes before confirming to operator.
5.**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.
6.**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.
7.**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.
8.**Long implementations hit the 600s foreground wall-clock limit.** A peer dispatch with `--max-turns 50` doing 30+ minutes of work (real implementation, multiple smoke tests with research-profile dispatches inside) can exceed the foreground command's 600-second timeout even when well within the turn budget. The peer may be terminated mid-task with no output, leaving the dispatch in an indeterminate state. **Mitigation:** for any peer dispatch expected to take more than ~5 minutes of wall-clock time, use the terminal tool's `background=true` + `notify_on_complete=true` mode instead of foreground. The peer runs to completion, you get notified on exit, and you spot-check the result. Real example (July 2026): dispatching a 9-task skill build (`better-search` implementation) to `ask-dev` with `--max-turns 50` hit the 600s foreground timeout during Task 5 (smoke test 2). Re-dispatching in background mode completed all 9 tasks. **Rule of thumb:** if the work involves 3+ smoke tests that each spawn their own research-profile dispatches, use background mode from the start.
9.**Don't silently paraphrase.** Relay the peer's actual response. If long, chunk it. Call out unverified claims.
10.**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.
Before EVERY `ask hermes` dispatch, verify the general profile's `reasoning_effort` is set to the maximum the model supports. This is a hard gate — do not dispatch without checking.
```
# 1. Read the general profile's current model and reasoning_effort
grep -E "default:|reasoning_effort:" ~/.hermes/profiles/general/config.yaml | head -5
# 2. If reasoning_effort is NOT at max for the model:
# - deepseek-v4-pro:cloud → set to 'max' (xhigh rejected)
# - glm-5.2:cloud → set to 'max' (xhigh rejected)
# - minimax-m3:cloud → set to 'xhigh' (supports it)
# - If unsure what the model supports → set to 'max' (safe default)
# 3. Apply the fix if needed:
hermes -p general config set agent.reasoning_effort xhigh
# OR for models that reject xhigh:
hermes -p general config set agent.reasoning_effort max
```
**Rule:** Always dispatch with the highest reasoning effort the model actually supports. Never silently downgrade. If the model changed and you don't know what it supports, test with `max` first (universally safer than `xhigh`).
