Add multi-repository context support

[guodong-sq]

Summary

• Adds wt context command for managing multiple repository configurations
• Adds wt context add subcommand that runs full setup flow (same as install.sh)
• Shows context banner on all commands to indicate active repository
• Extracts shared setup logic into lib/wt-context-setup for reuse

Changes

New files:

• lib/wt-context - Core context management library
• lib/wt-context-setup - Shared setup flow for install.sh and wt context add
• bin/wt-context - Context list/switch/add command

Modified files:

• lib/wt-common - Loads context config on init
• install.sh - Simplified to use shared setup library
• wt.sh - Added context command
• All bin/wt-* scripts - Added context banner
• Shell completions - Added context command completion
• lib/wt-help - Updated help text

User Experience

# Interactive context selection
wt context

# Direct switch
wt context java

# List all contexts
wt context --list

# Add new repository context (full setup flow)
wt context add
wt context add ~/repo
wt context add myname ~/repo

# All commands show context banner
wt list
# Output:
#   [Context: java] (wt context to switch)
#   ...

Test plan

• Fresh install with install.sh
• Add second context with wt context add
• Switch contexts with wt context
• Verify context banner appears on all commands
• Verify shell completions work

🤖 Generated with Claude Code

[bezhermoso]

Have you considered using git config as config source of vault directory path, worktree base path, etc.? That way, wt would largely "work" depending on which repo you're on i.e. context-switching is either (a) cding to another repo, or (b) an --repo path argument you pass down to git -C

[guodong-sq]

Have you considered using git config as config source of vault directory path, worktree base path, etc.? That way, wt would largely "work" depending on which repo you're on i.e. context-switching is either (a) cding to another repo, or (b) an --repo path argument you pass down to git -C

Thanks for the suggestion! I think with git config alone there's a challenge with the "run wt from anywhere" use case. Even with git config storing per-repo settings, we'd still need something to answer: "which repo should wt list query when I run it from user root?"

Options would be:

1. Require being in a repo, can't run wt list, wt cd or wt switch from anywhere
2. Always pass --repo, wt --repo ~/Development/java list works, but adds friction to every command
3. Store "current context" somewhere, which brings us back to needing ~/.wt/current or similar

they are all valid options, and UX preferences, I went with "run from anywhere" since I often run wt list or wt cd from random directories.

I can see a place where we use a hybrid approach, where the current context is stored globally (e.g., in ~/.wt/current), then per-repo configurations and shell variables stored in git config. I went with single location for simplicity and put all config in one place. But git config has the advantage of config traveling with the repo. No strong preference either way honestly!

[bezhermoso]

Thanks for the suggestion! I think with git config alone there's a challenge with the "run wt from anywhere" use case. Even with git config storing per-repo settings, we'd still need something to answer: "which repo should wt list query when I run it from user root?"

IMO to support multi-repo, wt being context-aware when run within a repo would be the least surprising behavior to most people. I get the need for it to function "globally"/absence of immediate, local context, but I don't believe these two things are necessarily mutually exclusive.

Somewhat tangential, but making "local context" primary and "global context" secondary can even simplify other things e.g. less reliance on sessions/login-shell/interactivity (e.g. no need for source wt.sh), easier installation (e.g. just add to $PATH), etc.

IMO having the core of wt be local-context-first can likely simplify the implementation because of the tighter scope, the session-awareness & other interactivity stuff can easily be a layer above. This split offers a great benefit of minimizing where we have to be POSIX-compliant as we can separate the UX layer & offer shell-specific niceties. This is not an uncommon design pattern in CLI tools.

[guodong-sq]

Thanks for the suggestion! I think with git config alone there's a challenge with the "run wt from anywhere" use case. Even with git config storing per-repo settings, we'd still need something to answer: "which repo should wt list query when I run it from user root?"

IMO to support multi-repo, wt being context-aware when run within a repo would be the least surprising behavior to most people. I get the need for it to function "globally"/absence of immediate, local context, but I don't believe these two things are necessarily mutually exclusive.

Somewhat tangential, but making "local context" primary and "global context" secondary can even simplify other things e.g. less reliance on sessions/login-shell/interactivity (e.g. no need for source wt.sh), easier installation (e.g. just add to $PATH), etc.

IMO having the core of wt be local-context-first can likely simplify the implementation because of the tighter scope, the session-awareness & other interactivity stuff can easily be a layer above. This split offers a great benefit of minimizing where we have to be POSIX-compliant as we can separate the UX layer & offer shell-specific niceties. This is not an uncommon design pattern in CLI tools.

Thought about this a little bit more, here are my thoughts

local vs global context priority

I think the real tension is that wt has two kinds of commands with opposite needs: sub commands like wt add, wt metadata-* operates inside a repo, while wt list or wt cd can navigate across repo.
"Local-context-first" optimizes for "work on what I'm in." whereas "Global-context-first" optimizes for "jump to where I want to be.". However this concern is workflow-dependent, I find it beneficial and use navigation commands a lot, but for someone with external tools that help with the navigation, the commands that matter (wt add, wt remove, wt switch, wt metadata-*) are all "operate on the repo I'm in" operations that work better with local detection.
And the multi-session problem is a real correctness issue: two tmux panes running wt context concurrently stomp on each other's state via a shared ~/.wt/current file, potentially creating worktrees in the wrong repo.

the layering / POSIX point

I want to understand this better, were you referring to literally targeting POSIX sh, or more about the principle of keeping shell-specific concerns out of the core? Currently the architecture is:

• wt.sh must be sourced
• All bin/wt-* scripts are standalone bash executables
• Completions are already split into wt.bash and wt.zsh

The only reason sourcing is required today is the wt() dispatcher function and wt cd (can't change the shell's cwd from a subprocess). Every other command already works as a standalone executable. Also the bin/wt-* scripts are all #!/usr/bin/env bash and use bash-isms structurally (arrays, process substitution, [[ ]] throughout). Getting to POSIX sh would be a significant rewrite, and since bash+zsh covers the entire target audience, I'm not sure the payoff is there.

changes required to make local context take precedence

If I understand the suggestion correctly, the split would be:

• Core layer (pure executables, bash, no sourcing):

  • wt-add, wt-remove, wt-list, wt-switch, wt-metadata-*, wt-context
  • Detect context from cwd. Accept --repo/--context override.
  • takes all input via arguments, non-interactive.

• UX/Integration layer (interaction, session-aware)

  • interactive menus, confirmation prompts, wt cd, completions, fzf, context banners
  • shell-specific

@bezhermoso Does the above resonate with you?

[bezhermoso]

Getting to POSIX sh would be a significant rewrite, and since bash+zsh covers the entire target audience, I'm not sure the payoff is there.

@guodong-sq Ahh yes, I admit I did not dig into the true state of POSIX-compatibility, but simply assumed it was partly the goal given the use of cd ... && pwd common POSIX-compliant method of resolving paths in lieu of non-POSIX realpath. I agree targeting Zsh/Bash is already sufficient.

That resonates. I agree with your analysis of the tension here. Your analysis on what the required changes are for separating core functionality from shell integration is spot-on, and IMO would lead to more correct (or at least least-suprising) behavior, predictability & composability that makes it more attractive to adopt & slot into people's varying workflows.