Skip to content

feat: git worktree isolation for parallel CLI sessions (--worktree / -w)#654

Merged
teknium1 merged 2 commits into
mainfrom
feat/worktree-isolation
Mar 8, 2026
Merged

feat: git worktree isolation for parallel CLI sessions (--worktree / -w)#654
teknium1 merged 2 commits into
mainfrom
feat/worktree-isolation

Conversation

@teknium1

@teknium1 teknium1 commented Mar 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Add a --worktree (-w) flag to the hermes CLI that creates an isolated git worktree for the session. This allows running multiple hermes-agent instances concurrently on the same repo without file collisions, branch conflicts, or corrupted git state.

Closes #652

How It Works

On startup with -w:

  1. Detects git repo root
  2. Creates .worktrees/<hermes-uuid>/ with its own branch (hermes/hermes-<uuid>)
  3. Sets TERMINAL_CWD to the worktree path
  4. Copies files from .worktreeinclude (gitignored files like .env, .venv/)
  5. Auto-adds .worktrees/ to .gitignore
  6. Injects system prompt note so the agent knows it's in a worktree

On exit:

  • Clean worktree → auto-removes worktree and branch
  • Dirty worktree (uncommitted changes) → warns and keeps for manual recovery

Config support:

# In ~/.hermes/config.yaml
worktree: true  # Always create a worktree (equivalent to always passing -w)

Usage

# 10 terminal windows, each isolated:
hermes -w -q "Fix issue #628"
hermes -w -q "Review PR #620"
hermes -w -q "Implement feature X"
# ... all working on the same repo, zero collisions

# Interactive mode:
hermes -w

# .worktreeinclude — copy gitignored files to worktrees:
echo ".env" > .worktreeinclude
echo ".venv/" >> .worktreeinclude

Changes

  • cli.py: Added --worktree/-w flag, worktree setup/cleanup functions, config integration, system prompt injection (~170 lines)
  • tests/test_worktree.py: 17 tests covering repo detection, creation, independence, cleanup (clean/dirty), .worktreeinclude, .gitignore management, and 10 concurrent worktrees

Test Results

17 new tests passed
2149 total passed (full suite), 1 pre-existing failure (unrelated clipboard test)

teknium1 added 2 commits March 7, 2026 20:51
@teknium1
feat: git worktree isolation for parallel CLI sessions (--worktree / -w)
8d719b1 
Add a --worktree (-w) flag to the hermes CLI that creates an isolated
git worktree for the session. This allows running multiple hermes-agent
instances concurrently on the same repo without file collisions.

How it works:
- On startup with -w: detects git repo, creates .worktrees/<session>/
  with its own branch (hermes/<session-id>), sets TERMINAL_CWD to it
- Each agent works in complete isolation — independent HEAD, index,
  and working tree, shared git object store
- On exit: auto-removes worktree and branch if clean, warns and
  keeps if there are uncommitted changes
- .worktreeinclude file support: list gitignored files (.env, .venv/)
  to auto-copy/symlink into new worktrees
- .worktrees/ is auto-added to .gitignore
- Agent gets a system prompt note about the worktree context
- Config support: set worktree: true in config.yaml to always enable

Usage:
  hermes -w                      # Interactive mode in worktree
  hermes -w -q "Fix issue #123"  # Single query in worktree
  # Or in config.yaml:
  worktree: true

Includes 17 tests covering: repo detection, worktree creation,
independence verification, cleanup (clean/dirty), .worktreeinclude,
.gitignore management, and 10 concurrent worktrees.

Closes #652
@teknium1
fix: wire worktree flag into hermes CLI entry point + docs + tests
4be7834 
Critical fixes:
- Add --worktree/-w to hermes_cli/main.py argparse (both chat
  subcommand and top-level parser) so 'hermes -w' works via the
  actual CLI entry point, not just 'python cli.py -w'
- Pass worktree flag through cmd_chat() kwargs to cli_main()
- Handle worktree attr in bare 'hermes' and --resume/--continue paths

Bug fixes in cli.py:
- Skip worktree creation for --list-tools/--list-toolsets (wasteful)
- Wrap git worktree subprocess.run in try/except (crash on timeout)
- Add stale worktree pruning on startup (_prune_stale_worktrees):
  removes clean worktrees older than 24h left by crashed/killed sessions

Documentation updates:
- AGENTS.md: add --worktree to CLI commands table
- cli-config.yaml.example: add worktree config section
- website/docs/reference/cli-commands.md: add to core commands
- website/docs/user-guide/cli.md: add usage examples
- website/docs/user-guide/configuration.md: add config docs

Test improvements (17 → 31 tests):
- Stale worktree pruning (prune old clean, keep recent, keep dirty)
- Directory symlink via .worktreeinclude
- Edge cases (no commits, not a repo, pre-existing .worktrees/)
- CLI flag/config OR logic
- TERMINAL_CWD integration
- System prompt injection format
@teknium1 teknium1 merged commit 5ee9b67 into main Mar 8, 2026
1 check passed
@teknium1 teknium1 mentioned this pull request Mar 8, 2026
Closed
@teknium1 teknium1 deleted the feat/worktree-isolation branch March 8, 2026 05:39
angelburgosrosado pushed a commit to angelburgosrosado/hermes-agent that referenced this pull request Apr 27, 2026
@teknium1
Merge PR NousResearch#654: feat: git worktree isolation for parallel …
c37ee9e 
…CLI sessions (--worktree / -w)

Adds --worktree (-w) flag to hermes CLI for isolated git worktree sessions.
Multiple agents can work on the same repo concurrently without collisions.

Closes NousResearch#652
@ik-svc-oc ik-svc-oc mentioned this pull request May 2, 2026
Merged
2 tasks
02356abc pushed a commit to 02356abc/hermes-agent that referenced this pull request May 14, 2026
@teknium1
Merge PR NousResearch#654: feat: git worktree isolation for parallel …
2bc1334 
…CLI sessions (--worktree / -w)

Adds --worktree (-w) flag to hermes CLI for isolated git worktree sessions.
Multiple agents can work on the same repo concurrently without collisions.

Closes NousResearch#652
olympus-terminal pushed a commit to olympus-terminal/hermes-agent that referenced this pull request May 16, 2026
@teknium1
Merge PR NousResearch#654: feat: git worktree isolation for parallel …
377ed4e 
…CLI sessions (--worktree / -w)

Adds --worktree (-w) flag to hermes CLI for isolated git worktree sessions.
Multiple agents can work on the same repo concurrently without collisions.

Closes NousResearch#652
Egavasyug pushed a commit to Egavasyug/hermes-agent that referenced this pull request Jun 10, 2026
@teknium1
Merge PR NousResearch#654: feat: git worktree isolation for parallel …
e8b8d30 
…CLI sessions (--worktree / -w)

Adds --worktree (-w) flag to hermes CLI for isolated git worktree sessions.
Multiple agents can work on the same repo concurrently without collisions.

Closes NousResearch#652
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Feature: Git Worktree Isolation for Parallel CLI Sessions (hermes -w)

1 participant

@teknium1