worktree-add 1.2.1 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # worktree-add
 
-Create a Git worktree next to your current repo for a branch, copy useful local files, install deps, and open it in your editor.
+Create a Git worktree next to your current repo for a branch, copy useful local files, install deps, and open it in your apps.
 
 ## What it does
 
@@ -8,19 +8,21 @@ Running `worktree-add <branch>` from inside a repo:
 
 1. Normalizes `<branch>` (supports `origin/foo`, `refs/heads/foo`, etc.).
 2. Refuses if that branch is already checked out in any worktree.
-3. Warns if local and `origin/<branch>` heads differ and asks how to resolve.
-4. Picks a destination next to your current repo: `../<repo>-<safe-branch>`.
-5. If the destination exists, asks before moving it to the system trash.
-6. Fetches `origin/<branch>` when needed and creates a git worktree:
+3. Picks a destination next to your current repo: `../<repo>-<safe-branch>`.
+4. If the destination exists, pass `--interactive` to be prompted for confirmation, or `--yes` to move it to the system trash without prompting. Without either flag, the command exits.
+5. Fetches `origin/<branch>` and refreshes your local branch when safe:
+   - fast-forwards the local branch if it’s strictly behind `origin/<branch>`
+   - warns and keeps the local branch as-is if it’s ahead/diverged
+6. Creates a git worktree:
    - reuses an existing local branch
    - or creates a tracking branch from `origin/<branch>`
-   - or creates a new branch from the current `HEAD`
+   - or creates a new branch from the current `HEAD` (only when the branch does not exist on `origin/`, or when you pass `--offline` and `origin/` can’t be reached)
 7. Copies untracked / ignored files into the new worktree, skipping heavy stuff
    (`node_modules`, `dist`, `.next`, caches, virtualenvs, etc.).
 8. Detects your package manager and installs dependencies with lockfile‑safe flags
    (`npm ci`, `pnpm install --frozen-lockfile`, `yarn install --immutable`, etc.).
 9. If the project uses Next.js and supports it, runs `next typegen`.
-10. Opens the new worktree in your editor.
+10. Opens the new worktree in your requested apps (if any).
 
 Your original checkout is left untouched.
 
@@ -28,6 +30,7 @@ Your original checkout is left untouched.
 
 - Node.js ≥ 22.14.0
 - Git with `git worktree` support
+- Git credentials configured for `origin/` (the tool is non-interactive and won’t prompt for authentication)
 
 ## Install / run
 
@@ -49,7 +52,7 @@ Run it from anywhere inside an existing worktree of the repo.
 
 ```bash
 # inside /my/path/my-app
-worktree-add <branch>
+worktree-add <branch> [options]
 ```
 
 Run this inside an existing worktree of your project—the tool discovers the repo root from your current directory and creates the sibling worktree next to it.
@@ -62,8 +65,19 @@ Example:
 worktree-add feature/login-form
 ```
 
+Common options:
+
+```text
+  -a, --app <name>   Open the worktree in an app (repeatable)
+  --offline          Create from HEAD when origin can't be reached
+  -y, --yes          Skip confirmation and replace existing destination
+  --interactive      Allow confirmation prompts (requires a TTY)
+  --dry-run          Show what would happen without making changes
+  --verbose          Show progress messages on stderr
+```
+
 A new branch from the current HEAD is created only when the branch does not already
-exist locally or on `origin/`.
+exist locally or on `origin/`. If `origin/` can’t be reached and the branch doesn’t exist locally, the tool aborts unless you pass `--offline`.
 
 Destination directory (assuming repo named `my-app`):
 
@@ -72,27 +86,44 @@ Destination directory (assuming repo named `my-app`):
 /my/path/my-app-feature-login-form  # new worktree for branch "feature/login-form"
 ```
 
-## Editor control
+## Pipeline examples
 
-By default the tool opens the new worktree in:
+```bash
+# create a worktree for the newest local branch
+git for-each-ref --sort=-committerdate --format="%(refname:short)" refs/heads \
+  | head -n1 \
+  | xargs worktree-add
+
+# create a worktree for the first feature branch
+git branch --format="%(refname:short)" \
+  | grep '^feature/' \
+  | head -n1 \
+  | xargs worktree-add
+```
 
-1. `--editor <command>` if passed
-2. `WORKTREE_ADD_EDITOR` env var
-3. otherwise `code`
+## App control
 
-Only simple command names are allowed (no `;`, `&`, pipes, etc.) to avoid shell injection. Examples:
+After creating the worktree, the tool can open it in one or more apps. Nothing is opened by default.
+App names are executed on your machine, so only use values you trust. Validation is a UX guardrail (not a security boundary): it only blocks control characters to prevent common mistakes, while other punctuation is allowed because `open` uses platform launchers (macOS `open`, Windows PowerShell) and makes no security guarantees.
+Arguments are not parsed: values like `code -w` are treated as part of the app name and will likely fail.
 
-```bash
-worktree-add feature/foo -e code
-WORKTREE_ADD_EDITOR=vim worktree-add feature/foo
-```
+1. `--app <name>` flag (repeatable): `worktree-add feature/foo --app ghostty --app code`
+2. `WORKTREE_ADD_APP` env var (comma-separated): `WORKTREE_ADD_APP=ghostty,code worktree-add feature/foo`
+
+CLI flags take priority over the env var.
+To explicitly open nothing even when `WORKTREE_ADD_APP` is set, pass `--app ""`.
+Whitespace-only values like `--app "   "` are treated as absent and do not override `WORKTREE_ADD_APP`.
+
+If launching an app fails to start, the worktree still stays created and ready.
 
-If launching the editor fails, the worktree still stays created and ready.
+Platform note: on macOS the app value is passed to `open -a`, so use an application name like `Visual Studio Code` (or an `.app` path). On Linux/Windows it’s typically treated as an executable name/path.
 
-Tip: add a shell helper with your preferred editor in your shell profile. Example snippet to add:
+Terminal-based editors (vim/nvim/nano) are not supported via `--app` — apps are launched detached from the current terminal.
+
+Tip: add a shell helper with your preferred apps in your shell profile:
 
 ```bash
-worktree-add() { WORKTREE_ADD_EDITOR=cursor command worktree-add "$@" }
+worktree-add() { WORKTREE_ADD_APP=ghostty,code command worktree-add "$@" }
 ```
 
 Add it to your shell profile:
@@ -101,6 +132,10 @@ Add it to your shell profile:
 - bash: `~/.bashrc` or `~/.bash_profile`
 - fish: `~/.config/fish/config.fish`
 
+## Agent rule
+
+If you are an automated agent, read and follow `AGENTS.md` (and `CLAUDE.md` if present) at the repo root before making changes.
+
 ## License
 
 MIT

package/dist/app/get-unsafe-app-name-reason.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Defense-in-depth filter for app names passed to the `open` package.
+ *
+ * This is not intended as shell-injection mitigation. In `open@11` (currently
+ * used by this repo), the implementation uses `child_process.spawn()` without
+ * `shell: true`, but the exact subprocess differs by platform (macOS: `open -a`,
+ * Linux: usually `xdg-open` unless an explicit app is provided, Windows:
+ * PowerShell). This comment is informational, not a guarantee — treat this
+ * filter as a UX/diagnostics guardrail rather than a security boundary.
+ */
+export declare function getUnsafeAppNameReason(appName: string): string | undefined;

package/dist/app/get-unsafe-app-name-reason.js

@@ -0,0 +1,21 @@
+/**
+ * Defense-in-depth filter for app names passed to the `open` package.
+ *
+ * This is not intended as shell-injection mitigation. In `open@11` (currently
+ * used by this repo), the implementation uses `child_process.spawn()` without
+ * `shell: true`, but the exact subprocess differs by platform (macOS: `open -a`,
+ * Linux: usually `xdg-open` unless an explicit app is provided, Windows:
+ * PowerShell). This comment is informational, not a guarantee — treat this
+ * filter as a UX/diagnostics guardrail rather than a security boundary.
+ */
+export function getUnsafeAppNameReason(appName) {
+    for (const character of appName) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === undefined)
+            continue;
+        if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+            return "contains control characters";
+        }
+    }
+    return undefined;
+}

package/dist/app/resolve-apps.d.ts

@@ -0,0 +1,6 @@
+interface ResolveAppsInput {
+    optionApps?: string[];
+    environmentApps?: string;
+}
+export declare function resolveApps({ optionApps, environmentApps, }: ResolveAppsInput): string[];
+export {};

package/dist/app/resolve-apps.js

@@ -0,0 +1,31 @@
+function dedupePreserveOrder(apps) {
+    const seen = new Set();
+    const deduped = [];
+    for (const app of apps) {
+        if (seen.has(app))
+            continue;
+        seen.add(app);
+        deduped.push(app);
+    }
+    return deduped;
+}
+export function resolveApps({ optionApps, environmentApps, }) {
+    const hasExplicitEmptyOption = optionApps?.includes("") ?? false;
+    const normalizedOptionApps = optionApps?.map((app) => app.trim()).filter(Boolean) ?? [];
+    if (optionApps !== undefined) {
+        if (normalizedOptionApps.length > 0) {
+            return dedupePreserveOrder(normalizedOptionApps);
+        }
+        if (hasExplicitEmptyOption) {
+            return [];
+        }
+    }
+    const normalized = environmentApps?.trim();
+    if (normalized) {
+        return dedupePreserveOrder(normalized
+            .split(",")
+            .map((app) => app.trim())
+            .filter(Boolean));
+    }
+    return [];
+}

package/dist/cli/cleanup-worktree.d.ts

@@ -0,0 +1,2 @@
+import type { StatusLogger } from "../output/create-status-logger.js";
+export declare function cleanupWorktree(destinationDirectory: string, logger: StatusLogger, reason: string): void;

package/dist/cli/cleanup-worktree.js

@@ -0,0 +1,13 @@
+import { removeWorktree } from "../git/remove-worktree.js";
+export function cleanupWorktree(destinationDirectory, logger, reason) {
+    logger.warn(`Cleaning up worktree at ${JSON.stringify(destinationDirectory)} ${reason}.`);
+    try {
+        removeWorktree(destinationDirectory);
+    }
+    catch (cleanupError) {
+        const cleanupMessage = cleanupError instanceof Error
+            ? cleanupError.message
+            : String(cleanupError);
+        logger.warn(`Failed to clean up worktree at ${JSON.stringify(destinationDirectory)}: ${cleanupMessage}`);
+    }
+}

package/dist/cli/open-worktree-apps.d.ts

@@ -0,0 +1,5 @@
+import type { StatusLogger } from "../output/create-status-logger.js";
+export declare function openWorktreeApps(destinationDirectory: string, apps: string[], options?: {
+    dryRun?: boolean;
+    logger?: StatusLogger;
+}): Promise<void>;

package/dist/cli/open-worktree-apps.js

@@ -0,0 +1,33 @@
+import open from "open";
+import { getStatusLogger } from "../output/get-status-logger.js";
+import { getUnsafeAppNameReason } from "../app/get-unsafe-app-name-reason.js";
+export async function openWorktreeApps(destinationDirectory, apps, options = {}) {
+    const logger = getStatusLogger(options.logger);
+    const dryRun = options.dryRun ?? false;
+    await Promise.allSettled(apps.map(async (app) => {
+        const unsafeReason = getUnsafeAppNameReason(app);
+        if (unsafeReason) {
+            logger.warn(`Skipping app ${JSON.stringify(app)}: ${unsafeReason}.`);
+            return;
+        }
+        if (dryRun) {
+            logger.step(`Would open ${JSON.stringify(destinationDirectory)} in ${JSON.stringify(app)}`);
+            return;
+        }
+        logger.step(`Opening ${JSON.stringify(app)} …`);
+        try {
+            await open(destinationDirectory, {
+                app: { name: [app] },
+                wait: false,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const looksLikeArguments = /\s--?\S/u.test(app);
+            const argumentHint = looksLikeArguments
+                ? ' Note: application arguments are not supported; pass only the application name (for example, "code" instead of "code --wait").'
+                : "";
+            logger.warn(`Failed to open ${JSON.stringify(app)}: ${message}.${argumentHint}`);
+        }
+    }));
+}

package/dist/cli/register-sigint-handler.d.ts

@@ -0,0 +1,8 @@
+import type { StatusLogger } from "../output/create-status-logger.js";
+type SigintHandlerOptions = {
+    readonly destinationDirectory: string;
+    readonly logger: StatusLogger;
+    readonly onCleanup: () => void;
+};
+export declare function registerSigintHandler(options: SigintHandlerOptions): () => void;
+export {};

package/dist/cli/register-sigint-handler.js

@@ -0,0 +1,19 @@
+export function registerSigintHandler(options) {
+    let handled = false;
+    const handler = () => {
+        if (handled) {
+            // eslint-disable-next-line unicorn/no-process-exit -- CLI exits on SIGINT
+            process.exit(130);
+        }
+        handled = true;
+        options.logger.warn("Received SIGINT. Aborting.");
+        options.onCleanup();
+        console.error(`Worktree creation aborted. If cleanup failed, the directory may be incomplete at ${JSON.stringify(options.destinationDirectory)}.`);
+        // eslint-disable-next-line unicorn/no-process-exit -- CLI exits on SIGINT
+        process.exit(130);
+    };
+    process.on("SIGINT", handler);
+    return () => {
+        process.off("SIGINT", handler);
+    };
+}

package/dist/cli/resolve-worktree-context.d.ts

@@ -0,0 +1,6 @@
+export type WorktreeContext = {
+    readonly branch: string;
+    readonly repoRoot: string;
+    readonly destinationDirectory: string;
+};
+export declare function resolveWorktreeContext(branchRaw: string): WorktreeContext;

package/dist/cli/resolve-worktree-context.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { exitWithMessage, findWorktreeByBranchName, getRepositoryName, git, normalizeBranchName, toSafePathSegment, } from "../git/git.js";
+export function resolveWorktreeContext(branchRaw) {
+    const branch = normalizeBranchName(branchRaw);
+    if (branch.length === 0) {
+        exitWithMessage("Branch name is empty.\n" +
+            "Examples: `feature/foo`, `origin/feature/foo`, `refs/heads/feature/foo`.\n" +
+            "Note: `origin/` without a branch name is not valid.");
+    }
+    const existingWorktree = findWorktreeByBranchName(branch);
+    if (existingWorktree) {
+        exitWithMessage(`Branch '${branch}' is already checked out in: ${existingWorktree}\n` +
+            "You cannot add another worktree for the same branch.\n" +
+            "Open that worktree instead or remove it before retrying.\n" +
+            "If that path no longer exists, run `git worktree prune` and retry.");
+    }
+    const repoRoot = git("rev-parse", "--show-toplevel");
+    const repoName = getRepositoryName();
+    const branchDirectorySegment = toSafePathSegment(branch);
+    const destinationDirectory = path.join(path.dirname(repoRoot), `${repoName}-${branchDirectorySegment}`);
+    return { branch, repoRoot, destinationDirectory };
+}

package/dist/cli/run-worktree-add.d.ts

@@ -0,0 +1,9 @@
+export type CliOptions = {
+    readonly app?: string[];
+    readonly offline?: boolean;
+    readonly yes?: boolean;
+    readonly interactive?: boolean;
+    readonly dryRun?: boolean;
+    readonly verbose?: boolean;
+};
+export declare function runWorktreeAdd(branchRaw: string, options: CliOptions): Promise<void>;

package/dist/cli/run-worktree-add.js

@@ -0,0 +1,100 @@
+import { createStatusLogger } from "../output/create-status-logger.js";
+import { resolveApps } from "../app/resolve-apps.js";
+import { handleExistingDirectory } from "../worktree/destination-directory.js";
+import { copyUntrackedFiles } from "../worktree/untracked-file-copy.js";
+import { setupProject } from "../project/setup.js";
+import { exitWithMessage } from "../git/git.js";
+import { createWorktree } from "../git/create-worktree.js";
+import { fetchRemoteBranch } from "../git/fetch-remote-branch.js";
+import { cleanupWorktree } from "./cleanup-worktree.js";
+import { openWorktreeApps } from "./open-worktree-apps.js";
+import { registerSigintHandler } from "./register-sigint-handler.js";
+import { resolveWorktreeContext } from "./resolve-worktree-context.js";
+export async function runWorktreeAdd(branchRaw, options) {
+    const dryRun = options.dryRun ?? false;
+    const verbose = options.verbose ?? false;
+    const logger = createStatusLogger({
+        dryRun,
+        verbose,
+        decorate: process.stderr.isTTY && !Object.hasOwn(process.env, "NO_COLOR"),
+    });
+    const interactive = options.interactive ?? false;
+    const assumeYes = options.yes ?? false;
+    const context = resolveWorktreeContext(branchRaw);
+    let worktreeCreated = false;
+    const cleanupIfNeeded = (reason) => {
+        if (!worktreeCreated || dryRun)
+            return;
+        cleanupWorktree(context.destinationDirectory, logger, reason);
+    };
+    const unregisterSigintHandler = registerSigintHandler({
+        destinationDirectory: context.destinationDirectory,
+        logger,
+        onCleanup: () => {
+            cleanupIfNeeded("after interruption");
+        },
+    });
+    try {
+        const shouldContinue = await handleExistingDirectory(context.destinationDirectory, {
+            dryRun,
+            assumeYes,
+            interactive,
+            logger,
+        });
+        if (!shouldContinue) {
+            return;
+        }
+        const remoteStatus = (() => {
+            try {
+                return fetchRemoteBranch(context.branch, { dryRun, logger });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const prefix = `Failed to fetch origin/${context.branch}: `;
+                const failure = message.startsWith(prefix)
+                    ? message
+                    : `${prefix}${message}`;
+                exitWithMessage(`${failure}\n` +
+                    "If you expected this to work, check your network/credentials and retry.\n" +
+                    "If you want a new local branch from HEAD instead, pass --offline.");
+            }
+        })();
+        if (remoteStatus.status === "unknown" &&
+            !remoteStatus.localExists &&
+            !options.offline) {
+            exitWithMessage(`Could not reach origin to check whether '${context.branch}' exists, and the branch does not exist locally.\n` +
+                "Refusing to create a new branch from HEAD in this ambiguous state.\n" +
+                `Re-run with --offline to force creating a new local '${context.branch}' from the current HEAD.`);
+        }
+        // Only treat origin as existing when confirmed; "unknown" remains false.
+        const remoteBranchExists = remoteStatus.status === "exists";
+        createWorktree(context.branch, context.destinationDirectory, {
+            remoteBranchExists,
+            dryRun,
+            logger,
+        });
+        if (!dryRun) {
+            worktreeCreated = true;
+        }
+        await copyUntrackedFiles(context.repoRoot, context.destinationDirectory, {
+            dryRun,
+            logger,
+        });
+        await setupProject(context.destinationDirectory, { dryRun, logger });
+        const apps = resolveApps({
+            optionApps: options.app,
+            environmentApps: process.env.WORKTREE_ADD_APP,
+        });
+        await openWorktreeApps(context.destinationDirectory, apps, {
+            dryRun,
+            logger,
+        });
+    }
+    catch (error) {
+        cleanupIfNeeded("due to failure");
+        throw error;
+    }
+    finally {
+        unregisterSigintHandler();
+    }
+}

package/dist/cli.d.ts

@@ -6,10 +6,4 @@
  * Note: the destination is placed next to whichever worktree you run this from,
  * not necessarily the original "main" checkout.
  */
-interface ResolveEditorInput {
-    optionEditor?: string;
-    environmentEditor?: string;
-}
-export declare function resolveEditor({ optionEditor, environmentEditor, }?: ResolveEditorInput): string;
-export declare function isEditorCommandSafe(editor: string): boolean;
 export {};

package/dist/cli.js

@@ -6,95 +6,57 @@
  * Note: the destination is placed next to whichever worktree you run this from,
  * not necessarily the original "main" checkout.
  */
-import { spawnSync } from "node:child_process";
-import path from "node:path";
-import { Command } from "commander";
+import { Command } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
-import { git, getRepositoryName, normalizeBranchName, toSafePathSegment, findWorktreeByBranchName, exitWithMessage, } from "./git/git.js";
-import { copyUntrackedFiles } from "./worktree/untracked-file-copy.js";
-import { fetchRemoteBranch, createWorktree } from "./git/worktree-creation.js";
-import { resolveBranchHeadMismatch } from "./git/resolve-branch-head-mismatch.js";
-import { handleExistingDirectory } from "./worktree/destination-directory.js";
-import { setupProject } from "./project/setup.js";
-export function resolveEditor({ optionEditor, environmentEditor, } = {}) {
-    const normalizedOption = optionEditor?.trim();
-    const normalizedEnvironment = environmentEditor?.trim();
-    return normalizedOption || normalizedEnvironment || "code";
-}
-export function isEditorCommandSafe(editor) {
-    const normalized = editor.normalize("NFKC");
-    const trimmed = normalized.trim();
-    // Reject empty or excessively long commands
-    if (trimmed.length === 0 || trimmed.length > 256) {
-        return false;
-    }
-    // Reject common shell metacharacters, whitespace, and control characters to prevent injection
-    const unsafeCharacters = /[\\;&|`$(){}<>\s]|\p{Cc}/u;
-    return !unsafeCharacters.test(trimmed);
-}
-async function main(branchRaw, options) {
-    const branch = normalizeBranchName(branchRaw);
-    // Prevent attempting to add a worktree for a branch that is already checked out
-    const existingWorktree = findWorktreeByBranchName(branch);
-    if (existingWorktree) {
-        exitWithMessage(`Branch '${branch}' is already checked out in: ${existingWorktree}\n` +
-            "You cannot add another worktree for the same branch.\n" +
-            "Open that worktree instead or remove it before retrying.");
-    }
-    const shouldContinue = await resolveBranchHeadMismatch(branch);
-    if (!shouldContinue) {
-        process.exitCode = 1;
-        return;
-    }
-    // Determine destination directory for the new worktree
-    const repoRoot = git("rev-parse", "--show-toplevel");
-    const repoName = getRepositoryName();
-    const branchDirectorySegment = toSafePathSegment(branch);
-    const destinationDirectory = path.join(path.dirname(repoRoot), `${repoName}-${branchDirectorySegment}`);
-    // Check if destination directory already exists
-    await handleExistingDirectory(destinationDirectory);
-    // Step 1: Fetch remote branch if it exists
-    fetchRemoteBranch(branch);
-    // Step 2: Create the worktree
-    createWorktree(branch, destinationDirectory);
-    // Step 3: Copy untracked files, excluding any on the denylist
-    await copyUntrackedFiles(repoRoot, destinationDirectory);
-    // Step 4: Install dependencies and run project-specific setup
-    await setupProject(destinationDirectory);
-    // Step 5: Open the new worktree in the editor
-    const editor = resolveEditor({
-        optionEditor: options.editor,
-        environmentEditor: process.env.WORKTREE_ADD_EDITOR,
-    });
-    // Validate editor command to prevent injection attacks
-    if (!isEditorCommandSafe(editor)) {
-        exitWithMessage("Invalid editor command: shell metacharacters not allowed.\n" +
-            "Please use a simple editor name (e.g., 'code', 'cursor', 'vim').");
-    }
-    console.log(`➤ Opening ${editor} …`);
-    const result = spawnSync(editor, [destinationDirectory], {
-        stdio: "inherit",
-    });
-    if (result.error) {
-        console.error(`Failed to open ${editor}: ${result.error.message}`);
-        console.error("The worktree was created successfully, but the editor could not be opened.");
-    }
+import { runWorktreeAdd } from "./cli/run-worktree-add.js";
+function collectApp(app, previous) {
+    return [...(previous ?? []), app];
 }
 const program = new Command()
     .name(packageJson.name)
     .description("Create or reuse a Git worktree for a branch as a sibling of the current worktree")
     .version(packageJson.version)
     .argument("<branch>", "branch name for the worktree")
-    .option("-e, --editor <command>", "Editor to open the worktree with (default: WORKTREE_ADD_EDITOR env var or 'code')")
+    .option("-a, --app <name>", "Open the worktree in an app (repeatable)", collectApp)
+    .option("--offline", "Allow creating a new local branch from HEAD when origin cannot be reached and the branch does not exist locally")
+    .option("-y, --yes", "Skip confirmation and replace existing destination")
+    .option("--dry-run", "Show what would happen without making changes")
+    .option("--interactive", "Allow confirmation prompts (requires a TTY)")
+    .option("--verbose", "Show progress messages on stderr")
+    .showHelpAfterError("(add --help for additional information)")
+    .showSuggestionAfterError()
+    .addHelpText("after", `
+Examples:
+  $ worktree-add feature/login-form
+  $ worktree-add feature/api --app code
+  $ WORKTREE_ADD_APP=ghostty,code worktree-add feature/new-branch
+  $ git branch --format="%(refname:short)" | head -n1 | xargs worktree-add
+
+App notes:
+  - App names are executed on your machine; only use values you trust.
+  - Arguments are not parsed; pass only the app name (e.g., "code", not "code --wait").
+  - WORKTREE_ADD_APP is a comma-separated list of apps (alternative to repeating --app).
+  - To explicitly open nothing when WORKTREE_ADD_APP is set, pass --app "".
+
+Dependencies:
+  - git (with worktree support)
+  - a package manager when package.json is present (npm, pnpm, yarn, bun, deno)
+`)
     .action(async (branch, options) => {
     try {
-        await main(branch, options);
+        await runWorktreeAdd(branch, options);
     }
     catch (error) {
-        console.error(error);
+        if (options.verbose) {
+            console.error(error);
+        }
+        else {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(message);
+        }
         process.exitCode = 1;
     }
 });
 if (!process.env.VITEST) {
-    program.parse();
+    await program.parseAsync();
 }

package/dist/git/create-worktree.d.ts

@@ -0,0 +1,9 @@
+import type { StatusLogger } from "../output/create-status-logger.js";
+/**
+ * Create a worktree for the given branch at the specified destination.
+ */
+export declare function createWorktree(branch: string, destinationDirectory: string, options?: {
+    remoteBranchExists?: boolean;
+    dryRun?: boolean;
+    logger?: StatusLogger;
+}): void;

package/dist/git/create-worktree.js

@@ -0,0 +1,39 @@
+import { getStatusLogger } from "../output/get-status-logger.js";
+import { git, localBranchExists, normalizeBranchName, remoteBranchExists, } from "./git.js";
+import { extractDiagnosticLine } from "./extract-diagnostic-line.js";
+/**
+ * Create a worktree for the given branch at the specified destination.
+ */
+export function createWorktree(branch, destinationDirectory, options) {
+    const logger = getStatusLogger(options?.logger);
+    const dryRun = options?.dryRun ?? false;
+    const normalized = normalizeBranchName(branch);
+    if (localBranchExists(normalized)) {
+        logger.step(`${dryRun ? "Would run " : ""}git worktree add -- ${destinationDirectory} refs/heads/${normalized}`);
+        if (dryRun)
+            return;
+        git("worktree", "add", "--", destinationDirectory, `refs/heads/${normalized}`);
+        return;
+    }
+    let branchExistsOnOrigin = options?.remoteBranchExists;
+    if (branchExistsOnOrigin === undefined) {
+        try {
+            branchExistsOnOrigin = remoteBranchExists(normalized);
+        }
+        catch (error) {
+            const diagnostic = extractDiagnosticLine(error);
+            throw new Error(`Failed to reach origin to check whether '${normalized}' exists: ${diagnostic}`);
+        }
+    }
+    if (branchExistsOnOrigin) {
+        logger.step(`${dryRun ? "Would run " : ""}git worktree add --track -b ${normalized} -- ${destinationDirectory} origin/${normalized}`);
+        if (dryRun)
+            return;
+        git("worktree", "add", "--track", "-b", normalized, "--", destinationDirectory, `origin/${normalized}`);
+        return;
+    }
+    logger.step(`${dryRun ? "Would run " : ""}git worktree add -b ${normalized} -- ${destinationDirectory}`);
+    if (dryRun)
+        return;
+    git("worktree", "add", "-b", normalized, "--", destinationDirectory);
+}

package/dist/git/extract-diagnostic-line.d.ts

@@ -0,0 +1 @@
+export declare function extractDiagnosticLine(error: unknown): string;