Tutorial: Running a Second Hermes Agent in Parallel

Abstract. Hermes runs as many independent instances as you want – one process per terminal session, each with its own conversation history. The collisions happen on the filesystem, not in the agent: two instances editing the same git working tree, racing a shared counter file, or driving the same browser automation port. This tutorial covers the safe pattern for running a second agent on another project while the first one works: its own tmux window, worktree mode for code, explicit boundaries on shared state files, a separate browser port, and optionally a dedicated profile for long-running parallel projects.

Prerequisites

• Hermes installed (any version; commands below match the current CLI).
• A working tmux setup (the multi-window pattern uses it).
• An existing Hermes session running in one pane, and a second project you want to work on at the same time.
• git for the worktree option (only needed if the second agent edits code in the same repository).

Step 1: Give the Second Agent Its Own Window

The one rule that is never optional: the second agent runs in its own terminal, never inside the first agent’s pane. Each Hermes process needs its own PTY and its own session history.

In tmux, press Ctrl-a c to open a new window in the current session, then run hermes there. For a completely separate session (survives closing windows, has its own name):

tmux new-session -d -s projectX -x 120 -y 40 'hermes'

You now have two independent Hermes processes. Check that they are separate processes, not one shared one:

pgrep -fl "hermes"

You should see two PIDs. If you see one, the second window attached to the same process – kill it and start fresh with the tmux new-session form above.

Step 2: Use Worktree Mode When Editing Code

This is the single biggest lever for not stepping on each other. A plain second hermes in another window edits the same git working tree as the first agent; two agents patching the same files means clobbered edits and index conflicts. Hermes has a built-in mode for this:

hermes -w

The -w (worktree) flag creates an isolated git worktree for the second agent – its own branch and working tree, so git does not fight over the same index. Use it whenever the second agent will write code in the same repository the first agent is touching.

If the second project lives outside the shared repo, a plain hermes is fine: separate directories, no shared index. The worktree flag is for same-repo parallelism only.

Step 3: Set Explicit Boundaries on Shared State Files

If both agents follow the same logging and response-ID conventions, they will both want to write a few single-source files. Name them explicitly in the second agent’s opening brief so it does not touch them:

• The response-ID counter (single-line file, appended by every agent that emits response headers) – races between parallel sessions. Tell the second agent to skip the response-header convention, or accept interleaved registry rows.
• The daily log – this one is append-only, so both agents writing to it is safe and expected. The shared contract (AGENTS.md) asks every agent to log there under its own tag.
• Any per-project cursor or state file owned by the first agent.

A one-line brief to the second agent works:

Work only in <project dir>. Do not modify the response counter, the
response registry, or the shared journal. Do not use browser
automation on port 9222. Log your session to the dailylog under your
own tag.

Step 4: Give Browser Automation Its Own Port

The browser automation port (CDP, default 9222) is single-client. Two agents driving the same port corrupt each other’s flows – clicks land in the wrong session, page loads race. If the second agent needs browser automation:

# second agent's browser on a different port
open -a "Brave Browser" --args --remote-debugging-port=9223

The first agent keeps 9222; the second uses 9223. Each agent’s scripts must be pointed at its own port.

Step 5: Use a Dedicated Profile for Long-Running Projects

For a second project that will last days, the cleanest isolation is a separate Hermes profile – its own config, skills, memory, and session history, with zero shared state except the filesystem:

hermes profile create projectX --clone
hermes -p projectX

--clone copies your current settings so the new profile starts working immediately; the two profiles then diverge independently. Overkill for a one-off task, exactly right for a sustained parallel project.

Step 6: For One-Off Tasks, Do Not Spawn at All

A single question or a short task does not need a second interactive session. Use the one-shot mode from the first agent’s own terminal:

hermes chat -q "Summarize the key findings from these notes"

One-shot mode is fire-and-forget, needs no PTY, and cannot collide with anything the interactive session is doing. For longer tasks, run it in the background and check on it when it finishes.

Verification

1. Run pgrep -fl hermes and confirm two PIDs for two interactive sessions (or one PID plus a hermes chat -q subprocess for the one-shot path).
2. In the second window, run git status and confirm the working tree does not show the first agent’s in-flight changes (worktree mode) or, without worktree mode, that the two agents are not both touching the same files.
3. Ask the second agent for a read-only confirmation of its boundaries: “Which files are you allowed to write?” It should name only its own project directory and the shared append-only journal.
4. If both agents use browser automation, confirm the first still owns port 9222 and the second uses a different port: lsof -iTCP:9222 and lsof -iTCP:9223 show separate processes.
5. If you created a profile, confirm isolation with hermes -p projectX /status – it should show the new profile name, not the default.

The pattern in one line: separate window, worktree for code, explicit boundaries on shared files, separate browser port, profile for the long haul, and one-shot mode when a full session is overkill.