Install the CLI — once
Single global command. Requires bash 4.0+, git, jq, and Docker.
Coming soon — for humans and AI
agents
Fully isolated parallel dev environments. Zero conflicts.
Every workstream gets its own worktree, services, ports, and config — completely isolated from every other. Work on multiple versions of your app at the same time without port conflicts, file collisions, or agents stomping on each other. Built on git worktrees and Docker — no magic, no lock-in.
Total isolation.
Every workstream gets its own ports, services, files, and
config. Nothing shared, nothing collides.
Humans and agents, side by side.
Run 5 workstreams in parallel — whether a developer or an
AI agent is driving each one.
Git worktrees + Docker. That's it.
You define your environment. StackMux makes sure every
workstream gets an identical, isolated copy. Zero footprint in
your repo by default.
The problem is not git. The problem is everything around it.
Git worktrees let you check out multiple branches at once — but that's just files. Each branch still needs its own ports, its own database, its own Docker services, and its own config. Without true runtime isolation, "parallel development" means port conflicts, file collisions, and workstreams — human or AI — silently breaking each other. StackMux gives every workstream a fully isolated environment so nothing collides, ever.
How it works
Two one-time steps, then every workstream is the same simple loop.
Initialize your project — once per repo
Run stackmux init in any git checkout. Configures
your services, ports, and templates — stored outside the
repo with zero git footprint. Use it on any project without
leaving artifacts in the codebase, or commit shared config to
enforce it consistently across your team.
Start a workstream
Run stackmux start feat/auth. StackMux creates a
fully isolated environment — its own worktree, containers,
ports, and config — completely walled off from every other
workstream.
Develop and test
Work on your branch. Run tests against your isolated ports. Multiple branches stay live at once — humans and agents working side by side, with nothing colliding.
Finish up
Run stackmux finish feat/auth to stop services,
remove the worktree, and free resources. Or stop to pause the
workstream and resume it later.
Repeat
Every new feature, bugfix, or agent task follows the same loop: start, develop, finish. No re-setup, no surprises.
Every workstream is fully isolated. No exceptions.
Each workstream — whether driven by a developer or an agentic AI workflow — gets its own worktree, its own containers, its own ports, and its own config. No port conflicts. No file collisions. No "it works if you only run one at a time." Agents get generated context files so they know exactly what they own, what not to touch, and how to coordinate with other agents working in parallel.
Generated workstream context
Every workstream gets a human-readable context file with its ports, paths, rules, and operational commands — agents know how to verify the stack, rebuild services, and access GitHub with scoped credentials. You can scan it at a glance; AI agents read it automatically. StackMux auto-detects your AI tools and teaches them how to work with it. Customize what agents see per-project with template overrides.
# Workstream: feat-auth (api)
Branch: feat/auth
Worktree: ~/projects/api-feat-auth
Frontend: http://localhost:3001
API: http://localhost:5001
Slot: 1
## Rules
1. This worktree is your entire world
2. Test against YOUR ports, not defaults
3. Do not modify the base repo
4. Do not merge
## Project notes ← your custom content
- Auth uses OAuth2 via /api/auth
- Run migrations before testing
- See ARCHITECTURE.md for service mapWhy isolation has to be explicit
Without it, every parallel workstream — human or AI — assumes it owns the same ports, the same directories, and the same services. Two workstreams collide. Three is chaos. StackMux makes isolation the default, not something you wire up yourself.
Without StackMux
- Port collisions crash each other's servers
- Agents and humans overwrite each other's files
- Shared services break when branches diverge
- Every additional workstream makes it worse
With StackMux
- Each workstream is fully isolated — own worktree, containers, and ports
- Deterministic port assignment — collisions are impossible
- Generated context tells each workstream (and agent) exactly what it owns
- Run, test, and develop multiple versions of your app at once — zero conflicts
Three operating modes
Not every task needs full autonomy. StackMux lets you configure how much control agents get: full mode for end-to-end implementation and PR creation, read-only for analysis and planning without file modifications, or coordinator to orchestrate multiple agents — creating workstreams, monitoring progress, and delegating implementation without writing code itself.
Agents coordinate, not just isolate
Each workstream includes a structured status file that agents maintain as they work — current phase, progress, blockers, and key decisions. Coordinator agents and sibling workstreams read each other's status to understand progress and avoid duplicating work. Isolation prevents collisions; status tracking enables collaboration.
Already using Claude Code, Cursor, Windsurf, or GitHub Copilot?
Those tools are great at writing code — but when you run two
or more of them in parallel, they all assume they own the same
ports, the same services, and the same directories. StackMux is
the layer underneath that gives each agent (or human) its own
isolated environment to build, run, and test against. Your AI
coding tool writes the code. StackMux makes sure there's a clean,
isolated place to run it. Run stackmux init and it
auto-detects your existing tools and teaches agents how to work
with it — zero wiring required.
Built on git worktrees and Docker. Nothing weird.
Git worktrees for isolated checkouts.
Docker for containerized services.
StackMux drives both.
You define your environment — services, ports, config — and StackMux makes sure every workstream gets its own isolated copy. It creates the worktrees, manages the containers, assigns deterministic ports, and generates the config. Run services from any worktree with automatic port isolation. No proprietary runtime. No reinventing the wheel.
Deterministic ports
Base app on :3000, slot 1 on :3001, slot
2 on :3002. The same offset pattern applies across
every configured service: API, database, cache, everything.
Flexible service binding
Each service can be included (own container), base (share the base repo's instance), remote (point to an external endpoint), or skipped entirely. Run the full stack for one workstream and just the API hitting a remote database for another.
Monorepo stacks
Named stacks let you define slices of your platform. Run
--stack notes for one workstream,
--stack tasks for another,
--stack full for integration testing.
Local or shared — your call
In local mode, StackMux leaves zero footprint in the repo — nothing committed, nothing to gitignore. Or commit the config and give your whole team the same ports, the same services, and the same workflow. No setup guides, no "works on my machine", no per-developer decisions about how to run the stack. Sometimes eliminating the micro-decisions is the point.
Coming soon
StackMux is under active development and will be open-sourced soon. It will work on macOS, Linux, and Windows (via WSL) with a single command install.
Once released, the workflow will be:
stackmux init |
Configure your project (once per repo, zero git footprint) |
stackmux start <branch> |
Create an isolated workstream |
stackmux status |
See what's running |
stackmux stop <branch> |
Pause and resume later |
stackmux finish <branch> |
Tear it down and free resources |
How StackMux compares
StackMux fills the gap between tools you already use.
Free and open source.
StackMux will be Apache 2.0-licensed, free to use, with no telemetry or cloud dependencies.