yggtree 1.4.1 → 1.4.3

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
@@ -118,9 +168,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 +192,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,10 +212,10 @@ 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** and their names are randomly generated because they are meant to be temporary playgrounds.
 
@@ -208,7 +258,7 @@ Open the interactive menu.
 
 ---
 
-### `yggtree wt create [branch]`
+### `yggtree create [branch]`
 
 Create a worktree from a branch.
 
@@ -218,26 +268,26 @@ Options:
 * `--base <ref>`
 * `--source local|remote`
 * `--no-bootstrap`
-* `--enter / --no-enter`
+* `--open / --no-open`
 * `--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.
 * `--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 +295,46 @@ 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`
-* `--enter / --no-enter`
+* `--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`)
+* `--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.
+* Editor choices can be selected together.
+* Use `--tool` to skip the open prompt and launch one editor/app directly.
+* `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-enter
+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.
 
@@ -281,18 +343,18 @@ Options:
 *   `-n, --name <name>`: Optional sandbox name (auto-generated if omitted).
 *   `--carry / --no-carry`: Bring uncommitted changes (staged/unstaged/untracked) with you.
 *   `--no-bootstrap`
-*   `--enter / --no-enter`
+*   `--open / --no-open`
 *   `--exec "<command>"`
 
 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 apply`
 
 Apply changes from the current sandbox back to the origin repository. 
 *   **Backs up** origin files before overwriting.
@@ -300,7 +362,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 +370,7 @@ Undo a previous `apply` operation.
 
 ---
 
-### `yggtree wt create-multi`
+### `yggtree create-multi`
 
 Create multiple worktrees at once.
 
@@ -322,14 +384,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.
 
@@ -338,6 +400,7 @@ Columns:
 * TYPE (`MAIN`, `MANAGED`, `LINKED`, `SANDBOX`)
 * STATE (clean / dirty)
 * LAST ACTIVE
+* PR (optional — requires [GitHub CLI](https://cli.github.com/))
 * BRANCH
 
 Notes:
@@ -346,76 +409,57 @@ Notes:
 * `SANDBOX` and `MANAGED` are worktrees inside `~/.yggtree`.
 * 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.
 
 ---
 
-### `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 open [worktree]`
+### `yggtree open [worktree]`
 
-Open a worktree in an IDE or agent CLI.
+Open a worktree in an editor or supported desktop app.
 
 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`.
+* Lets you choose one or more editors/apps interactively, or pass `--tool`.
+* By default, `open` launches editors/apps and returns.
+* 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`, or `codex-app`)
 
 <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 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.
 
@@ -423,13 +467,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.
 
@@ -446,7 +490,7 @@ Optional:
 
 ---
 
-### `yggtree wt prune`
+### `yggtree prune`
 
 Clean up stale git worktree metadata.
 
@@ -467,12 +511,12 @@ Yggdrasil is ideal when:
 ## 📝 Practical Examples
 
 <details>
-<summary>Create a worktree and enter it immediately</summary>
+<summary>Create a worktree with the guided post-create flow</summary>
 
 **Command:**
 
 ```
-yggtree wt create feat/login-flow
+yggtree create feat/login-flow
 ```
 
 **What happens:**
@@ -480,25 +524,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
-* Drops you into a sub-shell inside the worktree
+* Lets you choose whether to open an editor after creation
 
 
 </details>
 ---
 
 <details>
-<summary>Create a worktree without bootstrap and without entering</summary>
+<summary>Create a worktree without bootstrap and without opening a tool</summary>
 
 **Command:**
 
 ```
-yggtree wt create feat/cleanup-api --no-bootstrap --no-enter
+yggtree create feat/cleanup-api --no-bootstrap --no-open
 ```
 
 **When to use:**
 
 * You just want the folder ready
-* You’ll enter it later
+* You’ll open it or move into its shell later if needed
 * You don’t want installs running automatically
 
 </details>
@@ -510,14 +554,13 @@ yggtree wt create feat/cleanup-api --no-bootstrap --no-enter
 **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>
@@ -529,31 +572,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>
@@ -565,7 +609,7 @@ yggtree wt enter test --exec "codex"
 **Command:**
 
 ```
-yggtree wt path test
+yggtree path test
 ```
 
 **Output:**
@@ -586,7 +630,7 @@ 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:**
@@ -594,7 +638,7 @@ yggtree wt create-sandbox --carry
 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.
 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,14 +5,17 @@ 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 { buildAgentExecCommand, detectInstalledOpenTools, isAgentTool, launchOpenTool, promptOpenToolSelection, } from './open.js';
+import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
+import { detectInstalledOpenTools, launchOpenTool, promptOpenToolSelection, } from './open.js';
 import { execa } from 'execa';
-import { spawn } from 'child_process';
 import fs from 'fs-extra';
 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.');
+        }
         // 1. Gather inputs
         const currentBranch = await getCurrentBranch();
         const answers = await inquirer.prompt([
@@ -51,28 +54,25 @@ export async function createCommandNew(options) {
                 default: true,
                 when: options.bootstrap !== false && options.bootstrap !== true,
             },
-            {
-                type: 'confirm',
-                name: 'shouldEnter',
-                message: 'Do you want to enter the new worktree now?',
-                default: true,
-                when: options.enter === undefined,
-            },
             {
                 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,
+                when: options.exec === undefined && options.open === undefined && options.enter === undefined,
             },
         ]);
         const branchName = options.branch || answers.branch;
         let baseRef = options.base || answers.base;
         const source = options.source || answers.source;
-        const shouldEnter = options.enter !== undefined ? options.enter : answers.shouldEnter;
         const shouldBootstrap = options.bootstrap !== undefined ? options.bootstrap : answers.bootstrap;
+        const shouldOpenTool = options.open !== undefined
+            ? options.open
+            : options.enter !== undefined
+                ? options.enter
+                : Boolean(answers.shouldOpenTool);
         let selectedTool;
-        if (options.exec === undefined && answers.shouldOpenTool) {
+        if (options.exec === undefined && shouldOpenTool) {
             const installedTools = await detectInstalledOpenTools();
             if (installedTools.length === 0) {
                 log.warning('No IDE/agent tool detected in PATH. Skipping open step.');
@@ -81,7 +81,6 @@ export async function createCommandNew(options) {
                 selectedTool = await promptOpenToolSelection(installedTools, 'Select tool to open:');
             }
         }
-        const execCommandStr = options.exec || (selectedTool && isAgentTool(selectedTool) ? buildAgentExecCommand(selectedTool) : undefined);
         // Append origin/ if remote is selected and not already present
         if (!options.base && source === 'remote' && !baseRef.startsWith('origin/')) {
             baseRef = `origin/${baseRef}`;
@@ -150,27 +149,28 @@ 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
-        if (execCommandStr && execCommandStr.trim()) {
-            log.info(`Executing: ${execCommandStr} in ${ui.path(wtPath)}`);
+        if (options.exec && options.exec.trim()) {
+            log.info(`Executing: ${options.exec} in ${ui.path(wtPath)}`);
             try {
-                await execa(execCommandStr, {
+                await execa(options.exec, {
                     cwd: wtPath,
                     stdio: 'inherit',
                     shell: true
                 });
             }
             catch (error) {
-                log.actionableError(error.message, execCommandStr, wtPath, [
-                    `cd ${wtPath} && ${execCommandStr}`,
+                log.actionableError(error.message, options.exec, wtPath, [
+                    `cd ${wtPath} && ${options.exec}`,
                     'Check your command syntax and environment variables'
                 ]);
             }
         }
-        if (selectedTool && !isAgentTool(selectedTool)) {
+        else if (selectedTool) {
             try {
                 log.info(`Opening ${ui.path(wtPath)} in ${chalk.cyan(selectedTool.name)}...`);
                 await launchOpenTool(selectedTool, wtPath);
@@ -181,21 +181,7 @@ export async function createCommandNew(options) {
         }
         // 6. Final Output
         log.success('Worktree ready!');
-        if (shouldEnter) {
-            log.info(`Spawning sub-shell in ${ui.path(wtPath)}...`);
-            log.dim('Type "exit" to return to the main terminal.');
-            const shell = process.env.SHELL || 'zsh';
-            const child = spawn(shell, [], {
-                cwd: wtPath,
-                stdio: 'inherit',
-            });
-            child.on('close', () => {
-                log.info('Exited sub-shell.');
-            });
-        }
-        else {
-            log.header(`cd "${wtPath}"`);
-        }
+        log.header(`cd "${wtPath}"`);
     }
     catch (error) {
         log.actionableError(error.message, 'yggtree wt create');

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

@@ -5,6 +5,7 @@ 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 { findLocalEnvFiles, promptAndCopyEnvFilesToWorktrees } from '../../lib/env-files.js';
 import { execa } from 'execa';
 import fs from 'fs-extra';
 export async function createCommandMulti(options) {
@@ -117,8 +118,16 @@ export async function createCommandMulti(options) {
                 ]);
             }
             createdWorktrees.push(wtPath);
-            // 4. Bootstrap
-            if (shouldBootstrap) {
+        }
+        const envFiles = await findLocalEnvFiles(repoRoot);
+        if (envFiles.length > 0 && createdWorktrees.length > 0) {
+            await promptAndCopyEnvFilesToWorktrees(repoRoot, createdWorktrees, envFiles, {
+                promptMessage: `Copy local env file${envFiles.length === 1 ? '' : 's'} to all created worktrees? (${envFiles.join(', ')})`,
+            });
+        }
+        // 4. Bootstrap
+        if (shouldBootstrap) {
+            for (const wtPath of createdWorktrees) {
                 await runBootstrap(wtPath, repoRoot);
             }
         }