worktree-devservers

Run multiple dev servers in git worktrees with automatic port allocation and reverse proxy routing. Each worktree gets its own <slug>.localhost URL on port 80.

Built for coding agents (Conductor, Claude Code, Cursor) that work in isolated worktrees, so multiple branches can run simultaneously without port conflicts.

How it works

1. Finds free ports (checks both IPv4 and IPv6)
2. Calls your start callback — you spawn whatever dev server you need
3. Registers a Caddy reverse proxy route: <slug>.localhost:80 → localhost:<port>
4. Cleans up routes and stale entries on exit

Prerequisites

brew install caddy
caddy start

Install

bun add worktree-devservers

Usage

CLI

The quickest way — no code needed:

dev-worktree --slug myapp -- bun run dev

The allocated port is set as the PORT env var. You can also reference it explicitly with $PORT:

dev-worktree --slug myapp --port 4000 -- vite --port \$PORT

| Flag | Default | Description | |------|---------|-------------| | --slug | (required) | Subdomain name | | --port | 3000 | Starting port to search from |

Programmatic API

For more control, import and call startWorktree directly:

import { startWorktree } from "worktree-devservers";

const slug = process.env.WORKTREE_SLUG;
if (!slug) {
  console.error("WORKTREE_SLUG is required");
  process.exit(1);
}

startWorktree(slug, async (ctx) => {
  const port = await ctx.findFreePort(3000);

  const child = Bun.spawn(["bun", "run", "dev"], {
    env: { ...process.env, PORT: String(port) },
    stdio: ["inherit", "inherit", "inherit"],
  });

  return { port, process: child };
});

Either way, access your dev server at http://<slug>.localhost.

API

startWorktree(slug, startFn, options?)

| Parameter | Type | Description | |-----------|------|-------------| | slug | string | Worktree identifier, used as the subdomain (<slug>.localhost) | | startFn | (ctx: WorktreeContext) => Promise<WorktreeHandle> | Callback to start your dev server | | options | WorktreeOptions | Optional configuration |

WorktreeContext

| Property | Type | Description | |----------|------|-------------| | slug | string | The worktree slug | | findFreePort(start) | (start: number) => Promise<number> | Find next free port from start. Tracks allocations internally. |

WorktreeHandle

| Property | Type | Description | |----------|------|-------------| | port | number | Port Caddy should route to | | process | Subprocess | Child process for lifecycle management |

WorktreeOptions

| Option | Default | Description | |--------|---------|-------------| | caddyAdmin | http://localhost:2019 | Caddy admin API URL | | serverId | worktree-devservers | Caddy server block ID | | listenPort | 80 | Port Caddy listens on |

License

MIT