Problem
Running multiple graff agents/sessions in the same checkout — or many parallel subagents/workflow tasks — means their file edits collide. A user driving ~10 agents at once needs each to operate on an isolated copy of the tree so one agent's edit_file/write_file never clobbers another's.
Today graff has no file isolation between concurrent sessions: they all share the cwd. (Subagents share context-isolation but not file isolation.)
Proposal — git worktree isolation (à la Claude Code's --worktree)
A git worktree is a separate working dir + branch sharing the same repo history. Each session/agent in its own worktree → edits never touch another's files.
graff --worktree <name> (and -w): create an isolated worktree under .graff/worktrees/<name>/ on branch worktree-<name>, branched from origin/HEAD (fall back to local HEAD), and start the session there. Omitting the name auto-generates one.- Subagent / workflow isolation: an
isolation: worktree option so parallel subagents (the swarm) each get a temporary worktree, auto-removed if they finish with no changes. This is the key one for "10 agents coding at once."
.worktreeinclude (gitignore-syntax): copy gitignored files (.env, .env.local, secrets) into each new worktree, since a fresh checkout lacks untracked files.- Cleanup: on exit, auto-remove a worktree with no changes/commits; keep (prompt) if there are uncommitted changes, untracked files, or new commits. Lock a worktree while its agent runs so a concurrent sweep can't remove it.
- Non-git VCS:
WorktreeCreate/WorktreeRemove hooks to override the default git worktree logic (SVN/Perforce/hg).
- Add
.graff/worktrees/ to .gitignore.
Notes
- Reference design: Claude Code's "Run parallel sessions with worktrees" docs (the
--worktree flag, subagent isolation: worktree, .worktreeinclude, cleanup, WorktreeCreate hook).
- Per the TUI-first rule, land it in the Zig harness first, then mirror to the GUI (the desktop app can create a worktree per session automatically).
Acceptance
graff --worktree <name> runs the session in an isolated worktree; edits don't touch the main checkout.- Parallel subagents can each run in their own worktree (
isolation: worktree), so N agents edit without collisions.
.worktreeinclude copies matched gitignored files into new worktrees.- Clean exit removes change-free worktrees; dirty ones are kept.
Problem
Running multiple graff agents/sessions in the same checkout — or many parallel subagents/workflow tasks — means their file edits collide. A user driving ~10 agents at once needs each to operate on an isolated copy of the tree so one agent's
edit_file/write_filenever clobbers another's.Today graff has no file isolation between concurrent sessions: they all share the cwd. (Subagents share context-isolation but not file isolation.)
Proposal — git worktree isolation (à la Claude Code's
--worktree)A git worktree is a separate working dir + branch sharing the same repo history. Each session/agent in its own worktree → edits never touch another's files.
graff --worktree <name>(and-w): create an isolated worktree under.graff/worktrees/<name>/on branchworktree-<name>, branched fromorigin/HEAD(fall back to local HEAD), and start the session there. Omitting the name auto-generates one.isolation: worktreeoption so parallel subagents (the swarm) each get a temporary worktree, auto-removed if they finish with no changes. This is the key one for "10 agents coding at once.".worktreeinclude(gitignore-syntax): copy gitignored files (.env,.env.local, secrets) into each new worktree, since a fresh checkout lacks untracked files.WorktreeCreate/WorktreeRemovehooks to override the defaultgit worktreelogic (SVN/Perforce/hg)..graff/worktrees/to.gitignore.Notes
--worktreeflag, subagentisolation: worktree,.worktreeinclude, cleanup,WorktreeCreatehook).Acceptance
graff --worktree <name>runs the session in an isolated worktree; edits don't touch the main checkout.isolation: worktree), so N agents edit without collisions..worktreeincludecopies matched gitignored files into new worktrees.