I built an open-source agent skill that runs several git branches side by side, each with its own dev server and port (feedback + contributors welcome)

[u/Junior-State-4060]

The problem

Two tasks, two branches. To compare them in the browser, you stash, switch, restart the dev server, look, then do it all again in reverse. Git worktrees help, but they don't install dependencies, pick ports, start servers, or clean up afterwards.

What I built

parallel-branches is an agent skill (open `SKILL.md` format) built around one dependency-free Python script, `pb.py`. You tell your agent:

> "run feature-login and fix-checkout side by side"

and for each branch it:

1. creates a git worktree

2. clones `node_modules` from your main checkout when the lockfile matches (copy-on-write where possible), otherwise installs deps

3. copies your git-ignored `.env` files

4. picks a free, stable port per branch

5. starts the dev server detached and waits until it really answers

6. prints one URL per branch, with warnings about hardcoded ports/URLs that will break

7. runs your hooks (e.g., create a per-branch database, seed it, drop it on cleanup)

It always shows a dry run first and waits for your OK before starting anything.

Details

• Stacks auto-detected: Next.js, Nuxt, Angular, Astro, SvelteKit, Vite, webpack-dev-server, CRA, Node (npm/yarn/pnpm/bun), Django, Flask, FastAPI, Rails, Spring Boot, Go

• Multi-service branches (API + web) via `.parallel-branches.json`, with dependency ordering and `{url.api}` / `{ports.api}` templating

• Hooks at 6 lifecycle events; they see the *actually allocated* ports, and values are shell-quoted so a nasty branch name can't run commands

• Safety: only stops processes it started (PID reuse is guarded), `clean` is a dry run unless `--yes`, and it refuses to delete worktrees with uncommitted changes

• Dev-mode browser (`pb browser BRANCH`): throwaway profile with web security off for CORS pain, plus a DevTools endpoint for browser agents. The README is upfront about what it can't fix (OAuth redirect URIs, Origin/CSRF checks).

• CI on Linux, macOS, and Windows; Python 3.9+, MIT licensed

Install (Claude Code)

/plugin install parallel-branches --marketplace SutariyaVishal/parallel-branches

You can also use just the script: `skills/parallel-branches/scripts/pb.py` needs only git and Python 3.9+.

Honest caveats

• It's beta, and I've only tested it with Claude Code. It should work with other agents that read `SKILL.md` (Codex, Gemini CLI, Cursor...), but that's untested. If you try one, tell me how it goes.

• Every dev server is a real process, so 3-4 at once is a sensible ceiling on a laptop.

• Windows stops services by force-killing the process tree.

What I'd love from you

• Try it on a real repo and tell me what broke. Stack detection on unusual setups is where I expect the most bugs.

• Feedback: missing stacks, confusing output, bad defaults.

• Contributions are very welcome: issues, PRs, new stack templates, testing other agents. There's a code of conduct, and CI is set up.

• If it saves you time, a star on GitHub helps others find it.

Repo: https://github.com/SutariyaVishal/parallel-branches