Build git worktree isolation manager for parallel agent sessions

[frankxai]

Context

Parallel agent sessions (like ComposioHQ/agent-orchestrator) need git worktree isolation so agents don't conflict on file operations.

Requirements

• WorktreeManager class: create, list, cleanup worktrees
• Auto-create worktree per agent session with unique branch
• Auto-cleanup on session end (merge or discard)
• Lock file management to prevent concurrent worktree access
• Integration with Guardian routing (each Guardian gets isolated worktree)
• CLI commands: arcanea-code worktree create|list|cleanup|merge

Architecture

arcanea-code worktree create --session agent-123 --base dev
  → Creates .git/worktrees/agent-123/
  → Checks out branch worktree/agent-123
  → Returns path for agent to work in

arcanea-code worktree merge --session agent-123
  → Merges worktree/agent-123 → dev
  → Cleans up worktree

[m13v]

We built something very similar for running parallel Claude Code agents on the same repo. A few things we learned the hard way:

1. Lock files are essential but tricky - we ended up using tmux sessions as the isolation boundary rather than file-level locks. Each agent gets its own tmux session with a dedicated worktree, and the session name maps to the worktree path. This avoids the whole lock contention problem.

2. Cleanup on crash is the hard part - your auto-cleanup on session end is good for the happy path, but agents crash. We added a periodic garbage collector that checks for orphaned worktrees where the parent process no longer exists.

3. Merge conflicts compound fast - if two agents touch overlapping files, merging back gets ugly. We found it better to assign agents to non-overlapping file scopes upfront rather than trying to resolve conflicts after the fact.

4. Branch naming convention matters - we use a format like worktree/agent-{session-id}/{issue-number} so you can trace exactly what task an agent was working on from the branch name alone.

The pattern of one worktree per agent session has been solid for us. Happy to share more details on the tmux-based orchestration approach if useful.

[m13v]

For reference, here is the tmux-based agent orchestration skill we use for this: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md

It handles session creation, worktree assignment, output monitoring, and crash recovery in a single workflow.

[frankxai]

Worktree manager implemented: create/list/merge/cleanup + /worktree command + tests. Commit 607afb8.

[m13v]

Nice, that was fast. The /worktree command is a great touch for the UX side.

One thing worth stress-testing early: what happens when two agents try to merge back to the same branch at the same time? In our setup we ended up adding a simple lock file check before the merge step to serialize those operations. Saved us from some nasty conflict resolution loops.