yggtree 1.4.2 → 1.4.4

package/README.md

@@ -7,22 +7,69 @@
 
 Like the mythical world tree connecting realms, Yggdrasil lets you grow isolated, parallel environments where ideas can evolve independently without colliding.
 
+For guided workflows, command examples, and safety notes, read the full docs:
+**[yggtree.logbookfordevs.com/docs](https://yggtree.logbookfordevs.com/docs)**.
+
 ---
 
 ## 🚀 Quick Start
 
 ### Installation
 
-Run without installing:
+Install globally:
+
+```bash
+npm install -g yggtree
+```
+
+Or try it without installing:
 
 ```bash
 npx yggtree
 ```
 
-Or install globally:
+### Agent Skills
+
+An agent skill is now available for your favorite agents.
+
+`yggtree` ships one consolidated skill that helps agents choose the right
+worktree workflow first, then load the smallest reference they need:
+
+* **Create a task worktree**: start a brand-new branch-backed task in parallel.
+* **Branch off without stashing**: jump into another branch without disturbing
+  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.
+
+This skill is especially useful with agents like **Claude Code**,
+**Codex**, **Cursor**, **Gemini CLI**, and other tools that support the open
+Skills ecosystem.
+
+Install it with the Skills CLI:
 
 ```bash
-npm install -g yggtree
+npx skills add logbookfordevs/yggdrasil-worktree
+```
+
+Install it globally for your user:
+
+```bash
+npx skills add logbookfordevs/yggdrasil-worktree --global
+```
+
+Install only the consolidated `yggtree` skill:
+
+```bash
+npx skills add logbookfordevs/yggdrasil-worktree --skill yggtree
+```
+
+If your agent supports targeted installs, you can also point the install to a
+specific agent runtime, for example:
+
+```bash
+npx skills add logbookfordevs/yggdrasil-worktree --agent codex
 ```
 
 ### Basic Usage
@@ -36,11 +83,14 @@ yggtree
 Or use commands directly:
 
 ```bash
-yggtree wt create
-yggtree wt list
-yggtree wt enter my-feature
+yggtree create
+yggtree list
+yggtree wc --ref my-feature
+yggtree -v
 ```
 
+The older `yggtree wt ...` form still works for compatibility, but direct commands are the preferred shape.
+
 ---
 
 ## 🧠 Mental Model
@@ -96,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.
@@ -118,9 +171,9 @@ Use the interactive UI or drive everything through commands and flags.
 ## 🧠 Parallel Development, Done Right
 
 ```bash
-yggtree wt create feat/city-selection
-yggtree wt create fix/validation
-yggtree wt create chore/cleanup-api
+yggtree create feat/city-selection
+yggtree create fix/validation
+yggtree create chore/cleanup-api
 ```
 
 Each command creates:
@@ -142,8 +195,8 @@ Yggdrasil shines when paired with AI agents.
 Instead of running agents against the same directory, you can assign **one worktree per agent**.
 
 ```bash
-yggtree wt create feat/ai-refactor-a --exec "cursor ."
-yggtree wt create feat/ai-refactor-b --exec "codex"
+yggtree create feat/ai-refactor-a --exec "cursor ."
+yggtree create feat/ai-refactor-b --exec "codex"
 ```
 
 Each agent operates in its own realm:
@@ -162,12 +215,18 @@ Sometimes you don't want to "commit to a branch" yet. You just want to try somet
 
 **Sandboxes** are temporary, local-only worktrees designed for this:
 
-1.  **Create**: `yggtree wt create-sandbox` (creates something like `sandbox-a3f2_feature-branch`).
+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 wt apply` to "push" those file changes back to your origin directory.
-4.  **Unapply**: Don't like it? `yggtree wt unapply` restores your origin to exactly how it was before.
+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**. 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:
 
-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
+```
 
 ---
 
@@ -208,7 +267,7 @@ Open the interactive menu.
 
 ---
 
-### `yggtree wt create [branch]`
+### `yggtree create [branch]`
 
 Create a worktree from a branch.
 
@@ -219,25 +278,27 @@ 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 a tool after creation (IDE or agent CLI).
+* 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>
 <summary>Example</summary>
 
 ```bash
-yggtree wt create feat/new-ui --base main --exec "cursor ."
+yggtree create feat/new-ui --base main --exec "cursor ."
 ```
 
 </details>
 
 ---
 
-### `yggtree wt worktree-checkout [name] [ref]`
+### `yggtree worktree-checkout [name] [ref]`
 
 Create a checkout-style worktree from an existing branch.
 
@@ -245,34 +306,48 @@ Behavior:
 
 * Prompts a searchable branch picker (type to filter in real time).
 * Attaches the new worktree directly to the selected branch (checkout-style).
+* If a branch exists both locally and on `origin`, the picker shows both `branch` (local) and `origin/branch` (remote tip, detached) as explicit choices.
 * If you select a remote-only branch (`origin/*`), yggtree creates the local branch in the new worktree automatically.
-* If that branch already has an active yggtree-managed worktree, yggtree falls back to entering that worktree instead of creating a duplicate.
+* If that branch already has an active worktree, yggtree falls back to using that worktree instead of creating a duplicate.
+* By default, yggtree ends the flow inside the worktree shell.
+* `yggtree wc` is a short alias for the same flow.
 
 Options:
 
 * `-n, --name <slug>`
 * `-r, --ref <ref>`: skip picker and use a specific branch (`feature/x` or `origin/feature/x`)
 * `--no-bootstrap`
-* `--open / --no-open`
+* `--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, 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:
 
-* Instead of asking for a free-form `exec` command, yggtree now asks if you want to open a tool after creation (IDE or agent CLI).
+* Yggtree asks what to open before starting the worktree shell.
+* 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.
 
 <details>
 <summary>Example</summary>
 
 ```bash
-yggtree wt worktree-checkout -n hotfix-auth -r main --no-open
+yggtree worktree-checkout -n hotfix-auth -r main --no-open
+yggtree wc hotfix-auth main --open
+yggtree wc hotfix-auth main --tool codex-app
+yggtree wc hotfix-auth main --open --no-enter
 ```
 
 </details>
 
 ---
 
-### `yggtree wt create-sandbox`
+### `yggtree create-sandbox`
 
 Create a temporary sandbox from your current local branch.
 
@@ -287,12 +362,27 @@ Options:
 Interactive flow:
 
 * Prompts for an optional sandbox name (leave empty to auto-generate one from current branch).
-* Instead of asking for a free-form `exec` command, yggtree now asks if you want to open a tool after creation (IDE or agent CLI).
+* Instead of asking for a free-form `exec` command, yggtree now asks if you want to open an editor after creation.
 * `--exec` remains available as an advanced explicit override.
 
 ---
 
-### `yggtree wt apply`
+### `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. 
 *   **Backs up** origin files before overwriting.
@@ -300,7 +390,7 @@ Apply changes from the current sandbox back to the origin repository.
 
 ---
 
-### `yggtree wt unapply`
+### `yggtree unapply`
 
 Undo a previous `apply` operation.
 *   Restores origin files from the sandbox's backup.
@@ -308,7 +398,7 @@ Undo a previous `apply` operation.
 
 ---
 
-### `yggtree wt create-multi`
+### `yggtree create-multi`
 
 Create multiple worktrees at once.
 
@@ -322,14 +412,14 @@ Options:
 <summary>Example</summary>
 
 ```bash
-yggtree wt create-multi --base main
+yggtree create-multi --base main
 ```
 
 </details>
 
 ---
 
-### `yggtree wt list`
+### `yggtree list`
 
 List all repo-linked worktrees with state.
 
@@ -351,99 +441,56 @@ Notes:
 
 ---
 
-### `yggtree wt enter [worktree]`
-
-Enter a worktree using a sub‑shell.
-
-* Uses your default shell
-* Type `exit` to return
-
-Optional:
-
-* `--exec "<command>"`
-
-<details>
-<summary>Example</summary>
-
-```bash
-yggtree wt enter feat/new-ui --exec "npm test"
-```
-
-</details>
-
----
-
-### `yggtree wt close`
-
-Gracefully exit a worktree sub-shell with an option to delete it.
-
-Behavior:
-
-* Only works inside an Yggdrasil sub-shell (entered via `wt enter` or post-creation).
-* Asks whether you want to delete the worktree before leaving.
-* Includes double-confirmation for safety.
-* Main worktree is never offered for deletion.
-
-<details>
-<summary>Example</summary>
-
-```bash
-# Inside a worktree sub-shell:
-yggtree wt close
-# → "Delete this worktree before leaving? (y/N)"
-# → If yes: removes the worktree, then exits
-# → If no: exits normally
-```
-
-</details>
-
----
-
-### `yggtree wt open [worktree]`
+### `yggtree open [worktree]`
 
-Open a worktree in an IDE or agent CLI.
+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 tool commands in your `PATH` (for example: IDEs like `cursor`, `code`, `zed`; agents like `claude`, `codex`, `gemini`, `opencode`).
-* Lets you choose one interactively, or pass `--tool`.
-* If an agent CLI is selected, yggtree opens a sub-shell and launches it there.
+* 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`.
+* 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>`
+* `--tool <command>` (for example: `cursor`, `code`, `codex`, `codex-app`, `cmux`, or `tmux`)
 
 <details>
 <summary>Examples</summary>
 
 ```bash
-yggtree wt open
-yggtree wt open feat/new-ui --tool cursor
-yggtree wt open feat/new-ui --tool claude
-yggtree wt list --open
+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
 ```
 
 </details>
 
 ---
 
-### `yggtree wt exec [worktree] -- <command>`
+### `yggtree exec [worktree] -- <command>`
 
-Run a command inside a worktree **without entering**.
+Run a command inside a worktree without changing your current terminal.
 
 <details>
 <summary>Example</summary>
 
 ```bash
-yggtree wt exec feat/new-ui -- npm test
+yggtree exec feat/new-ui -- npm test
 ```
 
 </details>
 
 ---
 
-### `yggtree wt path [worktree]`
+### `yggtree path [worktree]`
 
 Print a `cd` command for a worktree.
 
@@ -451,13 +498,13 @@ Useful for scripting and shell aliases.
 
 ---
 
-### `yggtree wt bootstrap`
+### `yggtree bootstrap`
 
 Re‑run bootstrap commands for a worktree.
 
 ---
 
-### `yggtree wt delete`
+### `yggtree delete`
 
 Interactively delete worktrees.
 
@@ -474,7 +521,7 @@ Optional:
 
 ---
 
-### `yggtree wt prune`
+### `yggtree prune`
 
 Clean up stale git worktree metadata.
 
@@ -500,7 +547,7 @@ Yggdrasil is ideal when:
 **Command:**
 
 ```
-yggtree wt create feat/login-flow
+yggtree create feat/login-flow
 ```
 
 **What happens:**
@@ -508,25 +555,25 @@ yggtree wt create feat/login-flow
 * Creates a new branch if it doesn’t exist (without inheriting base tracking), then publishes it to `origin` when possible
 * Creates a dedicated worktree
 * Runs bootstrap if enabled
-* Lets you choose whether to open an IDE or agent after creation
+* Lets you choose whether to open an editor after creation
 
 
 </details>
 ---
 
 <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 wt create feat/cleanup-api --no-bootstrap --no-open
+yggtree create feat/cleanup-api --no-bootstrap --no-open --no-enter
 ```
 
 **When to use:**
 
 * You just want the folder ready
-* You’ll open or enter it later if needed
+* You’ll open it or move into its shell later if needed
 * You don’t want installs running automatically
 
 </details>
@@ -538,14 +585,13 @@ yggtree wt create feat/cleanup-api --no-bootstrap --no-open
 **Command:**
 
 ```
-yggtree wt create feat/ui-refactor --exec "cursor ."
+yggtree create feat/ui-refactor --exec "cursor ."
 ```
 
 Works with:
 
 * `cursor .`
 * `code .`
-* `codex`
 * Any custom command available in your shell
 
 </details>
@@ -557,31 +603,32 @@ Works with:
 **Command:**
 
 ```
-yggtree wt exec test -- npm test
+yggtree exec test -- npm test
 ```
 
 **What this does:**
 
 * Runs the command inside the selected worktree
-* Does not enter a sub-shell
+* Keeps your current terminal where it is
 * Ideal for CI-like checks, scripts, or quick validations
 
 </details>
 ---
 
 <details>
-<summary>Enter a worktree and run a command before entering</summary>
+<summary>Checkout a branch and run a startup command</summary>
 
 **Command:**
 
 ```
-yggtree wt enter test --exec "codex"
+yggtree wc --ref test --open
 ```
 
 **What happens:**
 
-* Executes the command inside the worktree
-* Then drops you into a sub-shell
+* Checks out or reuses the branch worktree
+* Lets you choose an editor, supported app, or `Other command...`
+* Starts a worktree shell unless you pass `--no-enter`
 * Type `exit` to return to your original directory
 
 </details>
@@ -593,7 +640,7 @@ yggtree wt enter test --exec "codex"
 **Command:**
 
 ```
-yggtree wt path test
+yggtree path test
 ```
 
 **Output:**
@@ -614,15 +661,15 @@ Useful when you want to manually navigate or copy the path into scripts.
 **Command:**
 
 ```bash
-yggtree wt create-sandbox --carry
+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 wt apply`.
+4.  If it works: `yggtree apply`.
 5.  If it fails: Just delete the sandbox or `unapply`.
 
 </details>

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

@@ -5,16 +5,19 @@ import { getRepoRoot, getRepoName, verifyRef, fetchAll, getCurrentBranch, ensure
 import { runBootstrap } from '../../lib/config.js';
 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([
@@ -56,7 +59,7 @@ export async function createCommandNew(options) {
             {
                 type: 'confirm',
                 name: 'shouldOpenTool',
-                message: 'Open a tool after creation? (IDE or agent CLI)',
+                message: 'Open an editor after creation?',
                 default: false,
                 when: options.exec === undefined && options.open === undefined && options.enter === undefined,
             },
@@ -67,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();
@@ -148,38 +149,51 @@ export async function createCommandNew(options) {
                 'Attempt to push manually: git push -u origin HEAD',
             ]);
         }
+        await promptAndCopyEnvFiles(repoRoot, wtPath);
         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');