/worktree

Isolated git worktrees per PR — named from the story, set up and torn down by the repo's own hooks, claimed by one session at a time.

Invoked by
you with /worktree, or Claude automatically
Arguments
/worktree [on <story|branch|description> | off [name] | list | cleanup | init]
Requires
git · python3 3.11+; optionally gh · short
Pre-approved
Bash · AskUserQuestion · Read
Tags
gitworktreesworkflowshortcut
License
WTFPL-2.0
gh skill install calebstewart/ai-slop worktree --agent claude-code --scope user

Other agents, other scopes, and the copy-and-symlink routes are on the install page.

One git worktree per piece of work, each with its own test environment, and a registry that knows which Claude session is using which tree. Built for running several independent PRs at once without two sessions sharing a checkout, a test database, or a port, and for cleaning up afterwards without guessing.

The work is done by bin/wt, a standalone CLI (Python standard library, nothing to install). The skill tells Claude how to drive it; an editor or a hook can drive it directly.

What it does

Using it

/worktree on sc-123456, /worktree off, /worktree list, /worktree cleanup. It is also model-invoked, so “work on sc-123456 in a worktree” or “I’m done with this tree” is usually enough.

Giving a repository its hooks:

~/.claude/skills/worktree/bin/wt init --local   # stubs in .claude/worktree/, kept out of git

Drop --local to commit the hooks for everyone instead. The hook contract — inputs, outputs, dry runs, warm slots — is in reference/hooks.md.

Install

Install the skill as usual (see the repository README), then check the CLI kept its executable bit: chmod +x ~/.claude/skills/worktree/bin/wt if not.

wt does not need to be on your PATH. The skill runs it from its own directory, and everything else should call it by full path. A symlink is a convenience for typing it yourself; with one in place, wt’s suggested commands use the short name.

Session-start reminder

Optional: a SessionStart hook that mentions trees left by ended sessions, and tells a resumed session which tree it held. It prints nothing when there is nothing to say.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/skills/worktree/bin/wt janitor --hook" }
        ]
      }
    ]
  }
}

Driving it from an editor or a script

Every command takes --json, and nothing prompts; decisions come back as exit codes:

ExitMeaning
0done; for rm/cleanup without --yes, a plan
1error (error, hint in the JSON)
2usage
3held by another live session
4held by an ended session; repeat with --take-over after asking
5refused: unsafe, or a hook was not sure

Inside a Claude session, wt identifies the session from CLAUDE_CODE_SESSION_ID and CLAUDE_PID. Anything else that starts sessions — an editor plugin, say — passes --session <id> --pid <pid of the claude process>. Liveness is that pid together with its start time, so a reused pid never counts as the original session.

wt env [name] prints a tree’s environment as export lines, for starting a process (or a whole session) inside the tree with its environment already set.

Where things are kept

Needs git and python3 3.11+. gh adds PR state to removal plans; short resolves stories that have no branch yet.