yggtree 1.4.3 → 1.4.4

package/README.md

@@ -146,7 +146,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 apply the winner back to your origin branch.
+
+🤝 **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.
@@ -217,7 +220,13 @@ Sometimes you don't want to "commit to a branch" yet. You just want to try somet
 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.
 
-Sandboxes are **not pushed to remote** and their names are randomly generated because they are meant to be temporary playgrounds.
+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:
+
+```bash
+yggtree handoff --name auth-refactor
+```
 
 ---
 
@@ -269,11 +278,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 +318,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.
@@ -354,6 +367,21 @@ 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 version of `create-sandbox --carry`: it keeps 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. 
@@ -415,20 +443,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 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 +467,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
 ```
 
@@ -531,12 +562,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:**
@@ -636,7 +667,7 @@ yggtree create-sandbox --carry
 **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`.

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

@@ -7,15 +7,17 @@ import { WORKTREES_ROOT } from '../../lib/paths.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();
@@ -153,35 +153,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.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,8 @@ export async function createCommand(options) {
         }
         // 3. Gather remaining inputs
         const defaultSlug = toSlug(selectedBranch.branchName);
+        const repoName = await getRepoName();
+        const resolveWorktreePath = (name) => path.join(WORKTREES_ROOT, repoName, toSlug(name));
         const answers = await inquirer.prompt([
             {
                 type: 'input',
@@ -186,7 +212,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 +237,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 +279,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 {

package/dist/commands/wt/handoff.js

@@ -0,0 +1,7 @@
+import { createSandboxCommand } from './create-sandbox.js';
+export async function handoffCommand(options = {}) {
+    await createSandboxCommand({
+        ...options,
+        carry: true,
+    });
+}

package/dist/commands/wt/open.js

@@ -25,9 +25,13 @@ export const OPEN_TOOL_CANDIDATES = [
         aliases: ['codex', 'codex-app'],
         bundleId: 'com.openai.codex',
     },
+    { id: 'cmux', name: 'Cmux Panel', command: 'cmux', kind: 'terminal', aliases: ['cmux', 'cmux-panel'] },
+    { id: 'tmux', name: 'Tmux Session', command: 'tmux', kind: 'terminal', aliases: ['tmux', 'tmux-session'] },
 ];
 const OTHER_COMMAND_ACTION = '__other_command__';
 const NO_OPEN_ACTION = '__no_open__';
+const OPEN_ACTION_PAGE_SIZE = 16;
+const CMUX_TERMINAL_STARTUP_DELAY_MS = 350;
 const yggtreeAccent = chalk.hex('#DEADED');
 function truncateEnd(value, maxLen) {
     if (maxLen <= 0)
@@ -61,9 +65,6 @@ function formatWorktreeChoiceLabel(type, branchName, displayPath, terminalColumn
 function openRail() {
     return yggtreeAccent('│');
 }
-function openSectionLabel(label) {
-    return `${yggtreeAccent('┌')} ${chalk.bold(label)}`;
-}
 function formatOpenColumns(name, command, detail) {
     const paddedName = name.padEnd(16);
     const paddedCommand = command.padEnd(13);
@@ -73,6 +74,51 @@ function formatOpenColumns(name, command, detail) {
 export function formatOpenToolChoice(tool) {
     return formatOpenColumns(tool.name, tool.command, '');
 }
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function formatTerminalSessionName(wtPath) {
+    const basename = path.basename(wtPath) || 'worktree';
+    const slug = basename.toLowerCase().replace(/[^a-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+    return `yggtree-${slug || 'worktree'}`.slice(0, 80);
+}
+export function buildTmuxLaunchCommand(wtPath, env = process.env) {
+    const sessionName = formatTerminalSessionName(wtPath);
+    if (env.TMUX) {
+        return {
+            executable: 'tmux',
+            args: ['new-window', '-c', wtPath, '-n', sessionName],
+        };
+    }
+    return {
+        executable: 'tmux',
+        args: ['new-session', '-A', '-s', sessionName, '-c', wtPath],
+    };
+}
+export function buildCmuxNewPaneCommand() {
+    return {
+        executable: 'cmux',
+        args: ['new-pane', '--type', 'terminal', '--direction', 'right', '--focus', 'true'],
+    };
+}
+export function parseCmuxSurfaceRef(output) {
+    return output.match(/\bsurface:\S+/)?.[0];
+}
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export function buildCmuxSendCommand(surfaceRef, wtPath) {
+    return {
+        executable: 'cmux',
+        args: ['send', '--surface', surfaceRef, `cd ${shellQuote(wtPath)}`],
+    };
+}
+export function buildCmuxEnterCommand(surfaceRef) {
+    return {
+        executable: 'cmux',
+        args: ['send-key', '--surface', surfaceRef, 'Enter'],
+    };
+}
 export function formatOpenSpecialChoice(value, allowShellAction) {
     if (value === OTHER_COMMAND_ACTION) {
         return formatOpenColumns('Other command', 'custom', 'run first, then stay in shell');
@@ -146,8 +192,23 @@ export function resolveOpenToolOption(input, installed) {
         tool.command.toLowerCase() === normalized ||
         tool.aliases?.some(alias => alias.toLowerCase() === normalized));
 }
+export function resolveOpenToolCandidate(input) {
+    const normalized = input.trim().toLowerCase();
+    return OPEN_TOOL_CANDIDATES.find(tool => tool.id === normalized ||
+        tool.command.toLowerCase() === normalized ||
+        tool.aliases?.some(alias => alias.toLowerCase() === normalized));
+}
+async function resolveKnownOpenToolOption(input) {
+    const candidate = resolveOpenToolCandidate(input);
+    if (!candidate)
+        return undefined;
+    const exists = candidate.bundleId
+        ? await macOSAppBundleExists(candidate.bundleId)
+        : await commandExists(candidate.command);
+    return exists ? candidate : undefined;
+}
 export async function resolveOpenToolAction(input, installed) {
-    let chosenTool = resolveOpenToolOption(input, installed);
+    let chosenTool = resolveOpenToolOption(input, installed) || await resolveKnownOpenToolOption(input);
     if (!chosenTool && await commandExists(input)) {
         chosenTool = {
             id: 'custom',
@@ -159,27 +220,11 @@ export async function resolveOpenToolAction(input, installed) {
     return chosenTool ? { type: 'tool', tool: chosenTool } : undefined;
 }
 export async function promptOpenToolSelection(installedTools, message = 'Select tool to open:') {
-    const ideChoices = installedTools
-        .filter(tool => tool.kind === 'editor')
+    const choices = installedTools
         .map(tool => ({
         name: formatOpenToolChoice(tool),
         value: tool,
     }));
-    const appChoices = installedTools
-        .filter(tool => tool.kind === 'app')
-        .map(tool => ({
-        name: formatOpenToolChoice(tool),
-        value: tool,
-    }));
-    const choices = [];
-    if (ideChoices.length > 0) {
-        choices.push(new inquirer.Separator(openSectionLabel('Editors & IDEs')));
-        choices.push(...ideChoices);
-    }
-    if (appChoices.length > 0) {
-        choices.push(new inquirer.Separator(openSectionLabel('Apps')));
-        choices.push(...appChoices);
-    }
     const { selectedTool } = await inquirer.prompt([
         {
             type: 'list',
@@ -187,79 +232,55 @@ export async function promptOpenToolSelection(installedTools, message = 'Select
             message,
             choices,
             loop: false,
-            pageSize: 10,
+            pageSize: OPEN_ACTION_PAGE_SIZE,
         },
     ]);
     return selectedTool;
 }
-export function buildOpenActionsFromSelection(selectedValues, installedTools, otherCommand) {
-    if (selectedValues.includes(NO_OPEN_ACTION))
+export function buildOpenActionsFromSelection(selectedValue, installedTools, otherCommand) {
+    if (selectedValue === NO_OPEN_ACTION)
         return [];
-    const actions = selectedValues
-        .filter(value => value.startsWith('tool:'))
-        .map(value => installedTools.find(tool => `tool:${tool.id}` === value))
-        .filter((tool) => Boolean(tool))
-        .map(tool => ({ type: 'tool', tool }));
-    if (selectedValues.includes(OTHER_COMMAND_ACTION) && otherCommand?.trim()) {
-        actions.push({ type: 'other-command', command: otherCommand.trim() });
+    if (selectedValue.startsWith('tool:')) {
+        const tool = installedTools.find(candidate => `tool:${candidate.id}` === selectedValue);
+        return tool ? [{ type: 'tool', tool }] : [];
     }
-    return actions;
-}
-export function validateOpenActionSelection(selectedValues) {
-    if (selectedValues.includes(NO_OPEN_ACTION) && selectedValues.length > 1) {
-        return 'Choose either "Nothing" or one or more actions, not both.';
+    if (selectedValue === OTHER_COMMAND_ACTION && otherCommand?.trim()) {
+        return [{ type: 'other-command', command: otherCommand.trim() }];
     }
-    return true;
+    return [];
 }
-export async function promptOpenActions(installedTools, options = {}) {
-    const allowShellAction = options.allowShellAction ?? true;
-    const choices = [];
-    if (installedTools.length > 0) {
-        const editorTools = installedTools.filter(tool => tool.kind === 'editor');
-        const appTools = installedTools.filter(tool => tool.kind === 'app');
-        if (editorTools.length > 0) {
-            choices.push(new inquirer.Separator(openSectionLabel('Editors & IDEs')));
-            choices.push(...editorTools.map(tool => ({
-                name: formatOpenToolChoice(tool),
-                value: `tool:${tool.id}`,
-            })));
-        }
-        if (appTools.length > 0) {
-            choices.push(new inquirer.Separator(openSectionLabel('Apps')));
-            choices.push(...appTools.map(tool => ({
-                name: formatOpenToolChoice(tool),
-                value: `tool:${tool.id}`,
-            })));
-        }
-    }
+export function buildOpenActionChoices(installedTools, allowShellAction) {
+    const choices = installedTools.map(tool => ({
+        name: formatOpenToolChoice(tool),
+        value: `tool:${tool.id}`,
+    }));
     if (allowShellAction) {
-        if (choices.length > 0)
-            choices.push(new inquirer.Separator(' '));
-        choices.push(new inquirer.Separator(openSectionLabel('Shell')));
         choices.push({
             name: formatOpenSpecialChoice(OTHER_COMMAND_ACTION, allowShellAction),
             value: OTHER_COMMAND_ACTION,
         });
     }
-    if (choices.length > 0)
-        choices.push(new inquirer.Separator(' '));
     choices.push({
         name: formatOpenSpecialChoice(NO_OPEN_ACTION, allowShellAction),
         value: NO_OPEN_ACTION,
     });
-    const { selectedValues } = await inquirer.prompt([
+    return choices;
+}
+export async function promptOpenActions(installedTools, options = {}) {
+    const allowShellAction = options.allowShellAction ?? true;
+    const choices = buildOpenActionChoices(installedTools, allowShellAction);
+    const { selectedValue } = await inquirer.prompt([
         {
-            type: 'checkbox',
-            name: 'selectedValues',
+            type: 'list',
+            name: 'selectedValue',
             message: options.message || 'Open anything before entering the shell?',
             choices,
             loop: false,
-            pageSize: 10,
-            validate: validateOpenActionSelection,
+            pageSize: OPEN_ACTION_PAGE_SIZE,
         },
     ]);
     let otherCommand;
-    if (selectedValues.includes(OTHER_COMMAND_ACTION)) {
+    if (selectedValue === OTHER_COMMAND_ACTION) {
         const answer = await inquirer.prompt([
             {
                 type: 'input',
@@ -270,9 +291,39 @@ export async function promptOpenActions(installedTools, options = {}) {
         ]);
         otherCommand = answer.otherCommand;
     }
-    return buildOpenActionsFromSelection(selectedValues, installedTools, otherCommand);
+    return buildOpenActionsFromSelection(selectedValue, installedTools, otherCommand);
 }
 export async function launchOpenTool(tool, wtPath) {
+    if (tool.id === 'cmux') {
+        const newPaneCommand = buildCmuxNewPaneCommand();
+        const newPaneResult = await execa(newPaneCommand.executable, newPaneCommand.args, {
+            cwd: wtPath,
+        });
+        const surfaceRef = parseCmuxSurfaceRef(newPaneResult.stdout);
+        if (!surfaceRef) {
+            throw new Error(`Cmux did not return a terminal surface handle: ${newPaneResult.stdout || '<empty output>'}`);
+        }
+        await delay(CMUX_TERMINAL_STARTUP_DELAY_MS);
+        const sendCommand = buildCmuxSendCommand(surfaceRef, wtPath);
+        await execa(sendCommand.executable, sendCommand.args, {
+            cwd: wtPath,
+            stdio: 'ignore',
+        });
+        const enterCommand = buildCmuxEnterCommand(surfaceRef);
+        await execa(enterCommand.executable, enterCommand.args, {
+            cwd: wtPath,
+            stdio: 'ignore',
+        });
+        return;
+    }
+    if (tool.id === 'tmux') {
+        const { executable, args } = buildTmuxLaunchCommand(wtPath);
+        await execa(executable, args, {
+            cwd: wtPath,
+            stdio: 'inherit',
+        });
+        return;
+    }
     const { executable, args } = buildOpenToolLaunchCommand(tool, wtPath);
     await execa(executable, args, {
         cwd: wtPath,
@@ -292,10 +343,14 @@ export function buildOpenToolLaunchCommand(tool, wtPath) {
     };
 }
 export async function runOpenActions(actions, wtPath, options = {}) {
+    let openedTerminal = false;
     for (const action of actions) {
         if (action.type === 'tool' && action.tool) {
             log.info(`Opening ${ui.path(wtPath)} in ${chalk.cyan(action.tool.name)}...`);
             await launchOpenTool(action.tool, wtPath);
+            if (action.tool.kind === 'terminal') {
+                openedTerminal = true;
+            }
         }
     }
     const shellAction = actions.find(action => action.type === 'other-command');
@@ -303,7 +358,7 @@ export async function runOpenActions(actions, wtPath, options = {}) {
         await enterCommand(wtPath, { exec: shellAction.command });
         return;
     }
-    if (options.enter !== false) {
+    if (options.enter !== false && !openedTerminal) {
         await enterCommand(wtPath);
     }
 }

package/dist/index.js

@@ -15,6 +15,7 @@ import { pathCommand } from './commands/wt/path.js';
 import { openCommand } from './commands/wt/open.js';
 import { applyCommand } from './commands/wt/apply.js';
 import { unapplyCommand } from './commands/wt/unapply.js';
+import { handoffCommand } from './commands/wt/handoff.js';
 import { getVersion } from './lib/version.js';
 import { notifyIfUpdateAvailable } from './lib/update-check.js';
 import { findSandboxRoot } from './lib/sandbox.js';
@@ -41,8 +42,8 @@ function registerWorktreeCommands(parent) {
         .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
         .option('--open', 'Open an editor after creation')
         .option('--no-open', 'Skip opening an editor after creation')
-        .addOption(new Option('--enter', 'Deprecated alias for --open').hideHelp())
-        .addOption(new Option('--no-enter', 'Deprecated alias for --no-open').hideHelp())
+        .option('--enter', 'Enter the worktree sub-shell after creation')
+        .option('--no-enter', 'Do not enter the worktree sub-shell after creation')
         .option('--exec <command>', 'Command to execute after creation')
         .action(async (branch, options) => {
         await createCommandNew({
@@ -66,7 +67,7 @@ function registerWorktreeCommands(parent) {
             .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
             .option('--open', 'Open editors or run a startup command before entering')
             .option('--no-open', 'Skip opening editors or startup commands before entering')
-            .option('--tool <command>', 'Editor or app command to open after checkout (skips open prompt)')
+            .option('--tool <command>', 'Editor, app, or terminal command to open after checkout (skips open prompt)')
             .addOption(new Option('--enter', 'Enter the worktree sub-shell after checkout/opening').hideHelp())
             .option('--no-enter', 'Do not enter the worktree sub-shell after checkout/opening')
             .option('--exec <command>', 'Command to execute after creation')
@@ -87,8 +88,8 @@ function registerWorktreeCommands(parent) {
         await deleteCommand(options);
     });
     parent.command('open [worktree]')
-        .description('Open a worktree in an editor or supported app')
-        .option('--tool <command>', 'Editor or app command to use (e.g. cursor, code, codex-app)')
+        .description('Open a worktree in an editor, supported app, or terminal target')
+        .option('--tool <command>', 'Editor, app, or terminal command to use (e.g. cursor, code, codex-app, tmux)')
         .option('--enter', 'Enter the worktree sub-shell after opening')
         .addOption(new Option('--no-enter', 'Do not enter the worktree sub-shell after opening').hideHelp())
         .action(async (worktree, options) => {
@@ -126,6 +127,18 @@ function registerWorktreeCommands(parent) {
         .action(async (options) => {
         await createSandboxCommand(options);
     });
+    parent.command('handoff')
+        .description('Carry uncommitted work into a sandbox worktree')
+        .option('-n, --name <name>', 'Optional handoff name (prompted when omitted)')
+        .option('--no-bootstrap', 'Skip bootstrap (npm install + submodules)')
+        .option('--open', 'Open an editor after creation')
+        .option('--no-open', 'Skip opening an editor after creation')
+        .addOption(new Option('--enter', 'Deprecated alias for --open').hideHelp())
+        .addOption(new Option('--no-enter', 'Deprecated alias for --no-open').hideHelp())
+        .option('--exec <command>', 'Command to execute after creation')
+        .action(async (options) => {
+        await handoffCommand(options);
+    });
     parent.command('apply')
         .description('Apply sandbox changes to origin directory')
         .action(applyCommand);
@@ -158,6 +171,7 @@ program
         { name: `🌿 Grow New Realm ${chalk.dim('(create worktree)')}`, value: 'create-smart' },
         { name: `🔀 Traverse to Another Realm ${chalk.dim('(checkout existing branch in new worktree)')}`, value: 'worktree-checkout' },
         { name: `🌳 Grow Many Realms ${chalk.dim('(create multiple worktrees)')}`, value: 'create-multi' },
+        { name: `🤝 Hand Off Current Work ${chalk.dim('(carry dirty work into a sandbox)')}`, value: 'handoff' },
         { name: `🧪 Forge Sandbox Realm ${chalk.dim('(create sandbox worktree)')}`, value: 'create-sandbox' },
         { name: `🗺️  Survey Realms ${chalk.dim('(list worktrees)')}`, value: 'list' },
         { name: `🧭 Open Realm in Editor ${chalk.dim('(open worktree in editor)')}`, value: 'open' },
@@ -240,6 +254,9 @@ program
         case 'create-sandbox':
             await createSandboxCommand({ bootstrap: true });
             break;
+        case 'handoff':
+            await handoffCommand({ bootstrap: true });
+            break;
         case 'bifrost':
             await bifrostCommand();
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yggtree",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "packageManager": "pnpm@11.0.9",
   "description": "Interactive CLI for managing git worktrees and configs",
   "main": "dist/index.js",