yggtree 1.4.2 → 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.
 
@@ -223,21 +273,21 @@ Options:
 
 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`
-* `--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 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-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 +349,12 @@ 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 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.
 
@@ -351,99 +413,53 @@ 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 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.
 
@@ -451,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.
 
@@ -474,7 +490,7 @@ Optional:
 
 ---
 
-### `yggtree wt prune`
+### `yggtree prune`
 
 Clean up stale git worktree metadata.
 
@@ -500,7 +516,7 @@ Yggdrasil is ideal when:
 **Command:**
 
 ```
-yggtree wt create feat/login-flow
+yggtree create feat/login-flow
 ```
 
 **What happens:**
@@ -508,7 +524,7 @@ 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>
@@ -520,13 +536,13 @@ yggtree wt create feat/login-flow
 **Command:**
 
 ```
-yggtree wt create feat/cleanup-api --no-bootstrap --no-open
+yggtree create feat/cleanup-api --no-bootstrap --no-open
 ```
 
 **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 +554,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 +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>
@@ -593,7 +609,7 @@ yggtree wt enter test --exec "codex"
 **Command:**
 
 ```
-yggtree wt path test
+yggtree path test
 ```
 
 **Output:**
@@ -614,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:**
@@ -622,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,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 { promptAndCopyEnvFiles } from '../../lib/env-files.js';
 import { detectInstalledOpenTools, launchOpenTool, promptOpenToolSelection, } from './open.js';
 import { execa } from 'execa';
 import fs from 'fs-extra';
@@ -56,7 +57,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,
             },
@@ -148,6 +149,7 @@ export async function createCommandNew(options) {
                 'Attempt to push manually: git push -u origin HEAD',
             ]);
         }
+        await promptAndCopyEnvFiles(repoRoot, wtPath);
         if (shouldBootstrap) {
             await runBootstrap(wtPath, repoRoot);
         }

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);
             }
         }

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

@@ -6,6 +6,7 @@ import { runBootstrap } from '../../lib/config.js';
 import { WORKTREES_ROOT } from '../../lib/paths.js';
 import { log, ui, createSpinner } from '../../lib/ui.js';
 import { generateSandboxName, normalizeSandboxName, writeSandboxMeta } from '../../lib/sandbox.js';
+import { promptAndCopyEnvFiles } from '../../lib/env-files.js';
 import { detectInstalledOpenTools, launchOpenTool, promptOpenToolSelection, } from './open.js';
 import { execa } from 'execa';
 import fs from 'fs-extra';
@@ -66,7 +67,7 @@ export async function createSandboxCommand(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,
             },
@@ -181,6 +182,7 @@ export async function createSandboxCommand(options = {}) {
         spinner.succeed(`Sandbox created: ${chalk.cyan(sandboxName)}`);
         log.dim('This is a local sandbox - no remote branch will be pushed.');
         // 8. Bootstrap
+        await promptAndCopyEnvFiles(repoRoot, wtPath);
         if (shouldBootstrap) {
             await runBootstrap(wtPath, repoRoot);
         }