Multi-Agent Workflows

Subagent delegation handles parallelism inside a single Hermes process. The moment that process exits, every child agent dies with it. When you need parallel workers that survive the parent, that keep running after your terminal session ends, or that you can inspect and interact with independently, you spawn separate Hermes processes. tmux is the orchestration layer.

What you'll learn

• Multi-agent workflows spawn independent Hermes processes in tmux sessions, each with its own context, model, and working directory
• One-shot mode (hermes chat -q) is the launch mechanism, each agent gets a task, runs it to completion, and the session persists for inspection
• Worktree mode (-w) isolates each agent in a git worktree so parallel agents on the same repo never step on each other's files
• Session resume (--continue, --resume) lets you pick up an agent's work mid-stream or give it follow-up instructions after it finishes

The problem

You have a codebase with 30 services. You need to upgrade a dependency across all of them. Delegation handles this, but only inside one run. If the parent process dies or you close the terminal, every in-progress child dies too. And if one service's upgrade is particularly tricky, you cannot open that child's context and give it follow-up instructions, the child's entire session vanishes when the parent collects the result.

Multi-agent workflows give you durable, inspectable, independently addressable workers. Each one gets its own tmux window. You can attach to any window and see the full history of tool calls. You can send the agent a follow-up message. And because it runs in tmux, it survives your SSH session dropping.

This is the difference between "the agent ran a task" and "the agent is running a task right now, and I can talk to it." If you have worked through the multi-agent patterns in the AI Agents & Vibe Coding course, the conceptual model is similar, Hermes adds worktree isolation and direct session resume on top of it.

Options & when to use each

Approach	Good for	Costs you	When to pick it
tmux spawning with one-shot	Durable parallel workers, inspectable sessions, long-running independent tasks	Requires tmux, more orchestration up front, manual cleanup of sessions	When agents need to run longer than the parent, or you need to inspect individual agent sessions
Subagent delegation	Fast parallelism inside one run, automatic result collection	Children die with the parent, no session persistence	When tasks are short and you need results collected automatically
Manual hermes sessions in separate terminals	Ad-hoc parallel work with full interactive control	You are the scheduler, no automation, no batch launch	Quick one-off parallel tasks where you want to watch each one
Worktree mode (-w)	Parallel agents on the same repo that make file changes	Each worktree consumes disk space for a checkout (~100-500MB for a typical repo)	When two agents might edit the same file simultaneously or need isolated working trees

Build it

Step 1: Spawn a single agent in a tmux session

The simplest pattern: create a named tmux session, run a one-shot Hermes command in it, and detach.

# Create a tmux session named "audit-api"
tmux new-session -d -s audit-api

# Send a one-shot Hermes command to it
tmux send-keys -t audit-api \
  'hermes chat -q "Audit the API gateway for security issues: check for hardcoded secrets, missing input validation, and outdated dependencies. Save findings to /tmp/audit-api-report.md."' \
  Enter

# Detach (the session keeps running)
# You can reattach later with: tmux attach -t audit-api

The session persists. Detach, go do something else, and reattach when you want to see the output.

Step 2: Spawn parallel agents across multiple tmux windows

For the 30-service dependency upgrade, batch-spawn agents:

#!/bin/bash
# Spawn an agent per service directory in parallel
SERVICES=("api-gateway" "auth-service" "billing-worker" "notification-service" "user-dashboard")
SESSION="dep-upgrade"

# Create the session with the first window
tmux new-session -d -s "$SESSION" -n "${SERVICES[0]}"
tmux send-keys -t "$SESSION:${SERVICES[0]}" \
  "hermes chat -q \"Upgrade the 'requests' library to the latest version in the ${SERVICES[0]} project. Run tests after the upgrade. Report success or the specific test failure.\"" \
  Enter

# Add windows for remaining services
for i in "${!SERVICES[@]}"; do
  if [ "$i" -eq 0 ]; then continue; fi
  tmux new-window -t "$SESSION" -n "${SERVICES[$i]}"
  tmux send-keys -t "$SESSION:${SERVICES[$i]}" \
    "hermes chat -q \"Upgrade the 'requests' library to the latest version in the ${SERVICES[$i]} project. Run tests after the upgrade. Report success or the specific test failure.\"" \
    Enter
done

Each service gets its own window inside the dep-upgrade session. Switch between them with Ctrl-b n (next window) or Ctrl-b p (previous).

Step 3: Capture output from a finished agent

Once an agent finishes, capture the pane content to a file:

# Capture the entire scrollback buffer of window "api-gateway" in session "dep-upgrade"
tmux capture-pane -t dep-upgrade:api-gateway -p -S - > /tmp/api-gateway-result.txt

The -p flag prints to stdout (redirect to a file). The -S - flag captures the full scrollback history. Without it, you only get the visible pane content.

This is the pattern for automated result collection: a parent script spawns agents, polls for completion by checking pane contents, and captures results.

Step 4: Worktree mode, isolated git workspaces

When parallel agents operate on the same repository, they risk stepping on each other's file changes. Worktree mode (-w) creates an isolated git worktree for each agent run.

# Agent 1: audit the auth module
hermes chat -q -w /home/molsen/workspace/my-repo \
  "Find all authentication-related code and check for common security issues. Report findings."

# Agent 2: audit the payment module (simultaneously, isolated worktree)
hermes chat -q -w /home/molsen/workspace/my-repo \
  "Find all payment-processing code and check for missing transaction logging. Report findings."

Each -w invocation creates a temporary git worktree under /tmp/hermes-worktree-<random>/. The agent operates on a clean copy of the repo at the current HEAD. Changes made in the worktree are discarded when the agent exits, this is for read-only inspection or for generating reports that the agent writes to a shared location outside the worktree.

For agents that need to commit changes, have them push to a branch:

hermes chat -q -w /home/molsen/workspace/my-repo \
  "Refactor the logging module to use structured logging. Create a branch 'refactor/logging-structured', commit the changes, and push the branch."

Step 5: Resume a session for follow-up

An agent finishes its one-shot task and the session persists. You can resume it interactively to give follow-up instructions:

# Resume the most recent session in interactive mode
hermes --continue

# Or resume a specific session by ID
hermes --resume 20260721_143052_a1b2c3

In the tmux workflow, this means you can attach to a window after the agent finishes, type hermes --continue, and ask it to refine the report, add a section, or fix an error it made. The agent retains the full context of its previous run.

Step 6: Check completion across multiple agents

A polling pattern for a parent script that waits for all agents to finish:

#!/bin/bash
# Poll all windows in a tmux session for a completion marker
check_done() {
  local session="$1"
  local marker="$2"
  local windows=$(tmux list-windows -t "$session" -F "#{window_name}")

  for win in $windows; do
    local content=$(tmux capture-pane -t "$session:$win" -p -S - 2>/dev/null)
    if ! echo "$content" | grep -q "$marker"; then
      return 1  # At least one window is not done
    fi
  done
  return 0  # All windows contain the marker
}

# Wait for all agents to report "COMPLETE" in their output
while ! check_done "dep-upgrade" "COMPLETE"; do
  sleep 10
done

echo "All agents finished"

Have each agent's prompt include "When finished, output 'COMPLETE' on its own line" so the polling script has a reliable signal.

What goes wrong

Mistake	How you notice it	The fix
A tmux session accumulates dozens of stale windows from old runs	tmux list-sessions shows sessions you forgot about, consuming memory	Add a cleanup step to your spawn script: kill the session after capturing results. Or run tmux kill-session -t <old-session> manually. For automated workflows, name sessions with a timestamp and run a cron job that kills sessions older than 24 hours
An agent in a tmux window finishes but the window is still open, and you send a new command by accident	tmux send-keys sends text into the agent's already-finished terminal, which may interpret it as a new interactive prompt	Check the pane content before sending: `tmux capture-pane -t session:win -p
Multiple agents in worktree mode try to push to the same branch name	The second agent's push fails with a non-fast-forward rejection	Use unique branch names per agent: --branch refactor/agent-$(date +%s) or include the agent's task in the branch name
tmux capture-pane returns empty output because the pane history was cleared	You get an empty file or a single line showing the command prompt	Run tmux capture-pane -t session:win -p -S -5000 to capture more history. Increase tmux's history-limit in ~/.tmux.conf: set -g history-limit 50000
An agent spawned via tmux cannot find the hermes binary	The one-shot command fails with "command not found" because tmux inherits a minimal environment	Use the full path: ~/.local/bin/hermes chat -q "..." or source the shell config in the send-keys command: source ~/.bashrc && hermes chat -q "..."

Confirm it worked

Run this script to verify your tmux workflow setup. It creates a session, polls for completion, and captures the final output.

# 1. Create a tmux session with a one-shot agent
tmux new-session -d -s verify-agent
tmux send-keys -t verify-agent \
  'hermes chat -q "List the 5 most recently modified files in the current directory. Output COMPLETE when done."' \
  Enter

# 2. Wait a moment for the agent to start, then check it is running
sleep 5
tmux capture-pane -t verify-agent -p | tail -5

# 3. Poll for the "COMPLETE" marker
while ! tmux capture-pane -t verify-agent -p -S - | grep -q "COMPLETE"; do
  sleep 5
done

# 4. Capture the full output
tmux capture-pane -t verify-agent -p -S - > /tmp/agent-output.txt

# 5. Verify the output contains actual filenames
cat /tmp/agent-output.txt | head -20

# 6. Clean up
tmux kill-session -t verify-agent

If the captured output shows a list of 5 real filenames with modification times, the tmux spawning pattern works end to end.

Next: Webhooks, Event-Driven Agent Runs , triggering agent runs from external systems.