wtcode 0.4.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

wtcode/__init__.py

@@ -1,3 +1,3 @@
 """wtcode -- launch your favorite code tool in a git worktree."""
 
-__version__ = "0.4.0"
+__version__ = "0.7.0"

wtcode/wtcode.sh

@@ -5,6 +5,35 @@
 # Created: 2026-02-03
 set -eu
 shopt -s extglob
+
+# detect well-known AI coding agents via the env vars they set on their own
+# subprocesses -- send-keys/AppleScript fire into whatever pane/tab/window
+# happens to be current, which is unsafe to do behind an agent's back while
+# it's working (it may be a pane/window the user is watching, or one running
+# an unrelated task). exec is always safe: it just replaces the agent's own
+# child process.
+--running-under-coding-agent() {
+  [[ -n ${CLAUDECODE:-} || -n ${CURSOR_AGENT:-} || -n ${GEMINI_CLI:-} ||
+     -n ${CODEX_SANDBOX:-} || -n ${CODEX_SANDBOX_NETWORK_DISABLED:-} ]]
+}
+
+# declare all WTCODE_* env vars and their defaults in one place
+: ${WTCODE_TOOL:=${WTCODE_CMD:-}}   # WTCODE_CMD: deprecated alias
+: ${WTCODE_USE_CURRENT_BRANCH:=false}
+: ${WTCODE_BASE_REF:=}          # ref to fork new branches from (also: --base REF)
+: ${WTCODE_BRANCH_SCOPE:=}      # initial picker scope: all|worktree|local|remote
+: ${WTCODE_BRANCH_ORDER:=}      # initial picker order: recent|name|full
+# where the picker remembers its last state; set to empty to disable
+: ${WTCODE_STATE_FILE=${XDG_STATE_HOME:-$HOME/.local/state}/wtcode/state}
+if --running-under-coding-agent; then
+  : ${WTCODE_TMUX_MODE:=exec}
+  : ${WTCODE_TERMINAL_MODE:=exec}
+else
+  : ${WTCODE_TMUX_MODE:=send-keys}
+  : ${WTCODE_TERMINAL_MODE:=send-keys}
+fi
+: ${WTCODE_DEBUG:=}
+
 ${WTCODE_DEBUG:+set -x}
 
 --msg() { echo "wtcode: $*" >&2; }
@@ -17,16 +46,18 @@ ${WTCODE_DEBUG:+set -x}
     tr '[:upper:]' '[:lower:]' |   # lowercase
     sed 's/[^a-z0-9/_-]/-/g' |     # replace non-alnum to hyphens
     sed 's/--*/-/g' |              # collapse consecutive hyphens
-    sed 's/^-//; s/-$//'           # trim leading/trailing hyphens
+    sed 's|//*|/|g' |              # collapse consecutive slashes
+    sed 's|-*/-*|/|g' |            # no hyphens adjacent to slashes
+    sed 's|^[-/]*||; s|[-/]*$||'   # trim leading/trailing hyphens/slashes
 }
 
-WTCODE_VERSION=0.4.0
+WTCODE_VERSION=0.7.0
 --version() { echo "wtcode $WTCODE_VERSION"; }
 --help() {
   cat <<USAGE
 wtcode $WTCODE_VERSION -- launch a code tool in a git worktree
 
-Usage: wtcode [BRANCH] [CMD [CMD-ARGS...]]
+Usage: wtcode [--base REF] [BRANCH] [CMD [CMD-ARGS...]]
        wtcode --exec CMD [CMD-ARGS...]
 
   BRANCH     Git branch or worktree name to switch to.
@@ -35,24 +66,59 @@ Usage: wtcode [BRANCH] [CMD [CMD-ARGS...]]
              (use multiple colons to avoid fzf matching, e.g., :::my-branch
              or my-branch:::).
 
-  CMD        Command to launch in the worktree (default: \$WTCODE_CMD,
-             or first available of: ${WTCODE_CMDS_TO_TRY[*]}, \$SHELL).
+  CMD        Command to launch in the worktree (default: \$WTCODE_TOOL,
+             or first available of: ${WTCODE_TOOLS_TO_TRY[*]}, \$SHELL).
 
   --exec     Skip branch argument; select interactively, then launch CMD.
 
+  --base REF Fork a brand-new branch from REF (same as \$WTCODE_BASE_REF).
+
+Interactive picker keys (when BRANCH is omitted):
+  ctrl-s     scope: all, worktree, local, remote (all and worktree also show and
+             match a worktree directory that drifted from its branch name
+             or sits outside the main checkout and worktrees root)
+  ctrl-o     order: recent, name (remote shown as a suffix), remote/name
+  ctrl-r     base for a new branch: the default, the current branch (or
+             origin/HEAD, when that differs from the default)
+  ctrl-t     tool: nested picker of installed tools and recent commands;
+             type a new command/args to launch it (unless CMD was given)
+  alt-enter  create a new branch named after what you typed (never the
+             highlighted one); plain Enter does that too when nothing matches
+  ctrl-l     git remote update, then reload
+  Changes made in the picker are remembered for next time, even if canceled.
+
 Environment variables:
-  WTCODE_CMD             Default tool to launch (e.g., claude, lazygit, vim)
+  WTCODE_TOOL            Default tool to launch (e.g., claude, lazygit, vim); WTCODE_CMD is a deprecated alias
+  WTCODE_USE_CURRENT_BRANCH
+                         When creating a brand-new branch, fork it from the
+                         current HEAD instead of the default: origin/HEAD
+                         (falling back to origin/main, then origin/master)
+  WTCODE_BASE_REF        Fork brand-new branches from this ref (overrides the above)
+  WTCODE_BRANCH_SCOPE    Initial picker scope (all|worktree|local|remote)
+  WTCODE_BRANCH_ORDER    Initial picker order (recent|name|full)
+  WTCODE_STATE_FILE      Where the picker remembers its last state
+                         (default: \$XDG_STATE_HOME/wtcode/state; empty disables)
   WTCODE_TMUX_MODE       When in tmux, control how the tool is launched:
-                           send-keys    - send command to current pane (default in tmux)
+                           send-keys    - send command to current pane (default in tmux,
+                                          unless run by a known AI coding agent -- see below)
                            split-window - create split pane with send-keys
                            new-window   - create new window with send-keys
                            exec         - exec the tool directly (opt out of send-keys)
   WTCODE_TERMINAL_MODE   Outside tmux, control how the tool is launched:
                            send-keys    - reuse the current tab/window via AppleScript
-                                          (default; macOS only). Terminal.app and Ghostty
-                                          1.3+ use their own scripting support; any other
-                                          terminal falls back to simulated keystrokes
+                                          (default; macOS only, unless run by a known AI
+                                          coding agent -- see below). Terminal.app and
+                                          Ghostty 1.3+ use their own scripting support;
+                                          any other terminal falls back to simulated
+                                          keystrokes
                            exec         - exec the tool directly (opt out of send-keys)
+
+                         When wtcode is invoked by a known AI coding agent (detected via
+                         CLAUDECODE, CURSOR_AGENT, GEMINI_CLI, CODEX_SANDBOX, or
+                         CODEX_SANDBOX_NETWORK_DISABLED), both modes default to exec
+                         instead of send-keys, since send-keys/AppleScript would inject
+                         keystrokes into a pane/tab/window the agent doesn't control while
+                         it's still working. Set the env var explicitly to override.
   WTCODE_DEBUG           Enable debug tracing when set
   GIT_WORKTREE_ROOT      Override the directory where worktrees are created
 
@@ -62,18 +128,467 @@ Examples:
   wtcode feature-x claude --resume  # launch claude with --resume
   wtcode --exec claude --resume     # select interactively, launch claude --resume
   wtcode :new-feature               # create new branch and worktree
-  WTCODE_CMD=cursor wtcode feature  # use cursor as the default tool
+  WTCODE_TOOL=cursor wtcode feature  # use cursor as the default tool
 USAGE
 }
 
 # commands to try as default, in order of preference
-WTCODE_CMDS_TO_TRY=(
-    ${WTCODE_CMD:-}
+WTCODE_TOOLS_TO_TRY=(
+    $WTCODE_TOOL
     claude
     aider
     codex
 )
 
+###############################################################################
+## --default-base-ref -- ref to fork a brand-new branch from
+###############################################################################
+# defaults to origin/HEAD (falling back to origin/main, then origin/master),
+# so new worktrees start from the repo's default branch instead of whatever
+# happens to be checked out where wtcode was invoked. set
+# WTCODE_USE_CURRENT_BRANCH=true to restore the old behavior of forking from
+# the current HEAD. only consults local remote-tracking refs -- never
+# touches the network.
+--default-base-ref() {
+  if [[ -n $WTCODE_BASE_REF ]]; then
+    echo "$WTCODE_BASE_REF"
+    return
+  fi
+  if [[ $WTCODE_USE_CURRENT_BRANCH == true ]]; then
+    git rev-parse HEAD
+    return
+  fi
+  local ref
+  for ref in origin/HEAD origin/main origin/master; do
+    git rev-parse --verify -q "$ref" &>/dev/null && { echo "$ref"; return; }
+  done
+  git rev-parse HEAD
+}
+
+###############################################################################
+## interactive picker support -- remembered state, key-binding callbacks
+###############################################################################
+# The fzf picker lets you cycle some options with key bindings:
+#   ctrl-s scope   ctrl-o order   ctrl-r base ref   ctrl-l update
+#   alt-enter  create a new branch named after what you typed, not the highlighted one
+#   ctrl-t tool: opens a nested picker of installed tools and recently
+#           launched commands; type anything to launch a new command/args
+# The current values live in small files under a temp dir ($1 of the --fzf-*
+# callbacks, which fzf runs as separate processes); every change is also saved
+# to $WTCODE_STATE_FILE right away, for next time. none of this is touched when
+# a BRANCH is given on the command line.
+
+WTCODE_SCOPES=(all worktree local remote)
+WTCODE_ORDERS=(recent name full)   # full: sort by remote/name, name: by name alone
+
+--self() {
+  local src=${BASH_SOURCE[0]}
+  echo "$(cd "$(dirname "$src")" && pwd)/$(basename "$src")"
+}
+
+# --state-get KEY -- last remembered value (empty if none)
+--state-get() {
+  [[ -n $WTCODE_STATE_FILE && -r $WTCODE_STATE_FILE ]] || return 0
+  sed -n "s/^$1=//p" "$WTCODE_STATE_FILE" | tail -1
+}
+
+# --state-save KEY=VALUE... -- remember values, keeping the other keys
+--state-save() {
+  [[ -n $WTCODE_STATE_FILE ]] || return 0
+  {
+    mkdir -p "$(dirname "$WTCODE_STATE_FILE")"
+    local tmp=$WTCODE_STATE_FILE.$$ kv
+    { [[ -r $WTCODE_STATE_FILE ]] && cat "$WTCODE_STATE_FILE"; true; } > "$tmp"
+    for kv; do
+      grep -v "^${kv%%=*}=" "$tmp" > "$tmp.2" || true
+      printf '%s\n' "$kv" >> "$tmp.2"
+      mv "$tmp.2" "$tmp"
+    done
+    mv "$tmp" "$WTCODE_STATE_FILE"
+  } 2>/dev/null || --msg "could not save state to $WTCODE_STATE_FILE"
+}
+
+# --pick-valid VALUE DEFAULT CHOICES... -- VALUE if among CHOICES, else DEFAULT
+--pick-valid() {
+  local v=$1 d=$2 c; shift 2
+  for c; do [[ $c == "$v" ]] && { echo "$v"; return; }; done
+  echo "$d"
+}
+
+# --next-in-cycle CURRENT ITEMS... -- the item after CURRENT, wrapping around
+--next-in-cycle() {
+  local cur=$1 item take=false; shift
+  for item; do
+    $take && { echo "$item"; return; }
+    [[ $item == "$cur" ]] && take=true
+  done
+  echo "$1"
+}
+
+# --base-ref-for MODE -- the ref a new branch is forked from in each base mode
+--base-ref-for() {
+  case $1 in
+    current) echo HEAD ;;
+    origin)  git rev-parse --verify -q origin/HEAD &>/dev/null && echo origin/HEAD || --default-base-ref ;;
+    *)       --default-base-ref ;;
+  esac
+}
+
+# --base-modes -- the distinct bases ^r cycles: default, current branch, and
+# origin/HEAD (only when that isn't what default already is)
+--base-modes() {
+  local def head; def=$(--default-base-ref); head=$(git rev-parse HEAD 2>/dev/null) || head=
+  echo default
+  [[ $def == "$head" ]] || echo current   # default fell back to HEAD: same thing
+  [[ $(--base-ref-for origin) == "$def" ]] || echo origin
+}
+
+# --base-label MODE -- "<exact branch> (why)", what a new branch would fork from
+--base-label() {
+  local ref name
+  case $1 in
+    current) name=$(git branch --show-current 2>/dev/null); echo "${name:-HEAD} (current)" ;;
+    origin)  echo "$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo origin/HEAD) (origin/HEAD)" ;;
+    *)
+      ref=$(--default-base-ref)
+      if [[ -z $WTCODE_BASE_REF && $ref =~ ^[0-9a-f]{40}$ ]]; then name=$(git branch --show-current 2>/dev/null); name=${name:-HEAD}   # (the fallback to HEAD)
+      elif [[ $ref == origin/HEAD ]]; then name=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo "$ref")
+      else name=$ref
+      fi
+      echo "$name (default)" ;;
+  esac
+}
+
+# --split-command STRING -- shell-like words (quotes and backslashes), NUL-separated
+--split-command() {
+  local s=$1 i=0 c q= word= started=false
+  while (( i < ${#s} )); do
+    c=${s:i:1}
+    if [[ $q == "'" ]]; then
+      if [[ $c == "'" ]]; then q=; else word+=$c; fi
+    elif [[ $q == '"' ]]; then
+      if [[ $c == '"' ]]; then q=
+      elif [[ $c == '\' && ${s:i+1:1} == ['"\$`'] ]]; then word+=${s:i+1:1}; i=$((i+1))
+      else word+=$c
+      fi
+    else
+      case $c in
+        "'"|'"') q=$c; started=true ;;
+        '\')     word+=${s:i+1:1}; i=$((i+1)); started=true ;;
+        [[:space:]]) if $started; then printf '%s\0' "$word"; word=; started=false; fi ;;
+        *)       word+=$c; started=true ;;
+      esac
+    fi
+    i=$((i+1))
+  done
+  if $started; then printf '%s\0' "$word"; fi
+}
+
+# --available-tools -- installed tools worth offering, one per line
+--available-tools() {
+  local c seen=' '
+  for c in ${WTCODE_TOOL:+"$WTCODE_TOOL"} "${WTCODE_TOOLS_TO_TRY[@]}" "${SHELL:-bash}"; do
+    [[ -n $c && $seen != *" $c "* ]] || continue
+    # an explicit $WTCODE_TOOL is always offered; the rest only if installed
+    if [[ $c == "${WTCODE_TOOL-}" ]] || type "$c" &>/dev/null; then
+      echo "$c"; seen+="$c "
+    fi
+  done
+}
+
+# --fzf-init -- make the state dir for one picker session, print its path
+--fzf-init() {
+  local dir v
+  dir=$(mktemp -d "${TMPDIR:-/tmp}/wtcode.XXXXXX")
+  # env vars/args win over what was remembered
+  v=${WTCODE_BRANCH_SCOPE:-$(--state-get scope)}
+  --pick-valid "$v" all "${WTCODE_SCOPES[@]}" > "$dir/scope"
+  v=${WTCODE_BRANCH_ORDER:-$(--state-get order)}
+  --pick-valid "$v" recent "${WTCODE_ORDERS[@]}" > "$dir/order"
+  if [[ -n $WTCODE_BASE_REF || $WTCODE_USE_CURRENT_BRANCH == true ]]; then
+    echo default > "$dir/base"
+  else
+    --pick-valid "$(--state-get base)" default $(--base-modes) > "$dir/base"
+  fi
+  --base-label "$(<"$dir/base")" > "$dir/base_label"
+  if [[ -n ${WTCODE_TOOL_FIXED-} ]]; then
+    echo "$WTCODE_TOOL_FIXED" > "$dir/tool_fixed"
+  else
+    # initial: $WTCODE_TOOL, else the last used command if still installed,
+    # else the first installed tool
+    v=${WTCODE_TOOL:-$(--state-get tool)}
+    [[ -n $WTCODE_TOOL ]] || type "${v%% *}" &>/dev/null || v=$(--available-tools | head -1)
+    printf '%s\n' "$v" > "$dir/tool"
+  fi
+  echo "$dir"
+}
+
+# --fzf-commit DIR -- apply the final picker state (changes were already saved
+# as they were made, so they survive canceling too)
+--fzf-commit() {
+  local dir=$1 base tool
+  base=$(<"$dir/base")
+  [[ $base == default ]] || WTCODE_PICKED_BASE=$(--base-ref-for "$base")   # (not WTCODE_BASE_REF: that may be exported to the tool)
+  if [[ -r $dir/tool ]]; then
+    tool=$(<"$dir/tool")
+    WTCODE_PICKED_TOOL=$tool
+    --history-add "$tool"
+  fi
+}
+
+# --fzf-cycle DIR KIND -- advance scope|order|base|tool to its next value
+--fzf-cycle() {
+  local dir=$1 kind=$2 choices
+  case $kind in
+    scope) choices=("${WTCODE_SCOPES[@]}") ;;
+    order) choices=("${WTCODE_ORDERS[@]}") ;;
+    base)  choices=($(--base-modes)) ;;
+  esac
+  --next-in-cycle "$(<"$dir/$kind")" "${choices[@]}" > "$dir/$kind.new"
+  mv "$dir/$kind.new" "$dir/$kind"
+  # a scope/order reload cancels an update in flight, so its marker must go
+  [[ $kind == base ]] || rm -f "$dir/updating"
+  --state-save "$kind=$(<"$dir/$kind")"   # remembered right away, even if the picker is canceled
+  [[ $kind == base ]] && --base-label "$(<"$dir/base")" > "$dir/base_label"
+  return 0
+}
+
+# recently launched commands, most recent first
+--history-file() { [[ -n $WTCODE_STATE_FILE ]] && echo "$WTCODE_STATE_FILE.cmds" || true; }
+--history-add() {
+  local f; f=$(--history-file); [[ -n $f && -n $1 ]] || return 0
+  { { printf '%s\n' "$1"; grep -vxF -- "$1" "$f" 2>/dev/null || true; } | head -20 > "$f.new" && mv "$f.new" "$f"; } 2>/dev/null || true
+}
+
+# --fzf-pick-tool DIR -- nested picker for the tool (run via ctrl-t)
+# lists recent commands and installed tools; typing text that matches nothing
+# (or pressing alt-enter) takes the typed text as-is, e.g. `claude --resume`
+--fzf-pick-tool() {
+  local dir=$1 f out query key choice prompt='tool> '
+  [[ -e $dir/in_popup ]] || prompt='wtcode tool> '
+  f=$(--history-file)
+  out=$(
+    { [[ -n $f && -r $f ]] && cat "$f"; --available-tools; } | awk '!seen[$0]++' |
+    fzf --print-query --expect alt-enter --prompt "$prompt" --height 100% --layout reverse \
+        --header 'Pick a tool/recent command, or type a new command with args.
+enter: pick highlighted (or typed text if nothing matches)   alt-enter: use typed text as-is' ||
+    true
+  )
+  # fzf prints just the query when nothing matches, else query, key, choice
+  { read -r query || true; read -r key || true; read -r choice || true; } <<< "$out"
+  if [[ $key == alt-enter || -z $choice ]]; then choice=$query; fi
+  choice=${choice#"${choice%%[![:space:]]*}"} choice=${choice%"${choice##*[![:space:]]}"}   # trim
+  if [[ -n $choice ]]; then
+    printf '%s\n' "$choice" > "$dir/tool"
+    # remembered right away: it's a deliberate choice that should survive
+    # canceling the main picker
+    --state-save tool="$choice"
+    --history-add "$choice"
+  fi
+  return 0
+}
+
+# --tmux-at-least MAJOR MINOR -- is the running tmux at least this version?
+--tmux-at-least() {
+  local v; v=$(tmux -V 2>/dev/null) || return 1
+  [[ $v =~ ([0-9]+)\.([0-9]+) ]] || return 1
+  (( BASH_REMATCH[1] > $1 || (BASH_REMATCH[1] == $1 && BASH_REMATCH[2] >= $2) ))
+}
+
+# --fzf-pick DIR -- run the picker, print fzf's output (query, then selection).
+# inside tmux, fzf's own --tmux is NOT used: since tmux 3.7/fzf 0.7x it opens
+# a floating *pane*, whose keys go through tmux's key tables, so the prefix
+# (e.g. OPTMUX's C-t) and root bindings (bind -n) get swallowed before fzf
+# sees them. a display-popup overlay hands every key to the program instead.
+--fzf-pick() {
+  local dir=$1
+  if [[ -n ${TMUX:-} ]] && type tmux &>/dev/null && --tmux-at-least 3 3; then
+    local self cmd envs=() v
+    self=$(--self)
+    # started marks that the popup really ran: if it was then dismissed (Esc on
+    # the popup, client detached, ...) that's a cancel, NOT a reason to fall
+    # back to showing a second, different picker
+    printf -v cmd ': > %q; %q %q --fzf-run %q > %q' "$dir/started" "$BASH" "$self" "$dir" "$dir/out"
+    : > "$dir/in_popup"
+    # a popup doesn't inherit our environment; pass along what matters
+    # (not exported, but the key-binding callbacks need them)
+    envs+=(-e "WTCODE_BASE_REF=$WTCODE_BASE_REF" -e "WTCODE_USE_CURRENT_BRANCH=$WTCODE_USE_CURRENT_BRANCH")
+    for v in $(compgen -e); do
+      [[ $v =~ ^(PATH|HOME|SHELL|USER|LOGNAME|TMPDIR|LANG|LC_[A-Z]+|XDG_[A-Z_]+|WTCODE_[A-Z_]+|GIT_[A-Z_]+|FZF_[A-Z_]+)$ ]] &&
+        envs+=(-e "$v=${!v}")
+    done
+    tmux display-popup -E ${TMUX_PANE:+-t "$TMUX_PANE"} -d "$PWD" -w 90% -h 70% -b rounded \
+         -T ' wtcode ' ${envs[@]+"${envs[@]}"} "$cmd" 2>/dev/null || true
+    if [[ -e $dir/started ]]; then
+      cat "$dir/out" 2>/dev/null || true   # (empty when dismissed or canceled)
+      return 0
+    fi
+    rm -f "$dir/in_popup"   # no client to show a popup on, etc.: fall back
+  fi
+  --fzf-run "$dir"
+}
+
+# --fzf-run DIR -- the picker itself (also what runs inside the tmux popup)
+--fzf-run() {
+  local dir=$1 self b dir_q
+  { set +x; } &>/dev/null
+  self=$(--self)
+  printf -v b '%q %q' "$BASH" "$self"   # command prefix for the key bindings
+  printf -v dir_q '%q' "$dir"
+  local opts=() prompt='branch> '
+  # a popup is titled ' wtcode '; anywhere else the prompt says what this is
+  [[ -e $dir/in_popup ]] || { opts+=(--tmux 90%,70%); prompt="wtcode $prompt"; }
+  if [[ ! -e $dir/tool_fixed ]]; then
+    opts+=(--bind "ctrl-t:execute($b --fzf-pick-tool $dir_q)+transform-header($b --fzf-header $dir_q)")
+  fi
+  --list-branches "$(<"$dir/scope")" "$(<"$dir/order")" |
+  WTCODE_BASE_REF=$WTCODE_BASE_REF WTCODE_USE_CURRENT_BRANCH=$WTCODE_USE_CURRENT_BRANCH \
+  fzf --ansi --color --print-query --delimiter=$'\t' --with-nth=2 --nth=1 \
+      --preview "$b --fzf-preview {1} {3}" \
+      --preview-window 'right,50%,wrap,<120(down,40%,wrap)' \
+      --header "$(--fzf-header "$dir")" \
+      --bind "ctrl-s:execute-silent($b --fzf-cycle $dir_q scope)+reload($b --fzf-list $dir_q)" \
+      --bind "ctrl-o:execute-silent($b --fzf-cycle $dir_q order)+reload($b --fzf-list $dir_q)" \
+      --bind "ctrl-r:execute-silent($b --fzf-cycle $dir_q base)+transform-header($b --fzf-header $dir_q)" \
+      --bind "ctrl-l:execute-silent(: > $dir_q/updating)+transform-header($b --fzf-header $dir_q)+reload($b --fzf-update $dir_q)" \
+      --bind "alt-enter:execute-silent(: > $dir_q/force_new)+accept" \
+      --bind "load:transform-header($b --fzf-header $dir_q)" \
+      ${opts[@]+"${opts[@]}"} \
+      --prompt "$prompt" || true
+}
+
+# --fzf-preview BRANCH [LINE] -- preview pane: the picker's one-line summary,
+# then what BRANCH has relative to the base new branches fork from
+# (git diff --stat BASE...BRANCH, plus the commits that are only on BRANCH)
+--fzf-preview() {
+  local branch=${1-} line=${2-} base b=$'\e[1m' r=$'\e[0m'
+  [[ -z $line ]] || printf '%s\n\n' "$line"
+  [[ -n $branch ]] || return 0
+  base=$(--default-base-ref 2>/dev/null) || return 0
+  if [[ $branch == "$base" ]] || ! git rev-parse --verify -q "$branch^{commit}" &>/dev/null; then
+    return 0
+  fi
+  printf '%s%s...%s%s\n' "$b" "${base:0:40}" "$branch" "$r"
+  git log --oneline --no-decorate --color=never -n 10 "$base..$branch" 2>/dev/null
+  echo
+  git -c color.ui=always diff --stat=${FZF_PREVIEW_COLUMNS:-80} "$base...$branch" 2>/dev/null
+}
+
+--fzf-list() { --list-branches "$(<"$1/scope")" "$(<"$1/order")"; }
+
+--fzf-update() {
+  GIT_TERMINAL_PROMPT=0 git remote update </dev/null &>/dev/null || true
+  rm -f "$1/updating"   # (the header, in place, goes back on the next result)
+  --fzf-list "$1"
+}
+
+# --fzf-header DIR -- the current values are bold (fzf --ansi styles headers)
+--fzf-header() {
+  local dir=$1 scope order tool update b=$'\e[1m' r=$'\e[0m'
+  case $(<"$dir/scope") in
+    worktree) scope=worktrees ;;
+    *)        scope="$(<"$dir/scope") branches" ;;   # all/local/remote branches
+  esac
+  case $(<"$dir/order") in full) order=remote/name ;; *) order=$(<"$dir/order") ;; esac
+  if [[ -r $dir/tool_fixed ]]; then tool="tool: $b$(<"$dir/tool_fixed")$r (given)"; else tool="^t tool: $b$(<"$dir/tool")$r"; fi
+  update='^l update remotes'
+  [[ ! -e $dir/updating ]] || update="^l ${b}updating remotes...$r"   # inline: the rest of the header stays
+  echo "Enter: select, or create if nothing matches   $tool"
+  echo "alt-enter: create new worktree   ^r branch from: $b$(<"$dir/base_label")$r"
+  echo "^s scope: $b$scope$r   ^o order: $b$order$r   $update"
+}
+
+# --list-branches [SCOPE] [ORDER] -- candidates for the picker
+# format: branch_name<TAB>indicator branch_name<TAB>date hash [upstream] subject
+--list-branches() {
+  local scope=${1:-all} order=${2:-recent}
+  { set +x; } &>/dev/null
+  # NOTE: git branch --format uses ref-filter syntax which doesn't support
+  # pretty-format's %<(N,trunc) truncation. Using bash to handle truncation,
+  # alignment, and coloring instead.
+  local c_reset=$'\e[0m' c_green=$'\e[32m' c_cyan=$'\e[36m' c_blue=$'\e[34m' c_yellow=$'\e[33m' c_muted=$'\e[2;90m'   # dim gray: the remote/ part and worktree paths
+  local c_red=$'\e[31m' local_branches sort_args
+  local_branches=$(git branch --format='%(refname:lstrip=2)')
+  # the two places worktrees are expected: the main checkout, and the root
+  # where wtcode puts the rest (see --enter-git-worktree)
+  local main_wt wt_root=${GIT_WORKTREE_ROOT:-}
+  main_wt=$(cd "$(git rev-parse --git-common-dir)/.." 2>/dev/null && pwd -P) || main_wt=
+  [[ -z $wt_root && -z $main_wt ]] || : ${wt_root:=$main_wt.worktrees}
+  # compare like with like: git reports canonical paths (no symlinks, no trailing /)
+  [[ ! -d $wt_root ]] || wt_root=$(cd "$wt_root" && pwd -P)
+  case $order in
+    name) sort_args=(-k3,3f -k1,1n) ;;   # by name alone; local before remote on ties
+    full) sort_args=(-k4,4f) ;;          # by remote/name
+    *)    sort_args=(-k1,1n -k2,2nr) ;;  # local first, then remote, each by recency
+  esac
+  {
+    # stage 1: isremote epoch namekey, then the x-prefixed fields (x keeps
+    # read from collapsing empty tab-separated ones)
+    if [[ $scope == all || $scope == local || $scope == worktree ]]; then
+      git branch --format=$'%(committerdate:unix)\tx%(refname:lstrip=2)\tx%(HEAD)\tx%(worktreepath)\tx%(committerdate:relative)\tx%(objectname:short)\tx%(upstream:track)\tx%(contents:subject)' |
+      while IFS=$'\t' read -r epoch branch head worktree rest; do
+        [[ $scope == worktree && $head != 'x*' && -z ${worktree#x} ]] && continue
+        printf '0\t%s\t%s\t%s\t%s\t%s\t%s\n' "$epoch" "$branch" "$branch" "$head" "$worktree" "$rest" || break
+      done
+    fi
+    # remote-tracking branches that don't have a local counterpart
+    if [[ $scope == all || $scope == remote ]]; then
+      git branch -r --format=$'%(committerdate:unix)\tx%(refname:lstrip=2)\tx>\tx\tx%(committerdate:relative)\tx%(objectname:short)\tx\tx%(contents:subject)' |
+      while IFS=$'\t' read -r epoch remote_ref head worktree rest; do
+        remote_ref=${remote_ref#x}
+        [[ $remote_ref == */HEAD ]] && continue
+        grep -qxF "${remote_ref#*/}" <<< "$local_branches" && continue
+        printf '1\t%s\tx%s\tx%s\t%s\t%s\t%s\n' "$epoch" "${remote_ref#*/}" "$remote_ref" "$head" "$worktree" "$rest" || break
+      done
+    fi
+  } |
+  sort -t $'\t' "${sort_args[@]}" |
+  cut -f4- |
+  while IFS=$'\t' read -r branch head worktree date hash upstream subject; do
+    # strip the x prefix from all fields
+    branch=${branch#x} head=${head#x} worktree=${worktree#x} date=${date#x} hash=${hash#x} upstream=${upstream#x} subject=${subject#x}
+    # determine indicator and color: HEAD (*) takes precedence, then worktree (+)
+    local pre= suf= nm=$branch
+    if [[ $head == '*' ]]; then ind='*'; c=$c_green
+    elif [[ -n $worktree ]]; then ind='+'; c=$c_cyan
+    elif [[ $head == '>' ]]; then
+      # remote-only: mute the remote part, as a prefix (remote/name) or,
+      # when sorting by name alone, as a suffix: name (remote)
+      ind=' '; c=$c_reset
+      if [[ $order == name ]]; then nm=${branch#*/} suf=" (${branch%%/*})"; else pre=${branch%%/*}/ nm=${branch#*/}; fi
+    else ind=' '; c=$c_reset
+    fi
+    # worktrees also show where they are, searchable too, when that is
+    # unexpected: under the root but drifted from the branch name (wtcode puts
+    # branch X at <root>/X), or somewhere else entirely. the main checkout and
+    # in-place worktrees show nothing. local/remote scopes are about branches
+    if [[ -n $worktree && $worktree != "$main_wt" && ( $scope == all || $scope == worktree ) ]]; then
+      local rel=$worktree
+      if [[ -n $wt_root && $worktree == "$wt_root"/* ]]; then
+        rel=${worktree#"$wt_root"/}
+      elif [[ $worktree == "$HOME"/* ]]; then
+        rel="~/${worktree#"$HOME"/}"
+      fi
+      (( ${#rel} > 28 )) && rel="..${rel: -26}"
+      [[ $rel == "$branch" ]] || suf=" @ $rel"
+    fi
+    # truncate the name to fit, then pad (before adding colors)
+    local room=$(( 50 - ${#pre} - ${#suf} )) padw
+    (( room < 4 )) && room=4
+    (( ${#nm} > room )) && nm="${nm:0:room-2}.."
+    padw=$(( 50 - ${#pre} - ${#nm} - ${#suf} )); (( padw < 0 )) && padw=0
+    printf -v pad '%*s' "$padw" ''
+    printf -v date '%14s' "$date"
+    # build display fields with colors embedded
+    name_shown="${c_muted}${pre}${c_reset}${c}${nm}${c_reset}${c_muted}${suf}${c_reset}${pad}"
+    date_shown="${c_blue}${date}${c_reset}"
+    hash_shown="${c_yellow}${hash}${c_reset}"
+    if [[ -n $upstream ]]; then upstream_shown="${c_red}${upstream}${c_reset} "; else upstream_shown=''; fi
+    printf '%s\t%s %s\t%s  %s %s%s\n' \
+      "$branch" "$ind" "$name_shown" "$date_shown" "$hash_shown" "$upstream_shown" "$subject" || break
+  done
+}
+
 ###############################################################################
 ## --enter-git-worktree -- select branch and create/switch worktree
 ###############################################################################
@@ -85,56 +600,22 @@ WTCODE_CMDS_TO_TRY=(
   if [[ $# -gt 0 ]]; then
     branch_name=$1; shift
   elif type fzf &>/dev/null; then
-    # if branch name unspecified, use fzf to select one or enter a new name
-    # format: branch_name<TAB>indicator branch_name date hash [upstream] subject
-    branch_name=$(
-      { set +x; } &>/dev/null
-      # NOTE: git branch --format uses ref-filter syntax which doesn't support
-      # pretty-format's %<(N,trunc) truncation. Using bash to handle truncation,
-      # alignment, and coloring instead.
-      c_reset=$'\e[0m' c_green=$'\e[32m' c_cyan=$'\e[36m' c_blue=$'\e[34m' c_yellow=$'\e[33m' c_red=$'\e[31m' c_dim=$'\e[2m'
-      {
-      git branch --sort=-committerdate \
-          --format=$'x%(refname:lstrip=2)\tx%(HEAD)\tx%(worktreepath)\tx%(committerdate:relative)\tx%(objectname:short)\tx%(upstream:track)\tx%(contents:subject)'
-      # also include remote-tracking branches that don't have a local counterpart
-      local_branches=$(git branch --format='%(refname:lstrip=2)')
-      git branch -r --sort=-committerdate \
-          --format=$'x%(refname:lstrip=2)\tx>\tx\tx%(committerdate:relative)\tx%(objectname:short)\tx\tx%(contents:subject)' |
-      while IFS=$'\t' read -r remote_ref rest; do
-        remote_ref=${remote_ref#x}
-        [[ $remote_ref == */HEAD ]] && continue
-        local_name=${remote_ref#*/}
-        grep -qxF "$local_name" <<< "$local_branches" && continue
-        printf 'x%s\t%s\n' "$remote_ref" "$rest"
-      done
-      } |
-      while IFS=$'\t' read -r branch head worktree date hash upstream subject; do
-        # strip the x prefix from all fields
-        branch=${branch#x} head=${head#x} worktree=${worktree#x} date=${date#x} hash=${hash#x} upstream=${upstream#x} subject=${subject#x}
-        # determine indicator and color: HEAD (*) takes precedence, then worktree (+)
-        if [[ $head == '*' ]]; then ind='*'; c=$c_green
-        elif [[ -n $worktree ]]; then ind='+'; c=$c_cyan
-        elif [[ $head == '>' ]]; then ind=' '; c=$c_dim
-        else ind=' '; c=$c_reset
-        fi
-        # truncate then pad branch name, right-pad date (before adding colors)
-        if (( ${#branch} > 50 )); then name="${branch:0:48}.."; else name=$branch; fi
-        printf -v name '%-50s' "$name"
-        printf -v date '%14s' "$date"
-        # build display fields with colors embedded
-        name_shown="${c}${name}${c_reset}"
-        date_shown="${c_blue}${date}${c_reset}"
-        hash_shown="${c_yellow}${hash}${c_reset}"
-        if [[ -n $upstream ]]; then upstream_shown="${c_red}${upstream}${c_reset} "; else upstream_shown=''; fi
-        printf '%s\t%s %s\t%s  %s %s%s\n' \
-          "$branch" "$ind" "$name_shown" "$date_shown" "$hash_shown" "$upstream_shown" "$subject"
-      done |
-      fzf --ansi --color --tmux --print-query --delimiter=$'\t' --with-nth=2 --nth=1 \
-          --preview 'echo {3}' --preview-window 'down:2:wrap' \
-          --prompt 'wtcode: select worktree/branch (prefix : to create new) > ' |
-      cut -f1 |
-      tail -1
-    )
+    # if branch name unspecified, use fzf to select one or enter a new name.
+    # key bindings cycle scope/order/base/tool, see --fzf-* below
+    local fzf_dir
+    fzf_dir=$(--fzf-init)
+    # fzf prints the typed query, then the selection (if any)
+    local picked
+    picked=$(--fzf-pick "$fzf_dir")
+    if [[ -e $fzf_dir/force_new ]]; then
+      # alt-enter: the typed text is a new name, never an existing ref
+      branch_name=$(head -1 <<< "$picked")
+      [[ -n $branch_name ]] && branch_name=:$branch_name
+    else
+      branch_name=$(cut -f1 <<< "$picked" | tail -1)
+    fi
+    [[ -z ${branch_name-} ]] || --fzf-commit "$fzf_dir"
+    rm -rf "$fzf_dir"
   else  # abort if fzf not available
     branch_name=${1:?Need a worktree/branch name as first argument}; shift
   fi
@@ -230,9 +711,14 @@ WTCODE_CMDS_TO_TRY=(
     --msg "creating worktree for branch: $branch_name"
     git worktree add -B "$branch_name" "$worktree_path" "$(git rev-parse "$branch_name")"
   else
-    # fork the current HEAD and create the new worktree
-    --msg "creating worktree with new branch: $branch_name"
-    git worktree add -b "$branch_name" "$worktree_path" "$(git rev-parse HEAD)"
+    # fork a base ref and create the new worktree: defaults to origin/HEAD
+    # (falling back to origin/main, origin/master, then the current HEAD);
+    # set WTCODE_USE_CURRENT_BRANCH=true to always fork from the current
+    # branch instead
+    local base_ref
+    base_ref=${WTCODE_PICKED_BASE:-$(--default-base-ref)}
+    --msg "creating worktree with new branch: $branch_name (from $base_ref)"
+    git worktree add -b "$branch_name" "$worktree_path" "$base_ref"
   fi
   cd "$worktree_path"
 
@@ -423,8 +909,14 @@ APPLESCRIPT
 ###############################################################################
 --launch-code-tool() {
   # resolve the command to launch if not specified
+  if [[ $# -eq 0 && -n ${WTCODE_PICKED_TOOL-} ]]; then
+    # chosen in the interactive picker; may carry args, e.g. `claude --resume`
+    local _w _words=()
+    while IFS= read -r -d '' _w; do _words+=("$_w"); done < <(--split-command "$WTCODE_PICKED_TOOL")
+    [[ ${#_words[@]} -eq 0 ]] || set -- "${_words[@]}"
+  fi
   if [[ $# -eq 0 ]]; then
-    for _cmd in "${WTCODE_CMDS_TO_TRY[@]}"; do
+    for _cmd in "${WTCODE_TOOLS_TO_TRY[@]}"; do
       [[ -n "$_cmd" ]] && type "$_cmd" &>/dev/null && set -- "$_cmd" && break
     done
     # fall back to an interactive shell
@@ -446,7 +938,7 @@ APPLESCRIPT
   # when inside tmux, default to send-keys for command history access
   # set WTCODE_TMUX_MODE=exec to opt out and exec directly
   if [[ -n ${TMUX:-} ]] && type tmux &>/dev/null; then
-    local mode=${WTCODE_TMUX_MODE:-send-keys}
+    local mode=$WTCODE_TMUX_MODE
 
     case $mode in
       send-keys|split-window|new-window)
@@ -485,7 +977,7 @@ APPLESCRIPT
   # outside tmux: reuse the current tab/window if the terminal app supports
   # it (see --terminal-send-keys). set WTCODE_TERMINAL_MODE=exec to opt out
   if [[ -z ${TMUX:-} ]]; then
-    local mode=${WTCODE_TERMINAL_MODE:-send-keys}
+    local mode=$WTCODE_TERMINAL_MODE
     case $mode in
       send-keys)
         if --terminal-send-keys "$@"; then
@@ -513,6 +1005,7 @@ APPLESCRIPT
 -h() { --help "$@"; }
 
 --exec() {
+  [[ $# -gt 0 ]] && WTCODE_TOOL_FIXED=$1   # CMD given: the picker can't change it
   --enter-git-worktree
   --launch-code-tool "$@"
 }
@@ -526,6 +1019,13 @@ APPLESCRIPT
   --launch-code-tool "$@"
 }
 
+# global options (before BRANCH/CMD): --base REF
+while [[ ${1-} == --base || ${1-} == --base=* ]]; do
+  if [[ $1 == --base=* ]]; then WTCODE_BASE_REF=${1#--base=}; shift
+  else WTCODE_BASE_REF=${2:?--base needs a ref}; shift 2
+  fi
+done
+
 # dispatch $1 as a function when it starts with -
 [[ ${1-} == -* ]] || set -- -- "$@"
 "$@"

{wtcode-0.4.0.dist-info → wtcode-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wtcode
-Version: 0.4.0
+Version: 0.7.0
 Summary: Launch your favorite code tool in a git worktree
 Author-email: Jaeho Shin <netj@sparcs.org>
 License-Expression: MIT
@@ -60,7 +60,7 @@ wtcode --exec CMD [CMD-ARGS...]
 ```
 
 - **`BRANCH`** -- Git branch or worktree name. If omitted and [fzf](https://github.com/junegunn/fzf) is available, interactively select one. Surround with `:` to create a new branch (use `:::name` or `name:::` to avoid fzf matching the colons).
-- **`CMD`** -- Command to launch in the worktree. Defaults to `$WTCODE_CMD`, or the first available of: `claude`, `aider`, `codex`, `$SHELL`.
+- **`CMD`** -- Command to launch in the worktree. Defaults to `$WTCODE_TOOL`, or the first available of: `claude`, `aider`, `codex`, `$SHELL`.
   When `CMD` resolves to plain `claude` (no extra args) in a worktree that already existed, wtcode launches `claude /resume` so it opens straight into your last session there. Press `Esc` in the picker to start a new session instead.
 - **`--exec`** -- Skip the branch argument; select interactively via fzf, then launch `CMD`.
 - **`--help`** / **`--version`** -- Show help or version info.
@@ -74,14 +74,19 @@ wtcode feature-x claude --resume  # launch claude with flags
 wtcode --exec claude --resume     # select interactively, launch claude --resume
 wtcode :new-feature               # create new branch and worktree
 wtcode                            # interactive branch selection via fzf
-WTCODE_CMD=cursor wtcode feature  # use cursor as default tool
+WTCODE_TOOL=cursor wtcode feature  # use cursor as default tool
 ```
 
 ## Environment variables
 
 | Variable | Description |
 |---|---|
-| `WTCODE_CMD` | Default tool to launch (e.g., `claude`, `lazygit`, `vim`, `cursor`) |
+| `WTCODE_TOOL` | Default tool to launch (e.g., `claude`, `lazygit`, `vim`, `cursor`); `WTCODE_CMD` is a deprecated alias |
+| `WTCODE_USE_CURRENT_BRANCH` | When creating a brand-new branch, fork it from the current HEAD instead of the default: `origin/HEAD` (falling back to `origin/main`, then `origin/master`) |
+| `WTCODE_BASE_REF` | Fork brand-new branches from this ref (also `wtcode --base REF`) |
+| `WTCODE_BRANCH_SCOPE` | Initial picker scope: `all`, `worktree`, `local`, `remote` |
+| `WTCODE_BRANCH_ORDER` | Initial picker order: `recent`, `name`, `full` (remote/name) |
+| `WTCODE_STATE_FILE` | Where the picker remembers its last state (default `$XDG_STATE_HOME/wtcode/state`; empty disables) |
 | `WTCODE_DEBUG` | Enable debug tracing when set to any value |
 | `GIT_WORKTREE_ROOT` | Override the directory where worktrees are created |
 

wtcode-0.7.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+wtcode/__init__.py,sha256=h7R8i7Zgn-_8dPxK2hYN7eTNgSYrnmVyvmaDSvGQF_c,89
+wtcode/__main__.py,sha256=hOvSYANO-q_rf2yy-AQoEOr18KFRSOF8Ezosf8eeFmM,335
+wtcode/wtcode.sh,sha256=fIGxitblECbt7Rjdj8IeIHv0-pgke7BCZCccIgN6iS4,44180
+wtcode-0.7.0.dist-info/licenses/LICENSE,sha256=MV9gr1nAVj5R60EM2BQuBhBxCG5V9ulX6-Ep_-LcLqA,1067
+wtcode-0.7.0.dist-info/METADATA,sha256=YTVpAMP3q1RN8Yi31XUKnLZDmjgPcDofX28D-N1tdzM,4756
+wtcode-0.7.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+wtcode-0.7.0.dist-info/entry_points.txt,sha256=QkSPHU86FQa-ujQk07fF4sX4DBQgWzDtgusop4AA5bc,48
+wtcode-0.7.0.dist-info/top_level.txt,sha256=oftTSYYjDMqt33wa0c9MC15KuQ3eyRyoTLXy3PdkVfE,7
+wtcode-0.7.0.dist-info/RECORD,,

{wtcode-0.4.0.dist-info → wtcode-0.7.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

wtcode-0.4.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-wtcode/__init__.py,sha256=TqbbEAt77M6Nx-V2Hn5cdAYQHAuTIzcW1KhT-e_nzhw,89
-wtcode/__main__.py,sha256=hOvSYANO-q_rf2yy-AQoEOr18KFRSOF8Ezosf8eeFmM,335
-wtcode/wtcode.sh,sha256=4jJihpDcSMISByTOW7zo77xDk6bxstQWCEc3d6d-cX4,21098
-wtcode-0.4.0.dist-info/licenses/LICENSE,sha256=MV9gr1nAVj5R60EM2BQuBhBxCG5V9ulX6-Ep_-LcLqA,1067
-wtcode-0.4.0.dist-info/METADATA,sha256=tltadRB3o50NbV1Pwd0NhNLte-ezlBXRceRFSrAzs_I,4137
-wtcode-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-wtcode-0.4.0.dist-info/entry_points.txt,sha256=QkSPHU86FQa-ujQk07fF4sX4DBQgWzDtgusop4AA5bc,48
-wtcode-0.4.0.dist-info/top_level.txt,sha256=oftTSYYjDMqt33wa0c9MC15KuQ3eyRyoTLXy3PdkVfE,7
-wtcode-0.4.0.dist-info/RECORD,,