[Feature] `git worktree` integration

[bezhermoso]

Motivation

With AI coding agents & tooling increasingly adopt worktree workflows (most recently, Claude Code natively supporting via claude --worktree), being able to hook into the standard worktree flows would be ideal.

Proposed Changes

New adopt flow

• Take any existing worktree and give it the wt treatment.
• Mark it as adopted (e.g. w/ a marker file .git/wt/touch)

The core wt commands becomes a mostly a porcelain for common operations:

• wt add -> git worktree add ... then wt adopt
• wt list -> git worktree list w/ niceties. It should list all worktrees, adopted or no, and maybe decorate the adopted ones (worktrees with the marker file)
• wt switch -> git worktree list to pick from all worktrees, adopt the selection if it hasn't been adopted yet, then do the symlink switch.

Work trees does not have to be in the tool-managed worktree base directory for it to be adopted. The base directory should still be there for wt add flow.

Manage IntelliJ files, context & configs only

Allowing wt to adopt other worktrees managed by other tools (e.g. ~/conductor/workspaces/...) means it should rely less on the repos and their worktrees to be under ~/.wt.

It seems to me that as long as we can discover w/c root repos are managed & w/ subtrees are adopted by wt, then they don't have to live in ~/.wt/.... It can remain as the home for the IntelliJ files, and contexts w/ their configs; things that only wt needs to touch.

Not necessary, but we can also follow the XDG Base Directory Spec:

# $XDG_DATA_HOME for user-specific application-data that users don't need to deal with:
~/.local/share/wt/intellij-files/<CONTEXT>/...

# $XDG_CONFIG_HOME for user-specific, application configuration that users may need to deal with:
~/.config/wt/contexts/<CONTEXT>/...

Ensure core operations work 100% non-interactive

This is probably already the case, but they need to be non-interactive-first by design so they can used with zero issues in any orchestration.

Examples:

• A repository can have a post-checkout hook that detects a worktree checkout and auto-adopt.
• Conductor post-checkout script
• etc.

---

Working on a PoC on this based on the WIP PR I have open, but would love your thoughts before I get too deep 😄

[guodong-sq]

Great proposal, @bezhermoso. This feels like a natural next step from our earlier discussion about local-context-first and the core/UX layer split.

adopt flow
This is the right primitive. It cleanly separates "create a worktree" from "give it the wt treatment" (metadata, symlink management, etc.), which is exactly the decomposition we talked about. The marker file approach works well for discovery without a central registry. And with AI agents like Claude Code spawning worktrees independently, having wt adopt as a composable building block that hooks like post-checkout can call non-interactively is a much better story than requiring everything to flow through wt add.

One edge case worth calling out: worktrees created by other tools (or AI agents) may already have project metadata (.idea/, .ijwb/, etc.) by the time wt adopt runs. We'd need to handle this, likely a choice between "mark as adopted, keep existing files" vs "overwrite from vault". Inspired by our earlier discussions on this, I've been prototyping a WIP IntelliJ plugin (guodong/intellij_plugin branch) that implements a similar provision flow with a marker file and the keep/overwrite choice. The CLI adopt could follow the same model.

Relaxing the ~/.wt layout requirement
Agreed. This aligns with the local-context-first direction: if wt can detect and adopt worktrees wherever they live, the rigid directory structure becomes optional rather than mandatory. Keeping ~/.wt (or XDG paths) as home for metadata/configs only makes sense. Open to XDG but would probably start without it and add it later to keep scope manageable.

Non-interactive first
This is the core/UX layer split we discussed. If adopt, add, list, switch, and remove all work fully non-interactively via arguments, they become the core layer. The interactive menus, confirmation prompts, wt cd, completions, all of that stays as the UX layer on top. This would also help with the multi-session correctness issue (two tmux panes stomping on ~/.wt/current).

Looking forward to the PoC and happy to collaborate on it!

[bezhermoso]

We'd need to handle this, likely a choice between "mark as adopted, keep existing files" vs "overwrite from vault"

I'm curious: what's the use-case of adopting a worktree that skips overwriting from vault? Why can't we leave those un-adopted?