worktree

The worktree extension manages temporary detached git worktrees for isolated execution and persistent branch worktrees for feature work. It is the lifecycle owner for create/remove/prune behavior.

What it does

• creates detached worktrees with git worktree add --detach
• creates persistent branch worktrees with /worktree-create or the worktree_create tool
• removes worktrees with a git-first strategy, then filesystem fallback
• prunes stale managed worktrees on startup
• emits lifecycle events for hook automation
• injects session worktree context into the system prompt when enabled

Session isolation (tallow -w / --worktree)

When you start tallow with -w or --worktree, the CLI launches the session inside a temporary detached worktree and sets:

• TALLOW_WORKTREE_PATH
• TALLOW_WORKTREE_ORIGINAL_CWD

The extension reads those values, emits lifecycle events, and performs best-effort cleanup on session_shutdown.

Branch worktrees (/worktree-create / worktree_create)

Use /worktree-create <branch> [path] to create a persistent worktree for a local branch and move the interactive session into it. If the branch does not exist, tallow creates it from HEAD. If the branch already exists, tallow checks it out in the new worktree.

When no path is provided, tallow uses:

~/dev/<project>_worktrees/<branch-slug>

The worktree_create tool exposes the same flow to the model with required branch and optional baseRef / path parameters. The tool should be called alone because the session transitions into the new worktree after creation.

Subagent isolation (isolation: "worktree")

The subagent tool can run each subagent in its own detached worktree. Precedence is:

1. per-call isolation
2. agent frontmatter isolation
3. _defaults.md frontmatter isolation

Supported value:

• worktree

Hook events

Canonical events:

• worktree_create
• worktree_remove

Claude-compatible aliases:

• WorktreeCreate
• WorktreeRemove

Payload shape:

{
  "worktreePath": "/tmp/tallow-worktree-subagent-abc123-...",
  "repoRoot": "/repo",
  "scope": "session",
  "agentId": "fg_abc123",
  "timestamp": 1739999999999
}

scope is project, session, or subagent. agentId is present for subagent-scoped events.