Merge pull request #302 from windmill-labs/feat/switch-worktree-profile

feat: switch a worktree to another profile after creation

Author: diegoimbert

README.md

@@ -10,7 +10,7 @@ A web dashboard for managing parallel AI coding agents. webmux owns git worktree
 
 ![create worktree](https://github.com/windmill-labs/webmux/raw/main/site/static/videos/create.gif)
 
-Spin up new worktrees with one click. Pick a profile, type a prompt, and webmux creates the worktree, starts the agent, and begins streaming output. Merge or remove worktrees when you're done.
+Spin up new worktrees with one click. Pick a profile, type a prompt, and webmux creates the worktree, starts the agent, and begins streaming output. Changed your mind about the profile? Switch it later from the worktree menu (or `webmux profile <branch> <profile>`) — the session restarts with the new pane layout and commands, resuming the agent conversation. Merge or remove worktrees when you're done.
 
 ### Embedded Terminals
 

backend/src/__tests__/lifecycle-service.test.ts

@@ -270,6 +270,21 @@ const NO_DEFAULT_PROFILE_CONFIG: ProjectConfig = {
   },
 };
 
+const SWITCHABLE_PROFILE_CONFIG: ProjectConfig = {
+  ...TEST_CONFIG,
+  profiles: {
+    ...TEST_CONFIG.profiles,
+    full: {
+      runtime: "host",
+      envPassthrough: [],
+      panes: [
+        { id: "agent", kind: "agent", focus: true },
+        { id: "backend", kind: "command", split: "right", command: "bun run dev" },
+      ],
+    },
+  },
+};
+
 function makeLifecycleService(
   repoRoot: string,
   tmux: FakeTmuxGateway,
@@ -1463,6 +1478,141 @@ describe("LifecycleService", () => {
     expect(await Bun.file(paths.controlEnvPath).exists()).toBe(false);
   });
 
+  it("rebuilds an open worktree session with the panes of the profile it switches to", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const lifecycle = makeLifecycleService(
+      repoRoot,
+      tmux,
+      runtime,
+      new FakeDockerGateway(),
+      new FakeHookRunner(),
+      SWITCHABLE_PROFILE_CONFIG,
+    );
+
+    await lifecycle.createWorktree({ branch: "feature-profile", profile: "default" });
+    tmux.commands.length = 0;
+
+    const result = await lifecycle.setWorktreeProfile("feature-profile", "full");
+
+    expect(result).toEqual({ profile: "full", restarted: true });
+
+    const worktreePath = join(repoRoot, "__worktrees", "feature-profile");
+    const gitDir = new BunGitGateway().resolveWorktreeGitDir(worktreePath);
+    const meta = await readWorktreeMeta(gitDir);
+    expect(meta?.profile).toBe("full");
+    expect(meta?.runtime).toBe("host");
+    expect(runtime.getWorktreeByBranch("feature-profile")?.profile).toBe("full");
+
+    expect(tmux.listWindows()).toEqual([
+      {
+        sessionName: buildProjectSessionName(repoRoot),
+        windowName: buildWorktreeWindowName("feature-profile"),
+        paneCount: 2,
+      },
+    ]);
+    expect(tmux.commands.map((entry) => entry.command)).toContainEqual("bun run dev");
+    expect(tmux.commands[0]?.command).toContain("claude");
+  });
+
+  it("keeps a closed worktree closed and applies the new profile on the next open", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const lifecycle = makeLifecycleService(
+      repoRoot,
+      tmux,
+      runtime,
+      new FakeDockerGateway(),
+      new FakeHookRunner(),
+      SWITCHABLE_PROFILE_CONFIG,
+    );
+
+    await lifecycle.createWorktree({ branch: "feature-profile-closed", profile: "default" });
+    await lifecycle.closeWorktree("feature-profile-closed");
+
+    const result = await lifecycle.setWorktreeProfile("feature-profile-closed", "full");
+
+    expect(result).toEqual({ profile: "full", restarted: false });
+    expect(tmux.listWindows()).toEqual([]);
+
+    tmux.commands.length = 0;
+    await lifecycle.openWorktree("feature-profile-closed");
+
+    expect(tmux.listWindows()[0]?.paneCount).toBe(2);
+    expect(tmux.commands.map((entry) => entry.command)).toContainEqual("bun run dev");
+  });
+
+  it("tears down the container when a worktree leaves its docker profile", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const docker = new FakeDockerGateway();
+    const lifecycle = makeLifecycleService(
+      repoRoot,
+      tmux,
+      runtime,
+      docker,
+      new FakeHookRunner(),
+      SWITCHABLE_PROFILE_CONFIG,
+    );
+
+    await lifecycle.createWorktree({ branch: "feature-profile-docker", profile: "sandbox" });
+
+    const result = await lifecycle.setWorktreeProfile("feature-profile-docker", "full");
+
+    expect(result).toEqual({ profile: "full", restarted: true });
+    expect(docker.removed).toEqual(["feature-profile-docker"]);
+    expect(docker.launched).toHaveLength(1);
+
+    const worktreePath = join(repoRoot, "__worktrees", "feature-profile-docker");
+    const gitDir = new BunGitGateway().resolveWorktreeGitDir(worktreePath);
+    expect((await readWorktreeMeta(gitDir))?.runtime).toBe("host");
+    const controlEnvText = await Bun.file(getWorktreeStoragePaths(gitDir).controlEnvPath).text();
+    expect(controlEnvText).toContain("WEBMUX_CONTROL_URL=http://127.0.0.1:5111/api/runtime/events");
+  });
+
+  it("leaves the session untouched when the profile is unchanged", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const lifecycle = makeLifecycleService(
+      repoRoot,
+      tmux,
+      runtime,
+      new FakeDockerGateway(),
+      new FakeHookRunner(),
+      SWITCHABLE_PROFILE_CONFIG,
+    );
+
+    await lifecycle.createWorktree({ branch: "feature-profile-same", profile: "default" });
+    tmux.commands.length = 0;
+    tmux.createdWindows.length = 0;
+
+    const result = await lifecycle.setWorktreeProfile("feature-profile-same", "default");
+
+    expect(result).toEqual({ profile: "default", restarted: false });
+    expect(tmux.createdWindows).toEqual([]);
+    expect(tmux.commands).toEqual([]);
+  });
+
+  it("rejects switching to an unknown profile", async () => {
+    const repoRoot = await initRepo();
+    const runtime = new ProjectRuntime();
+    const tmux = new FakeTmuxGateway();
+    const lifecycle = makeLifecycleService(repoRoot, tmux, runtime);
+
+    await lifecycle.createWorktree({ branch: "feature-profile-unknown" });
+
+    await expect(lifecycle.setWorktreeProfile("feature-profile-unknown", "nope"))
+      .rejects.toMatchObject({ status: 400, message: "Unknown profile: nope" });
+
+    const worktreePath = join(repoRoot, "__worktrees", "feature-profile-unknown");
+    const gitDir = new BunGitGateway().resolveWorktreeGitDir(worktreePath);
+    expect((await readWorktreeMeta(gitDir))?.profile).toBe("default");
+  });
+
   it("creates a managed docker worktree through the container runtime path", async () => {
     const repoRoot = await initRepo();
     const runtime = new ProjectRuntime();

backend/src/server.ts

@@ -20,6 +20,7 @@ import {
   SendWorktreePromptRequestSchema,
   SetWorktreeArchivedRequestSchema,
   SetWorktreeLabelRequestSchema,
+  SetWorktreeProfileRequestSchema,
   ToggleEnabledRequestSchema,
   UpsertCustomAgentRequestSchema,
   WorktreeNameParamsSchema,
@@ -1455,6 +1456,18 @@ async function apiSetWorktreeLabel(name: string, req: Request): Promise<Response
   return jsonResponse({ ok: true, label: result.label });
 }
 
+async function apiSetWorktreeProfile(name: string, req: Request): Promise<Response> {
+  ensureBranchNotBusy(name);
+  const parsed = await parseJsonBody(req, SetWorktreeProfileRequestSchema);
+  if (!parsed.ok) return parsed.response;
+  const body = parsed.data;
+
+  log.info(`[worktree:profile] name=${name} profile=${body.profile}`);
+  const result = await lifecycleService.setWorktreeProfile(name, body.profile);
+  log.debug(`[worktree:profile] done name=${name} profile=${result.profile} restarted=${result.restarted}`);
+  return jsonResponse({ ok: true, profile: result.profile, restarted: result.restarted });
+}
+
 async function apiSendPrompt(name: string, req: Request): Promise<Response> {
   ensureBranchNotBusy(name);
   const parsed = await parseJsonBody(req, SendWorktreePromptRequestSchema);
@@ -2066,6 +2079,15 @@ function parseAgentIdParam(params: Record<string, string>):
       },
     },
 
+    [apiPaths.setWorktreeProfile]: {
+      PUT: (req) => {
+        const parsed = parseWorktreeNameParam(req.params);
+        if (!parsed.ok) return parsed.response;
+        const name = parsed.data;
+        return catching(`PUT /api/worktrees/${name}/profile`, () => apiSetWorktreeProfile(name, req));
+      },
+    },
+
     [apiPaths.sendWorktreePrompt]: {
       POST: (req) => {
         const parsed = parseWorktreeNameParam(req.params);

backend/src/services/lifecycle-service.ts

@@ -44,7 +44,7 @@ import {
 } from "./agent-service";
 import { getAgentDefinition, type AgentDefinition } from "./agent-registry";
 import type { ReconciliationService } from "./reconciliation-service";
-import { ensureSessionLayout, planSessionLayout } from "./session-service";
+import { ensureSessionLayout, isWorktreeOpen, planSessionLayout } from "./session-service";
 import { ArchiveStateService } from "./archive-state-service";
 import {
   createManagedWorktree,
@@ -765,6 +765,48 @@ export class LifecycleService {
     }
   }
 
+  /** Switch a worktree to another profile. When the worktree is open its tmux
+   *  window is rebuilt from the new profile's pane templates (resuming the agent
+   *  conversation); when it is closed the new profile applies on the next open. */
+  async setWorktreeProfile(branch: string, profileName: string): Promise<{
+    profile: string;
+    restarted: boolean;
+  }> {
+    try {
+      const resolved = await this.resolveExistingWorktree(branch);
+      if (!resolved.meta) {
+        throw new LifecycleError(`Worktree ${branch} has no managed metadata to reprofile`, 409);
+      }
+      const { profileName: nextProfileName, profile } = this.resolveProfile(profileName);
+      const wasOpen = isWorktreeOpen(this.deps.tmux, this.deps.projectRoot, branch);
+      if (resolved.meta.profile === nextProfileName) {
+        return { profile: nextProfileName, restarted: false };
+      }
+
+      // Containers are keyed by branch and reused on launch, so a worktree leaving
+      // its docker profile — for host or for another image — needs a teardown first.
+      if (resolved.meta.runtime === "docker") {
+        await this.deps.docker.removeContainer(branch);
+      }
+
+      await writeWorktreeMeta(resolved.gitDir, {
+        ...resolved.meta,
+        profile: nextProfileName,
+        runtime: profile.runtime,
+      });
+
+      if (wasOpen) {
+        await this.openWorktree(branch);
+      } else {
+        await this.deps.reconciliation.reconcile(this.deps.projectRoot, { force: true });
+      }
+
+      return { profile: nextProfileName, restarted: wasOpen };
+    } catch (error) {
+      throw this.wrapOperationError(error);
+    }
+  }
+
   listAvailableBranches(options: ListAvailableBranchesOptions = {}): Array<{ name: string }> {
     const localBranches = this.listLocalBranches().filter((branch) => isValidBranchName(branch));
     const remoteBranches = options.includeRemote

bin/src/completions.ts

@@ -11,7 +11,7 @@ interface ListBranchesDeps {
 
 // ── Constants ──────────────────────────────────────────────────────────────
 
-const BRANCH_SUBCOMMANDS = new Set(["open", "close", "refresh", "archive", "unarchive", "label", "remove", "merge", "send"]);
+const BRANCH_SUBCOMMANDS = new Set(["open", "close", "refresh", "archive", "unarchive", "label", "profile", "remove", "merge", "send"]);
 
 // ── Pure logic ─────────────────────────────────────────────────────────────
 
@@ -130,6 +130,7 @@ _webmux() {
     'archive:Hide a worktree from the default list'
     'unarchive:Show an archived worktree again'
     'label:Set or clear a workspace label'
+    'profile:Switch a worktree to another profile'
     'remove:Remove a worktree'
     'merge:Merge a worktree into main'
     'send:Send a prompt to a running worktree agent'
@@ -146,7 +147,7 @@ _webmux() {
   fi
 
   case "\${words[2]}" in
-    open|close|refresh|archive|unarchive|label|remove|merge|send)
+    open|close|refresh|archive|unarchive|label|profile|remove|merge|send)
       if (( CURRENT == 3 )); then
         local -a branches
         branches=(\${(f)"$(webmux --completions "\${words[2]}" 2>/dev/null)"})
@@ -206,12 +207,12 @@ const BASH_SCRIPT = `_webmux() {
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
   if [[ \${COMP_CWORD} -eq 1 ]]; then
-    COMPREPLY=($(compgen -W "serve init service update add oneshot list open close refresh archive unarchive label remove merge send prune restore linear project completion" -- "\${cur}"))
+    COMPREPLY=($(compgen -W "serve init service update add oneshot list open close refresh archive unarchive label profile remove merge send prune restore linear project completion" -- "\${cur}"))
     return
   fi
 
   case "\${COMP_WORDS[1]}" in
-    open|close|refresh|archive|unarchive|label|remove|merge|send)
+    open|close|refresh|archive|unarchive|label|profile|remove|merge|send)
       if [[ \${COMP_CWORD} -eq 2 ]]; then
         local branches
         branches=$(webmux --completions "\${COMP_WORDS[1]}" 2>/dev/null)

bin/src/webmux.ts

@@ -29,6 +29,7 @@ Usage:
   webmux archive      Hide a worktree from the default list
   webmux unarchive    Show an archived worktree again
   webmux label        Set or clear a workspace label
+  webmux profile      Switch a worktree to another profile
   webmux remove       Remove a worktree
   webmux merge        Merge a worktree into the main branch and remove it
   webmux send         Send a prompt to a running worktree agent
@@ -52,7 +53,7 @@ Environment:
 `);
 }
 
-type RootCommand = "serve" | "init" | "service" | "update" | "add" | "oneshot" | "list" | "open" | "close" | "refresh" | "archive" | "unarchive" | "label" | "remove" | "merge" | "send" | "tab" | "prune" | "restore" | "linear" | "project" | "completion" | null;
+type RootCommand = "serve" | "init" | "service" | "update" | "add" | "oneshot" | "list" | "open" | "close" | "refresh" | "archive" | "unarchive" | "label" | "profile" | "remove" | "merge" | "send" | "tab" | "prune" | "restore" | "linear" | "project" | "completion" | null;
 
 interface ParsedRootArgs {
   port: number;
@@ -80,6 +81,7 @@ function isRootCommand(value: string): value is NonNullable<RootCommand> {
     || value === "archive"
     || value === "unarchive"
     || value === "label"
+    || value === "profile"
     || value === "remove"
     || value === "merge"
     || value === "send"
@@ -165,7 +167,7 @@ export function parseRootArgs(args: string[]): ParsedRootArgs {
   };
 }
 
-function isWorktreeCommand(command: RootCommand): command is "add" | "list" | "open" | "close" | "refresh" | "archive" | "unarchive" | "label" | "remove" | "merge" | "send" | "tab" | "prune" | "restore" {
+function isWorktreeCommand(command: RootCommand): command is "add" | "list" | "open" | "close" | "refresh" | "archive" | "unarchive" | "label" | "profile" | "remove" | "merge" | "send" | "tab" | "prune" | "restore" {
   return command === "add"
     || command === "list"
     || command === "open"
@@ -174,6 +176,7 @@ function isWorktreeCommand(command: RootCommand): command is "add" | "list" | "o
     || command === "archive"
     || command === "unarchive"
     || command === "label"
+    || command === "profile"
     || command === "remove"
     || command === "merge"
     || command === "send"