Wiki / concepts / wiki

Worktree per task

Give each branch (feature, code review, parallel AI agent) its own git worktree checkout so switching never means stashing, WIP commits, or losing unstaged context. That's why worktrees became the default isolation unit for running several agents at once.

The friction is that files outside git don't follow the worktree: .env secrets, node_modules, local config. The fix pattern is to declare them once (copy mutable files like env, symlink heavy immutable ones like node_modules) and have a tool apply them on create, with a sync command when the list changes. workmux does this through .workmux.yaml. sam-natale argues it's worth it "with no AI features" at all.

omer-hamerman gives the short case: work on several changes at once from separate checkouts, no stashing, and git's own interface for it is poor, which is why wrappers like Worktrunk and workmux exist. workmux keeps trees in a sibling <project>__worktrees directory and cleans up merged ones in one sweep.

Related: session-per-worktree, agent-native-multiplexer, augment-over-replace.

Source: report ยท report

Factory version (zazencodes, Nov 2026): one orchestrator session runs up to three software-factory jobs at once, each in its own worktree and branch, with one PR that closes its GitHub issue (report).

Linked from

Agent-native multiplexerAugment over replaceSession per worktreeSoftware factory