feat: add --existing flag to wm add for resuming work on remote branches

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rubenfiszel

bin/src/worktree-commands.test.ts

@@ -89,6 +89,20 @@ describe("parseAddCommandArgs", () => {
     } satisfies ParsedAddCommand);
   });
 
+  it("parses --existing flag", () => {
+    expect(parseAddCommandArgs(["feature/search", "--existing"])).toEqual({
+      input: { branch: "feature/search", mode: "existing" },
+      detach: false,
+    });
+  });
+
+  it("parses --existing with other flags", () => {
+    expect(parseAddCommandArgs(["feature/search", "--existing", "--agent", "claude", "--detach"])).toEqual({
+      input: { branch: "feature/search", mode: "existing", agent: "claude" },
+      detach: true,
+    });
+  });
+
   it("parses --detach flag", () => {
     expect(parseAddCommandArgs(["feature/search", "--detach"])).toEqual({
       input: { branch: "feature/search" },
@@ -205,6 +219,37 @@ describe("runWorktreeCommand", () => {
     expect(switchCalls).toEqual([{ projectDir: "/repo", branch: "feature/search" }]);
   });
 
+  it("dispatches add --existing with mode existing", async () => {
+    const { runtime, calls } = makeRuntime();
+    const stdout: string[] = [];
+
+    const exitCode = await runWorktreeCommand(
+      {
+        command: "add",
+        args: ["feature/remote-branch", "--existing"],
+        projectDir: "/repo",
+        port: 5111,
+      },
+      {
+        createRuntime: () => runtime,
+        stdout: (message) => stdout.push(message),
+        switchToTmuxWindow: () => {},
+      },
+    );
+
+    expect(exitCode).toBe(0);
+    expect(calls).toEqual([
+      {
+        method: "createWorktree",
+        value: {
+          branch: "feature/remote-branch",
+          mode: "existing",
+        },
+      },
+    ]);
+    expect(stdout).toEqual(["Created worktree feature/remote-branch"]);
+  });
+
   it("skips tmux switch when --detach is passed to add", async () => {
     const { runtime } = makeRuntime();
     const stdout: string[] = [];

bin/src/worktree-commands.ts

@@ -70,9 +70,10 @@ export function getWorktreeCommandUsage(command: WorktreeSubcommand): string {
     case "add":
       return [
         "Usage:",
-        "  webmux add [branch] [--base <branch>] [--profile <name>] [--agent <claude|codex>] [--prompt <text>] [--env KEY=VALUE] [--detach]",
+        "  webmux add [branch] [--existing] [--base <branch>] [--profile <name>] [--agent <claude|codex>] [--prompt <text>] [--env KEY=VALUE] [--detach]",
         "",
         "Options:",
+        "  --existing               Use an existing local or remote branch instead of creating a new one",
         "  --base <branch>         Base branch for a new worktree (defaults to config)",
         "  --profile <name>         Worktree profile from .webmux.yaml",
         "  --agent <claude|codex>   Agent to launch in the worktree",
@@ -159,6 +160,11 @@ export function parseAddCommandArgs(args: string[]): ParsedAddCommand | null {
       return null;
     }
 
+    if (arg === "--existing") {
+      input.mode = "existing";
+      continue;
+    }
+
     if (arg === "--detach" || arg === "-d") {
       detach = true;
       continue;