feat: add Hermes Agent as native spawn target (#63)

* feat: add Hermes Agent as native spawn target

Add first-class support for Hermes Agent CLI in the spawn adapter system,
following the same patterns used by OpenClaw, Claude, Codex, and other agents.

Spawn adapters (adapters.py, tmux_backend.py, subprocess_backend.py):
- is_hermes_command() detection in command_validation.py and adapters.py
- Hermes included in is_interactive_cli() across all modules
- Auto-insert 'chat' subcommand when bare 'hermes' is passed
- Prompt via -q flag, session isolation via --continue
- Model forwarding via -m in tmux_backend
- --yolo for skip_permissions across all three backends
- None-guard on agent_name to prevent literal "None" session keys

Tests (test_adapters.py):
- is_hermes_command detection (bare name, full path, negatives)
- is_interactive_cli includes hermes
- 7 new tests: yolo, chat insertion, no-duplicate-chat, prompt via -q,
  --continue session, no-continue-without-name, yolo-preserved-with-chat

470 tests pass, 0 failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: replace invalid --continue flag with --source tool for Hermes spawns

Discovered during end-to-end testing: Hermes --continue only RESUMES existing
sessions and errors out with "No session found" when given a fresh name. Fresh
spawns must let Hermes auto-generate the session ID.

Changes:
- Remove automatic --continue flag from Hermes spawn commands
- Add --source tool so clawteam-spawned Hermes sessions don't pollute the
  user's session list (default --source cli)
- Update tests to verify --source tool is set and --continue is absent

Verified end-to-end: hermes chat --yolo --source tool -q "..." responds
correctly and exits cleanly with an auto-generated session ID.

470 tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add Hermes Agent to README supported agents

List Hermes in the agents badge, the prose agent list, and the Supported
Agents table. Spawn command: clawteam spawn hermes --team ...

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address codex review findings for Hermes adapter

Codex independent review caught 3 real issues:

[P1] subprocess_backend missing Hermes command block
  - Before: Hermes fell through to generic 'hermes -p <prompt>' on Windows
    or explicit subprocess backend. Hermes -p means --profile, not prompt.
  - After: Added Hermes block with chat insertion, --source tool, -m model,
    and -q prompt. Mirrors tmux_backend behavior.

[P2] Blind 'chat' insertion clobbered global options
  - Before: insert(1, 'chat') on any hermes command, rewriting 'hermes --profile
    foo' into 'hermes chat --profile foo' and breaking argv order.
  - After: Only insert chat when user's original command is bare 'hermes'
    (len(normalized_command) == 1). Respect user-supplied global options
    and alternate subcommands (sessions, model, setup, etc.).

[P3] No backend-level Hermes tests
  - Added test_tmux_backend_hermes_chat_source_and_prompt
  - Added test_subprocess_backend_hermes_chat_source_and_prompt
  - Added test_hermes_preserves_global_options (regression for --profile)
  - Added test_hermes_preserves_alternate_subcommand

[P3] README overstated support
  - Clarified Hermes status: "Full support (tmux + subprocess)"

474 tests pass (up from 470, +4 new).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: win4r

README.md

@@ -26,7 +26,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-≥3.10-blue?logo=python&logoColor=white" alt="Python">
-  <img src="https://img.shields.io/badge/agents-OpenClaw_%7C_Claude_Code_%7C_Codex_%7C_nanobot-blueviolet" alt="Agents">
+  <img src="https://img.shields.io/badge/agents-OpenClaw_%7C_Claude_Code_%7C_Codex_%7C_Hermes_%7C_nanobot-blueviolet" alt="Agents">
   <img src="https://img.shields.io/badge/transport-File_%7C_ZeroMQ_P2P-orange" alt="Transport">
   <img src="https://img.shields.io/badge/version-0.3.0-teal" alt="Version">
 </p>
@@ -35,7 +35,7 @@
 
 You set the goal. The agent swarm handles the rest — spawning workers, splitting tasks, coordinating, and merging results.
 
-Works with [OpenClaw](https://openclaw.ai) (default), [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/codex), [nanobot](https://github.com/HKUDS/nanobot), [Cursor](https://cursor.com), and any CLI agent.
+Works with [OpenClaw](https://openclaw.ai) (default), [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/codex), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [nanobot](https://github.com/HKUDS/nanobot), [Cursor](https://cursor.com), and any CLI agent.
 
 ## Platform Support
 
@@ -141,6 +141,7 @@ clawteam board attach my-team   # Linux/macOS/WSL with tmux
 | [Claude Code](https://claude.ai/claude-code) | `clawteam spawn claude --team ...` | Full support |
 | [Codex](https://openai.com/codex) | `clawteam spawn codex --team ...` | Full support |
 | [nanobot](https://github.com/HKUDS/nanobot) | `clawteam spawn nanobot --team ...` | Full support |
+| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | `clawteam spawn hermes --team ...` | Full support (tmux + subprocess) |
 | [Cursor](https://cursor.com) | `clawteam spawn subprocess cursor --team ...` | Experimental |
 | Custom scripts | `clawteam spawn subprocess python --team ...` | Full support |
 

clawteam/spawn/adapters.py

@@ -18,7 +18,7 @@ class PreparedCommand:
 
 
 class NativeCliAdapter:
-    """Adapter for direct CLI runtimes such as claude, codex, gemini, kimi, nanobot, qwen, opencode."""
+    """Adapter for direct CLI runtimes such as claude, codex, gemini, hermes, kimi, nanobot, qwen, opencode."""
 
     def prepare_command(
         self,
@@ -43,10 +43,27 @@ def prepare_command(
                 is_gemini_command(normalized_command)
                 or is_kimi_command(normalized_command)
                 or is_opencode_command(normalized_command)
+                or is_hermes_command(normalized_command)
             ):
                 final_command.append("--yolo")
 
-        if is_kimi_command(normalized_command):
+        if is_hermes_command(normalized_command):
+            # Hermes: tag as tool-sourced so clawteam spawns don't pollute the
+            # user's session list, pass prompt via -q. Insert 'chat' subcommand
+            # only when the user's original command is bare `hermes` (don't clobber
+            # user-supplied global options or alternate subcommands).
+            # Check normalized_command, not final_command, since skip_permissions
+            # may have already appended --yolo.
+            # Do NOT pass --continue -- Hermes --continue resumes EXISTING sessions
+            # only; fresh spawns auto-generate a session ID.
+            if len(normalized_command) == 1:
+                # Insert chat at position 1 (before any --yolo already appended).
+                final_command.insert(1, "chat")
+            if "--source" not in final_command:
+                final_command.extend(["--source", "tool"])
+            if prompt:
+                final_command.extend(["-q", prompt])
+        elif is_kimi_command(normalized_command):
             if cwd and not command_has_workspace_arg(normalized_command):
                 final_command.extend(["-w", cwd])
             if prompt:
@@ -158,6 +175,11 @@ def is_openclaw_command(command: list[str]) -> bool:
     return command_basename(command) == "openclaw"
 
 
+def is_hermes_command(command: list[str]) -> bool:
+    """Check if the command is a Hermes Agent CLI invocation."""
+    return command_basename(command) == "hermes"
+
+
 def is_interactive_cli(command: list[str]) -> bool:
     """Check if the command is a known interactive AI coding CLI."""
     return (
@@ -169,6 +191,7 @@ def is_interactive_cli(command: list[str]) -> bool:
         or is_qwen_command(command)
         or is_opencode_command(command)
         or is_openclaw_command(command)
+        or is_hermes_command(command)
     )
 
 

clawteam/spawn/command_validation.py

@@ -102,6 +102,11 @@ def is_opencode_command(command: list[str]) -> bool:
     return _cmd_basename(command) == "opencode"
 
 
+def is_hermes_command(command: list[str]) -> bool:
+    """Check if the command is a Hermes Agent CLI invocation."""
+    return _cmd_basename(command) == "hermes"
+
+
 def is_interactive_cli(command: list[str]) -> bool:
     """Check if the command is an interactive AI CLI."""
     return (
@@ -113,6 +118,7 @@ def is_interactive_cli(command: list[str]) -> bool:
         or is_kimi_command(command)
         or is_qwen_command(command)
         or is_opencode_command(command)
+        or is_hermes_command(command)
     )
 
 

clawteam/spawn/subprocess_backend.py

@@ -17,6 +17,7 @@
     is_claude_command,
     is_codex_command,
     is_gemini_command,
+    is_hermes_command,
     is_kimi_command,
     is_nanobot_command,
     is_openclaw_command,
@@ -95,15 +96,30 @@ def spawn(
                 final_command.append("--dangerously-skip-permissions")
             elif is_codex_command(normalized_command):
                 final_command.append("--dangerously-bypass-approvals-and-sandbox")
-            elif is_gemini_command(normalized_command) or is_kimi_command(normalized_command) or is_opencode_command(normalized_command):
+            elif is_gemini_command(normalized_command) or is_kimi_command(normalized_command) or is_opencode_command(normalized_command) or is_hermes_command(normalized_command):
                 final_command.append("--yolo")
         # Claude Code: pass --model if specified
         # Pass --model if specified (claude, openclaw)
         if model and is_claude_command(normalized_command):
             final_command.extend(["--model", model])
         if model and is_openclaw_command(normalized_command):
             final_command.extend(["--model", model])
-        if is_kimi_command(normalized_command):
+        # Hermes Agent: insert 'chat' only when the user's original command is
+        # bare `hermes` (don't clobber user-supplied global options or subcommands).
+        # Check normalized_command, not final_command, since skip_permissions
+        # may have already appended --yolo.
+        # Tag with --source tool so clawteam spawns don't pollute user session list.
+        # Pass prompt via -q (Hermes -p is --profile, not prompt).
+        if is_hermes_command(normalized_command):
+            if len(normalized_command) == 1:
+                final_command.insert(1, "chat")
+            if "--source" not in final_command:
+                final_command.extend(["--source", "tool"])
+            if model:
+                final_command.extend(["-m", model])
+            if prompt:
+                final_command.extend(["-q", prompt])
+        elif is_kimi_command(normalized_command):
             if cwd and not command_has_workspace_arg(normalized_command):
                 final_command.extend(["-w", cwd])
             if prompt:

clawteam/spawn/tmux_backend.py

@@ -25,6 +25,7 @@
     is_claude_command,
     is_codex_command,
     is_gemini_command,
+    is_hermes_command,
     is_kimi_command,
     is_nanobot_command,
     is_openclaw_command,
@@ -176,7 +177,7 @@ def spawn(
                 final_command.append("--dangerously-skip-permissions")
             elif is_codex_command(normalized_command):
                 final_command.append("--dangerously-bypass-approvals-and-sandbox")
-            elif is_gemini_command(normalized_command) or is_kimi_command(normalized_command) or is_opencode_command(normalized_command):
+            elif is_gemini_command(normalized_command) or is_kimi_command(normalized_command) or is_opencode_command(normalized_command) or is_hermes_command(normalized_command):
                 final_command.append("--yolo")
 
         # Claude Code: pass --model if specified
@@ -210,6 +211,25 @@ def spawn(
                 if prompt:
                     final_command.extend(["--message", prompt])
 
+        # Hermes Agent: tag as tool-sourced so clawteam spawns don't pollute the
+        # user's session list, pass prompt via -q. Insert 'chat' subcommand
+        # only when the user's original command is bare `hermes` (don't clobber
+        # user-supplied global options or alternate subcommands).
+        # Check normalized_command, not final_command, since skip_permissions
+        # may have already appended --yolo.
+        # Do NOT pass --continue -- Hermes --continue resumes EXISTING sessions
+        # only; fresh spawns auto-generate a session ID.
+        if is_hermes_command(normalized_command):
+            if len(normalized_command) == 1:
+                # Insert chat at position 1 (before any --yolo already appended).
+                final_command.insert(1, "chat")
+            if "--source" not in final_command:
+                final_command.extend(["--source", "tool"])
+            if model:
+                final_command.extend(["-m", model])
+            if prompt:
+                final_command.extend(["-q", prompt])
+
         if is_kimi_command(normalized_command):
             if cwd and not command_has_workspace_arg(normalized_command):
                 final_command.extend(["-w", cwd])
@@ -300,7 +320,7 @@ def spawn(
                 fallback_delay=cfg.spawn_prompt_delay,
             )
             _inject_prompt_via_buffer(target, agent_name, prompt)
-        elif prompt and not is_codex_command(normalized_command) and not is_openclaw_command(normalized_command) and not is_nanobot_command(normalized_command) and not is_gemini_command(normalized_command) and not is_kimi_command(normalized_command) and not is_qwen_command(normalized_command) and not is_opencode_command(normalized_command):
+        elif prompt and not is_codex_command(normalized_command) and not is_openclaw_command(normalized_command) and not is_hermes_command(normalized_command) and not is_nanobot_command(normalized_command) and not is_gemini_command(normalized_command) and not is_kimi_command(normalized_command) and not is_qwen_command(normalized_command) and not is_opencode_command(normalized_command):
             # Generic command: append prompt via send-keys
             _wait_for_tui_ready(
                 target,

tests/test_adapters.py

@@ -5,6 +5,7 @@
 from clawteam.spawn.adapters import (
     NativeCliAdapter,
     command_basename,
+    is_hermes_command,
     is_interactive_cli,
     is_opencode_command,
     is_qwen_command,
@@ -27,8 +28,14 @@ def test_is_opencode_command(self):
         assert not is_opencode_command(["openai"])
         assert not is_opencode_command([])
 
+    def test_is_hermes_command(self):
+        assert is_hermes_command(["hermes"])
+        assert is_hermes_command(["/usr/local/bin/hermes"])
+        assert not is_hermes_command(["claude"])
+        assert not is_hermes_command([])
+
     def test_is_interactive_cli_covers_all_known(self):
-        for cmd in ["claude", "codex", "nanobot", "gemini", "kimi", "qwen", "opencode"]:
+        for cmd in ["claude", "codex", "nanobot", "gemini", "hermes", "kimi", "qwen", "opencode"]:
             assert is_interactive_cli([cmd]), f"{cmd} should be interactive"
 
     def test_is_interactive_cli_rejects_unknown(self):
@@ -112,3 +119,73 @@ def test_codex_exec_remains_noninteractive(self):
         )
         assert result.post_launch_prompt is None
         assert "hello" in result.final_command
+
+
+class TestHermesCommandPreparation:
+    """Hermes Agent: chat subcommand insertion, --source tool tag, -q prompt, --yolo."""
+
+    adapter = NativeCliAdapter()
+
+    def test_hermes_gets_yolo(self):
+        result = self.adapter.prepare_command(
+            ["hermes"], skip_permissions=True, agent_name="w1",
+        )
+        assert "--yolo" in result.final_command
+        assert "chat" in result.final_command
+
+    def test_hermes_chat_subcommand_inserted(self):
+        result = self.adapter.prepare_command(["hermes"], agent_name="w1")
+        assert result.final_command[1] == "chat"
+
+    def test_hermes_no_duplicate_chat(self):
+        result = self.adapter.prepare_command(["hermes", "chat"], agent_name="w1")
+        assert result.final_command.count("chat") == 1
+
+    def test_hermes_preserves_global_options(self):
+        # If user passes hermes with global options (e.g., --profile), we must
+        # NOT insert 'chat' and break the argv order. Hermes CLI shape is
+        # `hermes [global-options] <command>`.
+        result = self.adapter.prepare_command(
+            ["hermes", "--profile", "foo"], agent_name="w1",
+        )
+        # chat should NOT be injected when the user passed global options
+        assert "chat" not in result.final_command
+        # source tag should still apply
+        assert "--source" in result.final_command
+
+    def test_hermes_preserves_alternate_subcommand(self):
+        # If user passes a non-chat subcommand (e.g., `hermes sessions`),
+        # we must not rewrite it as `hermes chat sessions`.
+        result = self.adapter.prepare_command(["hermes", "sessions"], agent_name="w1")
+        assert result.final_command[1] == "sessions"
+        assert "chat" not in result.final_command
+
+    def test_hermes_prompt_via_q_flag(self):
+        result = self.adapter.prepare_command(
+            ["hermes"], prompt="do work", agent_name="w1",
+        )
+        assert "-q" in result.final_command
+        assert "do work" in result.final_command
+        assert result.post_launch_prompt is None
+
+    def test_hermes_tagged_as_tool_source(self):
+        # Hermes spawns from clawteam use --source tool so they don't
+        # pollute the user's session list (which defaults to cli)
+        result = self.adapter.prepare_command(["hermes"], agent_name="w1")
+        assert "--source" in result.final_command
+        assert "tool" in result.final_command
+
+    def test_hermes_no_continue_flag(self):
+        # Hermes --continue resumes an existing session; clawteam spawns
+        # are fresh, so we must not pass --continue
+        result = self.adapter.prepare_command(["hermes"], agent_name="w1")
+        assert "--continue" not in result.final_command
+
+    def test_hermes_yolo_preserved_with_chat(self):
+        result = self.adapter.prepare_command(
+            ["hermes"], skip_permissions=True, agent_name="w1",
+        )
+        assert "--yolo" in result.final_command
+        assert "chat" in result.final_command
+        chat_idx = result.final_command.index("chat")
+        assert chat_idx == 1  # chat at position 1

tests/test_spawn_backends.py

@@ -1257,6 +1257,80 @@ def fake_popen(cmd, **kwargs):
     assert captured["cmd"][-4:] == ["opencode", "--yolo", "-p", "fix the bug"]
 
 
+def test_tmux_backend_hermes_chat_source_and_prompt(monkeypatch, tmp_path):
+    run_calls = _make_tmux_spawn_harness(monkeypatch, tmp_path, "hermes")
+
+    backend = TmuxBackend()
+    result = backend.spawn(
+        command=["hermes"],
+        agent_name="researcher",
+        agent_id="agent-h",
+        agent_type="general-purpose",
+        team_name="demo-team",
+        prompt="do research",
+        cwd="/tmp/demo",
+        skip_permissions=True,
+    )
+
+    assert "spawned" in result
+    new_session = next(c for c in run_calls if c[:3] == ["tmux", "new-session", "-d"])
+    full_cmd = new_session[-1]
+    # Verify: chat subcommand inserted, --yolo (skip_permissions), --source tool,
+    # -q prompt, and NO --continue (which only resumes existing sessions)
+    assert "hermes chat" in full_cmd
+    assert "--yolo" in full_cmd
+    assert "--source tool" in full_cmd
+    assert "-q 'do research'" in full_cmd
+    assert "--continue" not in full_cmd
+
+
+def test_subprocess_backend_hermes_chat_source_and_prompt(monkeypatch, tmp_path):
+    monkeypatch.setenv("PATH", "/usr/bin:/bin")
+    clawteam_bin = tmp_path / "venv" / "bin" / "clawteam"
+    clawteam_bin.parent.mkdir(parents=True)
+    clawteam_bin.write_text("#!/bin/sh\n")
+    monkeypatch.setattr(sys, "argv", [str(clawteam_bin)])
+
+    captured: dict[str, object] = {}
+
+    def fake_popen(cmd, **kwargs):
+        captured["cmd"] = cmd
+        return DummyProcess()
+
+    monkeypatch.setattr(
+        "clawteam.spawn.command_validation.shutil.which",
+        lambda name, path=None: "/usr/bin/hermes" if name == "hermes" else None,
+    )
+    monkeypatch.setattr("clawteam.spawn.subprocess_backend.subprocess.Popen", fake_popen)
+    monkeypatch.setattr("clawteam.spawn.registry.register_agent", lambda **_: None)
+
+    backend = SubprocessBackend()
+    backend.spawn(
+        command=["hermes"],
+        agent_name="researcher",
+        agent_id="agent-h",
+        agent_type="general-purpose",
+        team_name="demo-team",
+        prompt="do research",
+        cwd="/tmp/demo",
+        skip_permissions=True,
+    )
+
+    cmd = captured["cmd"]
+    # Find the start of the agent command within the subprocess wrapper args
+    hermes_idx = cmd.index("hermes")
+    agent_cmd = cmd[hermes_idx:]
+    # Verify: chat subcommand, --yolo, --source tool, -q prompt (not -p!)
+    assert agent_cmd[:2] == ["hermes", "chat"]
+    assert "--yolo" in agent_cmd
+    assert "--source" in agent_cmd
+    assert "tool" in agent_cmd
+    assert "-q" in agent_cmd
+    assert "do research" in agent_cmd
+    # Must NOT use -p (that's --profile in Hermes)
+    assert "-p" not in agent_cmd
+
+
 # --- Gateway token propagation (issue #51) ---