Manage git worktrees across a poly-repo environment
npm install worktree-flow> Multi-repo feature development with git worktrees




Stop juggling branches across repos. flow creates isolated workspaces with git worktrees from multiple repositories, all on the same branch, with a single command.
```
~/repos/ ~/workspaces/TICKET-123/
├── api-1/ (main) ├── api-1/ (TICKET-123 branch)
├── api-2/ (main) flow ├── client/ (TICKET-123 branch)
├── client/ (main) --------> └── AGENTS.md (copied from ~/repos)
└── AGENTS.md
`bash
npm install -g worktree-flow
Why worktree-flow?
Working on features that span multiple repositories means manually creating branches, switching between repos, and keeping everything in sync. Git worktrees solve part of this, but managing them across a poly-repo is still tedious.
flow automates the entire workflow:- One command to create branches across repos with interactive selection
- Workspace isolation so each feature gets its own directory with worktrees
- Workspace-level operations to push, pull, and check status across all repos at once
- Safe cleanup that checks for uncommitted changes and unpushed commits before removing
- Post-checkout hooks to run setup commands (like
npm ci) in parallel after branchingCommands
$3
Create a new branch across selected repos. Interactively select which repos to include, then creates branches and worktrees in a new workspace directory.
$3
Checkout an existing branch. Fetches all repos, detects which have the branch, and creates worktrees.
$3
Pull latest changes for all repos in the current workspace. Run from anywhere inside a workspace.
$3
Push all repos in the current workspace. Automatically sets upstream on first push.
$3
Check the status of all repos in a workspace. Shows uncommitted changes, commits ahead of main, and up-to-date repos.
$3
List all workspaces with status indicators. Shows:
- Active workspace (marked with
*) based on current directory
- Overall status: clean, uncommitted, ahead, behind, diverged, or mixed
- Repo count for each workspaceFetches all repos before checking status to ensure accurate information.
$3
Remove a workspace and all its worktrees. Fetches latest, checks for uncommitted changes and unpushed commits, and prompts for confirmation before removing.
$3
Remove stale workspaces in bulk. Finds workspaces where all worktrees are clean, fully merged, and haven't been committed to in over 7 days.
$3
Create tmux sessions for all workspaces that don't already have one. Each session is created with split panes (one for the workspace root and one for each worktree) using a tiled layout. Skips workspaces that already have active sessions.
Requires
tmux to be installed and the tmux config option to be enabled.$3
Configure flow settings. See Configuration below.
Configuration
Settings are stored in
~/.config/flow/config.json.| Key | Description | Default |
|-----|-------------|---------|
|
source-path | Directory containing your source repos | required |
| dest-path | Directory where workspaces are created | required |
| main-branch | Main branch name | master |
| tmux | Create tmux sessions with split panes (root + each worktree) | false |
| copy-files | Files to copy from source repos to worktrees | .env |
| post-checkout | Command to run after checkout (e.g. npm ci) | none |
| per-repo-post-checkout | Per-repo commands (see below) | {} |$3
Configure different commands for specific repos by editing
~/.config/flow/config.json:`json
{
"post-checkout": "npm ci",
"per-repo-post-checkout": {
"api-service": "npm ci && npm run build",
"frontend": "yarn install"
}
}
`Repos with per-repo commands use those; others fall back to the global
post-checkout command.AGENTS.md
If an
AGENTS.md` file exists at the root of your source-path, it will be copied into each workspace. This is useful for providing AI coding agents with context about your multi-repo setup.MIT