yggtree 1.4.3 → 1.4.5

package/README.md

@@ -40,8 +40,8 @@ worktree workflow first, then load the smallest reference they need:
   the work already in progress.
 * **Bootstrap and use a realm**: prepare a worktree, open it in your IDE, or
   run commands inside it.
-* **Run sandbox experiments**: try alternative approaches locally and
-  apply/unapply the winner safely.
+* **Run sandbox experiments**: try alternative approaches locally, then copy the
+  winner back with sandbox-backed apply/unapply.
 
 This skill is especially useful with agents like **Claude Code**,
 **Codex**, **Cursor**, **Gemini CLI**, and other tools that support the open
@@ -110,6 +110,7 @@ All managed worktrees live under:
 ```
 
 This keeps your main repository clean while enabling true parallelism.
+You can change the global managed worktree location with `yggtree config`.
 
 ---
 
@@ -146,7 +147,10 @@ Create, manage, and navigate Git worktrees as a primary workflow, not an afterth
 Work on multiple branches at the same time, each in its own isolated environment.
 
 🧪 **Sandbox worktrees for experimentation**
-Prototyping something risky? Create a sandbox with a random name, try different strategies, and apply the winner back to your origin branch.
+Prototyping something risky? Create a sandbox, try different strategies, and copy the winner back to your origin checkout.
+
+🤝 **Handoff current work**
+Started in your main checkout? Carry staged, unstaged, and untracked work into a named sandbox worktree and continue there.
 
 🤖 **AI-friendly isolation**
 One worktree per agent, per experiment, per idea. No shared state, no collisions.
@@ -158,7 +162,7 @@ Run installs, submodules, and setup scripts automatically for each worktree.
 Enter worktrees, execute commands, or run tasks without changing directories.
 
 📍 **Predictable structure**
-All managed worktrees live under `~/.yggtree`, keeping your repository clean.
+Managed worktrees default to `~/.yggtree`, with an optional global path setting for agent-native layouts.
 
 🧭 **Interactive or scriptable**
 Use the interactive UI or drive everything through commands and flags.
@@ -214,10 +218,16 @@ Sometimes you don't want to "commit to a branch" yet. You just want to try somet
 
 1.  **Create**: `yggtree create-sandbox` (creates something like `sandbox-a3f2_feature-branch`).
 2.  **Experiment**: Change files, run tests, try that risky refactor.
-3.  **Apply**: `yggtree apply` to "push" those file changes back to your origin directory.
-4.  **Unapply**: Don't like it? `yggtree unapply` restores your origin to exactly how it was before.
+3.  **Apply**: `yggtree apply` to copy changed sandbox files back to your origin directory with backups.
+4.  **Unapply**: Don't like it? `yggtree unapply` restores those backed-up origin files while the sandbox still exists.
+
+Sandboxes are **not pushed to remote**. Omit the name for a generated temporary sandbox, or provide one when the work needs to be easy to find later.
+
+Use `handoff` when you started in the origin checkout and want to continue that dirty work in a sandbox. This is the taught path for staged, unstaged, or untracked work:
 
-Sandboxes are **not pushed to remote** and their names are randomly generated because they are meant to be temporary playgrounds.
+```bash
+yggtree handoff --name auth-refactor
+```
 
 ---
 
@@ -250,6 +260,48 @@ Resolution order:
 
 ---
 
+## 🗂️ Global Worktree Paths
+
+By default, managed worktrees use the Yggtree layout:
+
+```bash
+~/.yggtree/<repo-name>/<worktree-slug>
+```
+
+Show the active global setting:
+
+```bash
+yggtree config get
+```
+
+Use the Codex-style layout when you want Yggtree-created worktrees to live under Codex's worktree root:
+
+```bash
+yggtree config use codex
+```
+
+That preset creates new managed worktrees like:
+
+```bash
+~/.codex/worktrees/<worktree-slug>/<repo-name>
+```
+
+Set a custom managed root while keeping the Yggtree layout:
+
+```bash
+yggtree config set-worktrees-root ~/Worktrees
+```
+
+Return to defaults:
+
+```bash
+yggtree config reset
+```
+
+Claude and Cursor do not currently have a confirmed native worktree directory pattern in Yggtree. Until that is explicit, use `set-worktrees-root` with the directory you want rather than relying on an unverified preset.
+
+---
+
 ## 🛠️ Command Reference
 
 ### `yggtree`
@@ -269,11 +321,13 @@ Options:
 * `--source local|remote`
 * `--no-bootstrap`
 * `--open / --no-open`
+* `--enter / --no-enter`
 * `--exec "<command>"`
 
 Interactive flow:
 
 * Instead of asking for a free-form `exec` command, yggtree now asks if you want to open an editor after creation.
+* After creation, yggtree enters the new worktree shell unless you pass `--no-enter`.
 * `--exec` remains available as an advanced explicit override.
 
 <details>
@@ -307,15 +361,17 @@ Options:
 * `-r, --ref <ref>`: skip picker and use a specific branch (`feature/x` or `origin/feature/x`)
 * `--no-bootstrap`
 * `--open / --no-open`: choose whether to open editors or run a startup command before the worktree shell starts
-* `--tool <command>`: open a specific editor/app and skip the open prompt (`cursor`, `code`, `codex-app`)
+* `--tool <command>`: open a specific editor, app, or terminal target and skip the open prompt (`cursor`, `code`, `codex-app`, `cmux`, `tmux`)
 * `--no-enter`: finish after create/open and return to the caller
 * `--exec "<command>"`
 
 Interactive flow:
 
 * Yggtree asks what to open before starting the worktree shell.
-* Editor choices can be selected together.
-* Use `--tool` to skip the open prompt and launch one editor/app directly.
+* Shell-entry flows use a single action picker, so pressing Enter on Cmux or Tmux chooses that terminal target directly.
+* Plain `yggtree open` flows use the same single action picker and return after opening the selected target.
+* Use `--tool` to skip the open prompt and launch one editor/app or terminal target directly.
+* Cmux, Tmux, and `Other command...` are mutually exclusive because the open picker accepts one action.
 * `Other command...` runs a command in the Yggtree shell first, then leaves you there.
 * Use `--no-enter` when you only want the worktree created/opened and the command to return.
 * `--exec` remains available as an advanced explicit override.
@@ -336,12 +392,12 @@ yggtree wc hotfix-auth main --open --no-enter
 
 ### `yggtree create-sandbox`
 
-Create a temporary sandbox from your current local branch.
+Create a temporary local-only sandbox from your current branch.
 
 Options:
 
 *   `-n, --name <name>`: Optional sandbox name (auto-generated if omitted).
-*   `--carry / --no-carry`: Bring uncommitted changes (staged/unstaged/untracked) with you.
+*   `--carry / --no-carry`: Explicitly choose whether to copy uncommitted changes into the sandbox. Prefer `handoff` when the intent is continuing dirty work.
 *   `--no-bootstrap`
 *   `--open / --no-open`
 *   `--exec "<command>"`
@@ -354,25 +410,43 @@ Interactive flow:
 
 ---
 
+### `yggtree handoff`
+
+Carry uncommitted work from the current checkout into a sandbox worktree.
+
+Options:
+
+*   `-n, --name <name>`: Optional handoff name (prompted when omitted).
+*   `--no-bootstrap`
+*   `--open / --no-open`
+*   `--exec "<command>"`
+
+This is the continuation-focused semantic path for dirty work. It uses sandbox metadata and apply/unapply behavior, but defaults to carrying staged, unstaged, and untracked files.
+
+---
+
 ### `yggtree apply`
 
-Apply changes from the current sandbox back to the origin repository. 
-*   **Backs up** origin files before overwriting.
+Copy changed files from the current sandbox back to the origin checkout.
+*   **Backs up** origin files in sandbox metadata before overwriting.
 *   **Offers to delete** the sandbox after applying.
+*   **Is not a Git merge**: review the origin diff after applying, especially when deletions are involved.
 
 ---
 
 ### `yggtree unapply`
 
 Undo a previous `apply` operation.
-*   Restores origin files from the sandbox's backup.
+*   Restores origin files from the sandbox's backup metadata.
 *   *Note: Only works if the sandbox worktree still exists.*
 
 ---
 
 ### `yggtree create-multi`
 
-Create multiple worktrees at once.
+Create multiple official branch-backed worktrees at once. This is a bulk setup
+command; it does not have the full `create` lifecycle flags such as `--open`,
+`--enter`, or `--exec`.
 
 Options:
 
@@ -406,7 +480,7 @@ Columns:
 Notes:
 
 * Entries are grouped by `TYPE`.
-* `SANDBOX` and `MANAGED` are worktrees inside `~/.yggtree`.
+* `SANDBOX` and `MANAGED` are worktrees inside the configured managed worktree root.
 * External worktrees are labeled `LINKED`.
 * Use `--open` to switch this flow into "pick and open in tool" mode.
 * The **PR** column shows the pull request status for each branch (e.g. `OPEN`, `IN REVIEW`, `APPROVED`, `MERGED`, `DRAFT`, `CHANGES`). It only appears when `gh` CLI is installed and authenticated — otherwise it's silently omitted.
@@ -415,20 +489,22 @@ Notes:
 
 ### `yggtree open [worktree]`
 
-Open a worktree in an editor or supported desktop app.
+Open a worktree in an editor, supported desktop app, or terminal target.
 
 Behavior:
 
 * If `[worktree]` is omitted, you can pick from the worktree list with type-to-filter search.
 * Detects available editor commands in your `PATH` (for example: `cursor`, `code`, `zed`, `webstorm`).
-* Detects Codex App on macOS and launches it with `open -b com.openai.codex`.
-* Lets you choose one or more editors/apps interactively, or pass `--tool`.
-* By default, `open` launches editors/apps and returns.
+* Detects Codex App on macOS and launches the selected worktree with `codex app <path>`.
+* Detects Cmux and Tmux when their CLI commands are available.
+* Lets you choose one editor, app, or terminal target interactively, or pass `--tool`.
+* Keeps Cmux, Tmux, and `Other command...` mutually exclusive by using a single action picker.
+* By default, `open` launches the selected target and returns, except foreground terminal targets such as Tmux.
 * Use `wc --open` when you want to open a worktree and continue in its shell.
 
 Options:
 
-* `--tool <command>` (for example: `cursor`, `code`, `codex`, or `codex-app`)
+* `--tool <command>` (for example: `cursor`, `code`, `codex`, `codex-app`, `cmux`, or `tmux`)
 
 <details>
 <summary>Examples</summary>
@@ -437,6 +513,7 @@ Options:
 yggtree open
 yggtree open feat/new-ui --tool cursor
 yggtree open feat/new-ui --tool codex-app
+yggtree open feat/new-ui --tool tmux
 yggtree list --open
 ```
 
@@ -486,7 +563,7 @@ Behavior:
 
 Optional:
 
-* `--all` includes linked worktrees outside `~/.yggtree` (main/current worktree is excluded for safety)
+* `--all` includes linked worktrees outside the configured managed root (main/current worktree is excluded for safety)
 
 ---
 
@@ -531,12 +608,12 @@ yggtree create feat/login-flow
 ---
 
 <details>
-<summary>Create a worktree without bootstrap and without opening a tool</summary>
+<summary>Create a worktree without bootstrap, opening a tool, or entering</summary>
 
 **Command:**
 
 ```
-yggtree create feat/cleanup-api --no-bootstrap --no-open
+yggtree create feat/cleanup-api --no-bootstrap --no-open --no-enter
 ```
 
 **When to use:**
@@ -630,16 +707,16 @@ Useful when you want to manually navigate or copy the path into scripts.
 **Command:**
 
 ```bash
-yggtree create-sandbox --carry
+yggtree handoff --name risky-refactor
 ```
 
 **Scenario:**
 
 1.  You have 5 files changed in your main repo but aren't sure about the direction.
-2.  Run `create-sandbox --carry` to move those changes into an isolated `sandbox-a3f2_feature-branch` folder.
+2.  Run `handoff --name risky-refactor` to carry those changes into an isolated `sandbox-risky-refactor` folder.
 3.  Experiment freely.
 4.  If it works: `yggtree apply`.
-5.  If it fails: Just delete the sandbox or `unapply`.
+5.  If it fails after applying: run `yggtree unapply` before deleting the sandbox.
 
 </details>
 

package/dist/commands/config.js

@@ -0,0 +1,53 @@
+import chalk from 'chalk';
+import { formatGlobalConfig, getPresetConfig, getWorktreePathConfig, normalizeWorktreesRootInput, readGlobalConfig, writeGlobalConfig, } from '../lib/global-config.js';
+import { log } from '../lib/ui.js';
+export async function configGetCommand() {
+    const [rawConfig, resolvedConfig] = await Promise.all([
+        readGlobalConfig(),
+        getWorktreePathConfig(),
+    ]);
+    console.log(chalk.bold('\n  Yggtree config\n'));
+    formatGlobalConfig(rawConfig, resolvedConfig)
+        .forEach(line => console.log(`  ${line}`));
+    console.log('');
+}
+export async function configUseCommand(preset) {
+    const presetConfig = getPresetConfig(preset);
+    if (!presetConfig) {
+        log.error(`Unknown config preset "${preset}".`);
+        log.dim('Available presets: default, yggtree, codex');
+        return;
+    }
+    await writeGlobalConfig(presetConfig);
+    log.success(`Using ${preset} worktree layout.`);
+    await configGetCommand();
+}
+export async function configSetWorktreesRootCommand(root) {
+    const currentConfig = await readGlobalConfig();
+    await writeGlobalConfig({
+        ...currentConfig,
+        worktreesRoot: normalizeWorktreesRootInput(root),
+        worktreeLayout: currentConfig.worktreeLayout || 'yggtree',
+    });
+    log.success('Updated worktrees root.');
+    await configGetCommand();
+}
+export async function configSetWorktreeLayoutCommand(layout) {
+    if (layout !== 'yggtree' && layout !== 'codex') {
+        log.error(`Unknown worktree layout "${layout}".`);
+        log.dim('Available layouts: yggtree, codex');
+        return;
+    }
+    const currentConfig = await readGlobalConfig();
+    await writeGlobalConfig({
+        ...currentConfig,
+        worktreeLayout: layout,
+    });
+    log.success('Updated worktree layout.');
+    await configGetCommand();
+}
+export async function configResetCommand() {
+    await writeGlobalConfig({});
+    log.success('Reset Yggtree config to defaults.');
+    await configGetCommand();
+}

package/dist/commands/wt/bootstrap.js

@@ -2,23 +2,25 @@ import chalk from 'chalk';
 import inquirer from 'inquirer';
 import path from 'path';
 import { listWorktrees, getRepoRoot } from '../../lib/git.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { getManagedWorktreesRoot } from '../../lib/global-config.js';
 import { log } from '../../lib/ui.js';
 import { runBootstrap } from '../../lib/config.js';
+import { isManagedWorktreePath } from '../../lib/worktree.js';
 export async function bootstrapCommand() {
     try {
         const _ = await getRepoRoot();
         const worktrees = await listWorktrees();
+        const managedRoot = await getManagedWorktreesRoot();
         // 1. Select Worktree
         // Filter managed or just show all? The prompt said "managed", let's prioritize managed but maybe allow all if needed?
         // User requirements say "managed", sticking to that for consistency.
-        const managedWts = worktrees.filter(wt => wt.path.startsWith(WORKTREES_ROOT));
+        const managedWts = worktrees.filter(wt => isManagedWorktreePath(wt.path, managedRoot));
         if (managedWts.length === 0) {
             log.info('No managed worktrees found to bootstrap.');
             return;
         }
         const choices = managedWts.map(wt => {
-            const relative = path.relative(WORKTREES_ROOT, wt.path);
+            const relative = path.relative(managedRoot, wt.path);
             return {
                 name: `${chalk.bold(relative)} (${chalk.dim(wt.branch || wt.HEAD)})`,
                 value: wt.path,

package/dist/commands/wt/create-branch.js

@@ -3,19 +3,21 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream, publishBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
 import { detectInstalledOpenTools, launchOpenTool, promptOpenToolSelection, } from './open.js';
+import { enterCommand } from './enter.js';
 import { execa } from 'execa';
 import fs from 'fs-extra';
+export function shouldEnterCreatedWorktree(options) {
+    return options.enter !== false;
+}
 export async function createCommandNew(options) {
     try {
         const repoRoot = await getRepoRoot();
         log.info(`Repo: ${chalk.dim(repoRoot)}`);
-        if (options.enter !== undefined) {
-            log.warning('`--enter` / `--no-enter` is deprecated. Use `--open` / `--no-open` instead.');
-        }
+        const shouldEnterShell = shouldEnterCreatedWorktree(options);
         // 1. Gather inputs
         const currentBranch = await getCurrentBranch();
         const answers = await inquirer.prompt([
@@ -68,9 +70,7 @@ export async function createCommandNew(options) {
         const shouldBootstrap = options.bootstrap !== undefined ? options.bootstrap : answers.bootstrap;
         const shouldOpenTool = options.open !== undefined
             ? options.open
-            : options.enter !== undefined
-                ? options.enter
-                : Boolean(answers.shouldOpenTool);
+            : Boolean(answers.shouldOpenTool);
         let selectedTool;
         if (options.exec === undefined && shouldOpenTool) {
             const installedTools = await detectInstalledOpenTools();
@@ -89,7 +89,8 @@ export async function createCommandNew(options) {
         // e.g. feat/new-button -> feat-new-button
         const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
         const repoName = await getRepoName();
-        const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
+        const worktreePathConfig = await getWorktreePathConfig();
+        const wtPath = buildManagedWorktreePath(repoName, slug, worktreePathConfig);
         // 2. Validation
         if (!slug)
             throw new Error('Invalid name');
@@ -153,35 +154,47 @@ export async function createCommandNew(options) {
         if (shouldBootstrap) {
             await runBootstrap(wtPath, repoRoot);
         }
-        // 5. Exec Command
+        // 5. Post-create actions
         if (options.exec && options.exec.trim()) {
-            log.info(`Executing: ${options.exec} in ${ui.path(wtPath)}`);
-            try {
-                await execa(options.exec, {
-                    cwd: wtPath,
-                    stdio: 'inherit',
-                    shell: true
-                });
+            if (shouldEnterShell) {
+                await enterCommand(wtPath, { exec: options.exec });
             }
-            catch (error) {
-                log.actionableError(error.message, options.exec, wtPath, [
-                    `cd ${wtPath} && ${options.exec}`,
-                    'Check your command syntax and environment variables'
-                ]);
+            else {
+                log.info(`Executing: ${options.exec} in ${ui.path(wtPath)}`);
+                try {
+                    await execa(options.exec, {
+                        cwd: wtPath,
+                        stdio: 'inherit',
+                        shell: true
+                    });
+                }
+                catch (error) {
+                    log.actionableError(error.message, options.exec, wtPath, [
+                        `cd ${wtPath} && ${options.exec}`,
+                        'Check your command syntax and environment variables'
+                    ]);
+                }
             }
         }
-        else if (selectedTool) {
-            try {
-                log.info(`Opening ${ui.path(wtPath)} in ${chalk.cyan(selectedTool.name)}...`);
-                await launchOpenTool(selectedTool, wtPath);
+        else {
+            if (selectedTool) {
+                try {
+                    log.info(`Opening ${ui.path(wtPath)} in ${chalk.cyan(selectedTool.name)}...`);
+                    await launchOpenTool(selectedTool, wtPath);
+                }
+                catch (error) {
+                    log.warning(`Could not open ${selectedTool.name}: ${error.message}`);
+                }
             }
-            catch (error) {
-                log.warning(`Could not open ${selectedTool.name}: ${error.message}`);
+            if (shouldEnterShell) {
+                await enterCommand(wtPath);
             }
         }
         // 6. Final Output
         log.success('Worktree ready!');
-        log.header(`cd "${wtPath}"`);
+        if (!shouldEnterShell) {
+            log.header(`cd "${wtPath}"`);
+        }
     }
     catch (error) {
         log.actionableError(error.message, 'yggtree wt create');

package/dist/commands/wt/create-multi.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensureCorrectUpstream, publishBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { findLocalEnvFiles, promptAndCopyEnvFilesToWorktrees } from '../../lib/env-files.js';
 import { execa } from 'execa';
@@ -70,9 +70,10 @@ export async function createCommandMulti(options) {
         const createdWorktrees = [];
         // 3. Execution for each branch
         const repoName = await getRepoName();
+        const worktreePathConfig = await getWorktreePathConfig();
         for (const branchName of branchNames) {
             const slug = branchName.replace(/[\/\\]/g, '-').replace(/\s+/g, '-');
-            const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
+            const wtPath = buildManagedWorktreePath(repoName, slug, worktreePathConfig);
             log.header(`Processing: ${branchName}`);
             const wtSpinner = createSpinner(`Creating worktree at ${ui.path(wtPath)}...`).start();
             // Check if target branch already exists

package/dist/commands/wt/create-sandbox.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoRoot, getRepoName, getCurrentBranch } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { generateSandboxName, normalizeSandboxName, writeSandboxMeta } from '../../lib/sandbox.js';
 import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
@@ -136,7 +136,8 @@ export async function createSandboxCommand(options = {}) {
         }
         // 5. Create worktree
         const repoName = await getRepoName();
-        const wtPath = path.join(WORKTREES_ROOT, repoName, sandboxName);
+        const worktreePathConfig = await getWorktreePathConfig();
+        const wtPath = buildManagedWorktreePath(repoName, sandboxName, worktreePathConfig);
         const spinner = createSpinner('Creating sandbox worktree...').start();
         try {
             await fs.ensureDir(path.dirname(wtPath));

package/dist/commands/wt/create.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import path from 'path';
 import { getRepoName, createWorktree, fetchAll, listWorktrees } from '../../lib/git.js';
 import { runBootstrap } from '../../lib/config.js';
-import { WORKTREES_ROOT } from '../../lib/paths.js';
+import { buildManagedWorktreePath, getWorktreePathConfig } from '../../lib/global-config.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { ensureAutocompletePrompt } from '../../lib/prompt.js';
 import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
@@ -74,6 +74,30 @@ export function findExistingBranchWorktree(worktrees, branchName) {
         !wt.prunable &&
         fs.pathExistsSync(wt.path));
 }
+function normalizeExistingPath(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function findWorktreeByPath(worktrees, wtPath) {
+    const normalizedPath = normalizeExistingPath(wtPath);
+    return worktrees.find(wt => normalizeExistingPath(wt.path) === normalizedPath);
+}
+export function getWorktreePathCollisionMessage(worktreeName, wtPath, worktrees) {
+    if (!fs.pathExistsSync(wtPath))
+        return undefined;
+    const occupyingWorktree = findWorktreeByPath(worktrees, wtPath);
+    if (occupyingWorktree?.branch) {
+        return `Worktree name "${worktreeName}" is already used by branch "${occupyingWorktree.branch}".`;
+    }
+    if (occupyingWorktree?.prunable) {
+        return `Worktree path exists but Git marks its metadata as prunable: ${occupyingWorktree.prunable}.`;
+    }
+    return 'Worktree path already exists.';
+}
 export async function createCommand(options) {
     try {
         const repoRoot = await ensureRepoContext();
@@ -179,6 +203,9 @@ export async function createCommand(options) {
         }
         // 3. Gather remaining inputs
         const defaultSlug = toSlug(selectedBranch.branchName);
+        const repoName = await getRepoName();
+        const worktreePathConfig = await getWorktreePathConfig();
+        const resolveWorktreePath = (name) => buildManagedWorktreePath(repoName, toSlug(name), worktreePathConfig);
         const answers = await inquirer.prompt([
             {
                 type: 'input',
@@ -186,7 +213,12 @@ export async function createCommand(options) {
                 message: 'Worktree name (slug):',
                 default: options.name || defaultSlug,
                 when: !options.name,
-                validate: (input) => input.trim().length > 0 || 'Name is required',
+                validate: (input) => {
+                    const slug = toSlug(input);
+                    if (!slug)
+                        return 'Name is required';
+                    return getWorktreePathCollisionMessage(slug, resolveWorktreePath(input), existingWorktrees) || true;
+                },
             },
             {
                 type: 'confirm',
@@ -206,6 +238,20 @@ export async function createCommand(options) {
             },
         ]);
         const name = options.name || answers.name;
+        const slug = toSlug(name);
+        const wtPath = resolveWorktreePath(name);
+        // 4. Validation
+        if (!slug)
+            throw new Error('Invalid name');
+        const pathCollisionMessage = getWorktreePathCollisionMessage(slug, wtPath, existingWorktrees);
+        if (pathCollisionMessage) {
+            log.actionableError(pathCollisionMessage, `yggtree wc --name ${slug}`, wtPath, [
+                'Choose a different worktree name with --name',
+                `Inspect the occupying path: ls ${wtPath}`,
+                'Use yggtree wt prune only if Git reports stale worktree metadata',
+            ]);
+            return;
+        }
         const shouldBootstrap = options.bootstrap !== undefined ? options.bootstrap : answers.bootstrap;
         const shouldOpenTool = options.tool
             ? true
@@ -234,12 +280,6 @@ export async function createCommand(options) {
                 });
             }
         }
-        const slug = toSlug(name);
-        const repoName = await getRepoName();
-        const wtPath = path.join(WORKTREES_ROOT, repoName, slug);
-        // 4. Validation
-        if (!slug)
-            throw new Error('Invalid name');
         // 5. Execution (checkout-style: attach to selected branch)
         const spinner = createSpinner(`Creating worktree at ${ui.path(wtPath)}...`).start();
         try {