sync-worktrees 3.6.2 → 4.0.0

package/README.md

@@ -1,34 +1,75 @@
 # sync-worktrees
 
-Automatically synchronize Git worktrees with remote branches. Keep your local worktrees in sync with remote repositories - perfect for multi-branch development workflows and automated testing setups.
+> Keep every branch and every repo you work on checked out as predictable directories — no stashing, no re-cloning, no re-orienting your AI assistant.
 
 ![sync-worktrees demo](./assets/sync-worktrees-demo-optimized.gif)
 
+**Contents:** [Why](#why-sync-worktrees) · [How it works](#how-it-works) · [Quick start](#quick-start) · [MCP server](#mcp-server) · [Interactive TUI](#interactive-tui) · [CLI options](#cli-options)
+
+## Why sync-worktrees
+
+If you've ever:
+
+- Stashed half-finished work just to check out another branch
+- Lost minutes hunting for where you cloned a sibling repo
+- Switched branches in five repos because one feature spans them all
+- Re-explained to an AI assistant which directory holds which branch
+
+…sync-worktrees fixes that. It keeps the **entire branch and repo layout you work in materialized on disk** — one directory per branch, automatically kept in sync with the remote. Switching branches becomes `cd`. Searching across repos becomes `grep -r`. **AI agents see the same shape you do, so "look in the other repo" actually works.**
+
+It's also a clean answer to **dev-environment bootstrapping**. One config file describes every repo, branch, and folder layout your team works in. Hand it to a new hire (or a fresh laptop) and `sync-worktrees` lays down the whole workspace in a single command — no day-one cloning checklist, no "where do I put this repo?" Slack threads.
+
+Runs as a one-shot, a background daemon, or an interactive TUI — and ships an MCP server so AI assistants can list, create, and inspect worktrees themselves.
+
 ## How it works
 
-sync-worktrees maintains a **separate working directory for each remote branch**, all sharing the same Git repository:
+The default — **worktree mode** — gives every remote branch its own directory while sharing one Git database underneath:
+
+1. **First run** clones the repo once as a bare repository (just the Git data, no working files).
+2. **Each sync**:
+   - Creates a directory for every remote branch (`main`, `develop`, `feature/*`).
+   - Fetches latest changes (no merge — your local work stays untouched).
+   - Removes directories for branches deleted upstream (preserves dirty trees and unpushed commits).
+
+Smallest config that produces this:
+
+```javascript
+// sync-worktrees.config.js
+// @ts-check
+
+/** @satisfies {import("sync-worktrees").SyncWorktreesConfig} */
+const config = {
+  repositories: [
+    {
+      name: "my-repo",
+      repoUrl: "https://github.com/user/my-repo.git",
+      worktreeDir: "./worktrees/my-repo",
+    },
+  ],
+};
+
+export default config;
+```
 
-1. **First run**: Clones your repository as a bare repository (no working files, just Git data)
-2. **Automatic sync**: 
-   - Creates a dedicated worktree for **every remote branch** (`main`, `develop`, `feature/*`, etc.)
-   - Each branch gets its own isolated directory with a full working copy
-   - Fetches latest changes (doesn't merge - preserves your local work)
-   - Removes worktrees when remote branches are deleted (preserves local changes)
+Run `sync-worktrees` from the directory holding the config and you get:
 
-**Why this matters**: Switch between branches instantly without stashing, run tests on multiple branches simultaneously, or keep your CI and production branches always ready.
+```
+.
+├── sync-worktrees.config.js
+├── .bare/
+│   └── my-repo/             # Bare repository (shared Git objects)
+└── worktrees/my-repo/
+    ├── main/                # Worktree for main branch
+    ├── feature-1/           # Worktree for feature-1 branch
+    └── feature-2/           # Worktree for feature-2 branch
+```
+
+**Clone mode** (`mode: "clone"`) is a first-class alternative: a plain `git clone` of one branch into `worktreeDir`, no bare repo, no per-branch subfolders. Reach for it when you want a repo to live at a fixed path — a dependency sibling, a single-branch dev clone, or any case where one checkout is enough. See [Clone mode](#clone-mode).
 
 ## Features
 
-- 🔄 Automatically creates worktrees for all remote branches
-- 🗑️ Removes worktrees for deleted remote branches (preserves local changes)
-- ⏰ Run as a scheduled cron job or one-time execution
-- 🛡️ Safe operations - won't delete worktrees with uncommitted changes or unpushed commits
-- 📝 Clear logging with timestamps and progress indicators
-- 📋 Config file support for managing multiple repositories
-- 🔁 Automatic retry with exponential backoff for network and filesystem errors
-- 🕐 Branch age filtering - only sync branches active within a specified time period
-- 🔀 Smart handling of rebased/force-pushed branches with automatic divergence detection
-- 🤖 MCP server for AI assistants - inspect and manage worktrees from Claude Desktop, Claude Code, Cursor, etc.
+- **Filtering & lifecycle** — branch name globs, age filtering, sparse checkout, automatic divergence detection with `.diverged/` preservation, retry with exponential backoff.
+- **Interactive TUI** — Ink-based UI with wizards for opening worktrees, creating branches, and inspecting status; diverged-directory management; live log streaming; multi-repo filtering.
 
 ## Installation
 
@@ -36,99 +77,191 @@ sync-worktrees maintains a **separate working directory for each remote branch**
 npm install -g sync-worktrees
 ```
 
-Or with pnpm:
+## Quick start
+
+`sync-worktrees` always runs against a config file. Create one once, then run the tool.
 
 ```bash
-pnpm add -g sync-worktrees
+cd ~/projects/my-sync-dir
+sync-worktrees init      # interactive wizard → writes sync-worktrees.config.js
+sync-worktrees           # auto-loads the config in the current directory and starts syncing
 ```
 
-## Usage
+By default, bare `sync-worktrees` launches the [interactive TUI](#interactive-tui) and keeps syncing on the cron schedule from your config. Press `q` to quit. For a one-shot run (CI, scripts, ad-hoc), add `--runOnce`.
 
-Run `sync-worktrees` in any directory:
+To manage multiple repositories, edit the generated config file and add entries under `repositories`. See [Configuration](#configuration).
 
-- **First run** — no config found → interactive wizard asks for repo URL, worktree directory, and schedule, then saves `sync-worktrees.config.js` in the current directory and starts syncing.
-- **Subsequent runs** — `sync-worktrees` auto-loads `sync-worktrees.config.js` (or `.mjs` / `.cjs`) from the current directory. No flags needed.
+If the config lives outside the current directory, pass it explicitly:
 
 ```bash
-cd ~/projects/my-sync-dir
-sync-worktrees           # wizard → saves config → runs
-sync-worktrees           # re-uses the saved config
+sync-worktrees --config /path/to/sync-worktrees.config.js
+sync-worktrees --config /path/to/sync-worktrees.config.js --runOnce
+sync-worktrees list --config ./config.js --filter "frontend-*"
 ```
 
-To manage multiple repositories, edit the generated config file and add entries under `repositories`. See [Configuration File](#configuration-file).
+## MCP server
 
-### Explicit config path
+sync-worktrees ships a [Model Context Protocol](https://modelcontextprotocol.io) server so AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) can inspect and operate your workspace directly. Installing the package exposes a second binary, `sync-worktrees-mcp`, that speaks MCP over stdio.
 
-Useful when the config lives outside the current directory:
+In a single call, an AI assistant can discover every repo and worktree you have configured — so an agent working in `frontend/` can grep across `backend/` and `shared/` without you reorienting it. That call is `detect_context` with `includeAllWorktrees: true`; the response also includes a per-capability `{ available, reason }` block telling the agent which operations are reachable from its current vantage point, so there's no guessing whether `sync` will work. See [Available tools](#available-tools) for the full surface.
+
+### Getting started
+
+Install the sync-worktrees MCP server with your client.
+
+**Standard config** works in most tools:
+
+```json
+{
+  "mcpServers": {
+    "sync-worktrees": {
+      "command": "npx",
+      "args": ["-y", "-p", "sync-worktrees", "sync-worktrees-mcp"],
+      "env": {
+        "SYNC_WORKTREES_CONFIG": "/absolute/path/to/sync-worktrees.config.js"
+      }
+    }
+  }
+}
+```
+
+If installed globally, replace `command` with `sync-worktrees-mcp` and drop `args`. `SYNC_WORKTREES_CONFIG` is optional — without it the server runs in **auto-detect mode**: when the client's CWD sits inside a worktree managed by sync-worktrees, the server locates the bare repo, enumerates sibling worktrees, and enables per-worktree operations. `sync` and `initialize` require a loaded config (or call `load_config` at runtime).
+
+<details>
+<summary>Claude Code</summary>
+
+Use the Claude Code CLI:
 
 ```bash
-sync-worktrees --config /path/to/sync-worktrees.config.js
-sync-worktrees --config ./config.js --filter "frontend-*"
-sync-worktrees --config ./config.js --list
+claude mcp add sync-worktrees -- npx -y -p sync-worktrees sync-worktrees-mcp
 ```
 
-### Opening a worktree from the TUI
+To pass a config path, append `-e SYNC_WORKTREES_CONFIG=/absolute/path/to/sync-worktrees.config.js` to the command.
 
-Press `o` in the interactive TUI to open the selected worktree. The wizard supports two modes, toggled with `Tab`:
+</details>
 
-- **Terminal** (default) — launches a new terminal window with a `tmux` session attached to the worktree directory. Session name is `<repo>-<sanitized-branch>`; re-opening the same worktree attaches to the existing session instead of creating a duplicate.
-- **Editor** — launches `$EDITOR` / `$VISUAL` (falls back to `code`) in the worktree.
+<details>
+<summary>Claude Desktop</summary>
 
-Terminal mode requires [`tmux`](https://github.com/tmux/tmux) to be installed.
+Edit `claude_desktop_config.json` and paste the **standard config** above into the `mcpServers` block. Default locations:
 
-#### Environment variables
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-| Variable | Purpose | Default behavior |
-|----------|---------|------------------|
-| `SYNC_WORKTREES_TERMINAL` | Override the terminal launcher on any platform. Value is a command string; the tmux invocation is appended via `sh -c`. Example: `SYNC_WORKTREES_TERMINAL="alacritty -e"`. | See per-platform defaults below. |
-| `TERMINAL` | Linux-only fallback when `SYNC_WORKTREES_TERMINAL` is unset. Same format. | Probes `gnome-terminal`, `konsole`, `alacritty`, `kitty`, `xterm` in order. |
-| `EDITOR` / `VISUAL` | Editor mode launcher. | Falls back to `code`. |
+Restart Claude Desktop after editing.
 
-Per-platform terminal defaults (when no env override is set):
+</details>
 
-- **macOS** — Ghostty if `Ghostty.app` is installed, otherwise Terminal.app via AppleScript.
-- **Linux** — `$TERMINAL` if set; otherwise the first found among the candidates above.
+<details>
+<summary>Cursor</summary>
+
+Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project). Paste the **standard config** above.
+
+Or open `Cursor Settings` → `MCP` → `Add new MCP Server`, pick `command` type, and enter `npx -y -p sync-worktrees sync-worktrees-mcp`.
+
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Follow the Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp) and use the **standard config** above.
+
+</details>
+
+<details>
+<summary>VS Code</summary>
+
+Use the VS Code CLI:
+
+```bash
+code --add-mcp '{"name":"sync-worktrees","command":"npx","args":["-y","-p","sync-worktrees","sync-worktrees-mcp"]}'
+```
+
+Or follow the VS Code MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) and use the **standard config** above.
+
+</details>
+
+<details>
+<summary>Codex</summary>
+
+Use the Codex CLI:
+
+```bash
+codex mcp add sync-worktrees -- npx -y -p sync-worktrees sync-worktrees-mcp
+```
+
+Or edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.sync-worktrees]
+command = "npx"
+args = ["-y", "-p", "sync-worktrees", "sync-worktrees-mcp"]
+```
+
+</details>
 
-## MCP Server
+<details>
+<summary>Gemini CLI</summary>
 
-sync-worktrees ships a [Model Context Protocol](https://modelcontextprotocol.io) server so AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf, etc.) can inspect and manage your worktrees directly. Installing the package exposes a second binary, `sync-worktrees-mcp`, that speaks MCP over stdio.
+Follow the Gemini CLI MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson) and use the **standard config** above.
 
-### Setup
+</details>
 
-Add the server to your MCP client config. Use `npx` if the package is not installed globally:
+<details>
+<summary>Cline</summary>
+
+Edit `cline_mcp_settings.json` (see [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers)) and add:
 
 ```json
 {
   "mcpServers": {
     "sync-worktrees": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "-p", "sync-worktrees", "sync-worktrees-mcp"],
-      "env": {
-        "SYNC_WORKTREES_CONFIG": "/absolute/path/to/sync-worktrees.config.js"
-      }
+      "disabled": false
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>opencode</summary>
+
+Edit `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "sync-worktrees": {
+      "type": "local",
+      "command": ["npx", "-y", "-p", "sync-worktrees", "sync-worktrees-mcp"],
+      "enabled": true
     }
   }
 }
 ```
 
-If installed globally, replace `command` with `sync-worktrees-mcp` and drop `args`. `SYNC_WORKTREES_CONFIG` is optional — without it the server runs in **auto-detect mode**: when the client's CWD sits inside a worktree managed by sync-worktrees, the server locates the bare repo, enumerates sibling worktrees, and enables per-worktree operations. Sync and initialize require a loaded config (or call `load_config` at runtime).
+</details>
 
-Client-specific locations:
+<details>
+<summary>Warp</summary>
 
-| Client | Config file |
-|--------|-------------|
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
-| Claude Code | `claude mcp add sync-worktrees -- npx -y -p sync-worktrees sync-worktrees-mcp` |
-| Cursor | `~/.cursor/mcp.json` (or project-level `.cursor/mcp.json`) |
+Open `Settings` → `AI` → `Manage MCP Servers` → `+ Add` (see [Warp MCP docs](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server)) and paste the **standard config** above. Alternatively, run `/add-mcp` in the prompt.
+
+</details>
 
 ### Available tools
 
 | Tool | Purpose |
 |------|---------|
-| `detect_context` | Inspect a path, resolve the bare repo, enumerate sibling worktrees, report capabilities. |
-| `list_worktrees` | List worktrees with status label (`clean`/`dirty`/`stale`/`current`), divergence, `safeToRemove`, last sync. |
+| `detect_context` | Inspect a path, resolve the bare repo, enumerate sibling worktrees, report config-driven sibling repositories and capabilities. Pass `includeAllWorktrees: true` to include every configured repo's worktrees keyed by repo name. |
+| `list_worktrees` | List worktrees with status label (`clean`/`dirty`/`stale`/`current`), divergence, `safeToRemove`, last sync. Without `repoName` and with a loaded config, results are grouped across all configured repos. |
 | `get_worktree_status` | Detailed status for one worktree (dirty files, unpushed commits, stashes, operation in progress). |
-| `create_worktree` | Create a worktree for a branch; optionally create the branch from `baseBranch` and push. |
+| `create_worktree` | Create a worktree for a branch; optionally create the branch from `baseBranch`. Newly created branches are pushed to origin unless `push=false`. |
 | `remove_worktree` | Remove a worktree after safety checks; `force=true` skips validation. |
 | `update_worktree` | Fast-forward one worktree to match upstream. |
 | `sync` | Full sync cycle (fetch, create, prune, update). Requires config. Streams progress notifications. |
@@ -142,288 +275,280 @@ All tools that target a single repo accept an optional `repoName`. When omitted,
 
 - `remove_worktree` refuses to delete worktrees with uncommitted changes, unpushed commits, stashes, or operations in progress (merge/rebase/cherry-pick/revert/bisect). Pass `force=true` to override.
 - `create_worktree` rejects sanitized-path collisions (e.g. `feature/foo` vs `feature-foo` both resolving to `feature-foo/`) before touching disk.
+- Branches created by sync-worktrees use `--no-track` first, then publish with `git push -u origin <branch>`, so they do not inherit `origin/main` as their upstream.
 - Path-targeted tools verify the supplied path is a registered worktree of the selected repository.
 
-## Options
+## Interactive TUI
 
-| Option | Alias | Description | Default |
-|--------|-------|-------------|---------|
-| `--config` | `-c` | Path to JavaScript config file (auto-detected in CWD when omitted) | - |
-| `--filter` | `-f` | Filter repositories by name (wildcards supported) | - |
-| `--list` | `-l` | List configured repositories and exit | `false` |
-| `--runOnce` | - | Override config to run once and exit | `false` |
-| `--no-update-existing` | - | Disable automatic updates of existing worktrees | `false` |
-| `--debug` | `-d` | Show detailed reasons for skipped cleanups | `false` |
-| `--help` | `-h` | Show help | - |
+Running `sync-worktrees` without `runOnce` drops you into an interactive terminal UI with live log streaming, manual sync triggers, and wizards for the common operations.
 
-Most sync behavior (repo URL, worktree directory, cron schedule, branch filtering, LFS, retry) is configured in the config file. The CLI flags that only make sense for one-off runs (`--repoUrl`, `--worktreeDir`, `--cronSchedule`, `--branchMaxAge`, `--branchInclude`, `--branchExclude`, `--skip-lfs`, `--bareRepoDir`) are still supported — run `sync-worktrees --help` for the full list.
+### Keybindings
 
-## Configuration File
+| Key | Action |
+|-----|--------|
+| `s` | Manually trigger sync for all repositories |
+| `c` | Create a new branch (wizard) |
+| `o` | Open a worktree in terminal or editor (wizard) |
+| `w` | View worktree status across repos |
+| `r` | Reload configuration and re-sync |
+| `?` / `h` | Toggle help screen |
+| `q` / `Esc` | Gracefully quit |
+| `j` / `↓` | Scroll log down one line |
+| `k` / `↑` | Scroll log up one line |
+| `gg` | Jump to top of log |
+| `G` | Jump to bottom (re-enables auto-scroll) |
 
-For managing multiple repositories, create a JavaScript ES module config file:
+### Wizards
+
+- **Open wizard (`o`)** — select a worktree across all configured repos with live filtering (just type to narrow the list). Press `Tab` to flip between **Terminal** mode (launches a new terminal window attached to a `tmux` session in the worktree) and **Editor** mode (launches `$EDITOR` / `$VISUAL`, falling back to `code`). Re-opening the same worktree attaches to the existing tmux session instead of creating a duplicate.
+- **Branch creation wizard (`c`)** — pick a repo, pick a base branch from a live-filtered list, type the new branch name. Names are validated against Git's rules; if the desired name already exists, a numeric suffix (`-2`, `-3`, …) is suggested automatically.
+- **Worktree status view (`w`)** — flat list of every worktree across every configured repo, each tagged with status flags:
+
+  | Flag | Meaning |
+  |------|---------|
+  | `✓` | Clean |
+  | `M` | Modified / uncommitted changes |
+  | `↑` | Unpushed commits |
+  | `S` | Stashed changes |
+  | `⚠` | Operation in progress (merge/rebase/cherry-pick/revert/bisect) |
+  | `⊞` | Modified submodules |
+  | `✗` | Upstream branch is gone |
+
+  Press `Enter` on an entry to expand file/commit/stash counts. The view also surfaces `.diverged/` directories preserved from past force-pushes; press `d` (with `y`/`n` confirmation) to delete one after reviewing.
+
+### Terminal mode environment variables
+
+| Variable | Purpose | Default behavior |
+|----------|---------|------------------|
+| `SYNC_WORKTREES_TERMINAL` | Override the terminal launcher on any platform. Value is a command string; the tmux invocation is appended via `sh -c`. Example: `SYNC_WORKTREES_TERMINAL="alacritty -e"`. | See per-platform defaults below. |
+| `TERMINAL` | Linux-only fallback when `SYNC_WORKTREES_TERMINAL` is unset. Same format. | Probes `gnome-terminal`, `konsole`, `alacritty`, `kitty`, `xterm` in order. |
+| `EDITOR` / `VISUAL` | Editor mode launcher. | Falls back to `code`. |
+
+Per-platform terminal defaults (when no env override is set):
+
+- **macOS** — Ghostty if `Ghostty.app` is installed, otherwise Terminal.app via AppleScript.
+- **Linux** — `$TERMINAL` if set; otherwise the first found among the candidates above.
+
+Terminal mode requires [`tmux`](https://github.com/tmux/tmux) to be installed.
+
+## Configuration
+
+Config files are JavaScript ES modules. Relative paths resolve from the config file's location, and you have full access to `process.env` and Node module loading.
+
+### Minimal config
 
 ```javascript
-export default {
-  // Optional defaults for all repositories
+// @ts-check
+
+/** @satisfies {import("sync-worktrees").SyncWorktreesConfig} */
+const config = {
+  repositories: [
+    {
+      name: "my-project",
+      repoUrl: "https://github.com/user/my-project.git",
+      worktreeDir: "./worktrees/my-project",
+    },
+  ],
+};
+
+export default config;
+```
+
+### Multi-repo config
+
+```javascript
+// @ts-check
+
+/** @satisfies {import("sync-worktrees").SyncWorktreesConfig} */
+const config = {
   defaults: {
-    cronSchedule: "0 * * * *",  // Hourly
-    runOnce: false,
-    branchMaxAge: "30d",  // Only sync branches active in last 30 days
-    branchExclude: ["wip-*", "tmp-*"],  // Exclude WIP and temporary branches
-    updateExistingWorktrees: true  // Auto-update worktrees that are behind (default: true)
+    cronSchedule: "0 * * * *",        // hourly
+    branchMaxAge: "30d",               // ignore stale branches
+    branchExclude: ["wip-*", "tmp-*"],
+    updateExistingWorktrees: true,
   },
 
-  // Retry configuration (optional - these are the defaults)
   retry: {
-    maxAttempts: 'unlimited',  // or a number like 5
-    initialDelayMs: 1000,      // Start with 1 second
-    maxDelayMs: 600000,        // Max 10 minutes between retries
-    backoffMultiplier: 2       // Double the delay each time
+    maxAttempts: "unlimited",
+    initialDelayMs: 1000,
+    maxDelayMs: 600000,
+    backoffMultiplier: 2,
   },
 
   repositories: [
     {
-      name: "frontend",  // Unique identifier
+      name: "frontend",
       repoUrl: "https://github.com/company/frontend.git",
-      worktreeDir: "./worktrees/frontend",  // Relative paths supported
-      cronSchedule: "*/30 * * * *"  // Override default
+      worktreeDir: "./worktrees/frontend",
+      cronSchedule: "*/30 * * * *",   // override default
     },
     {
       name: "backend",
-      repoUrl: process.env.BACKEND_REPO_URL,  // Environment variables supported
+      repoUrl: process.env.BACKEND_REPO_URL || "https://github.com/company/backend.git",
       worktreeDir: "/absolute/path/backend-worktrees",
-      branchMaxAge: "6m",  // Override: only sync branches active in last 6 months
-      branchInclude: ["feature/*", "release-*", "main"],  // Only sync specific branches
-      // Uses default schedule
-      retry: { maxAttempts: 10 }  // Override retry for this repo
-    }
-  ]
+      branchMaxAge: "6m",
+      branchInclude: ["feature/*", "release-*", "main"],
+      retry: { maxAttempts: 10 },     // per-repo override
+    },
+  ],
 };
+
+export default config;
 ```
 
-**Notes:**
-- Relative paths are resolved from the config file location
-- `bareRepoDir` defaults to `.bare/<repo-name>` if not specified
-- Repository-specific settings override defaults
+Notes:
 
-### Retry Configuration
+- `bareRepoDir` defaults to `.bare/<repo-name>` if not specified.
+- Repository-specific settings override `defaults`.
 
-The tool automatically retries on network errors and filesystem race conditions:
+### Clone mode
 
-- **Default behavior**: Unlimited retries with exponential backoff (1s, 2s, 4s... up to 10 minutes)
-- **Network errors**: Connection timeouts, DNS failures, repository access issues
-- **Filesystem errors**: Busy files, permission issues, race conditions
+Set `mode: "clone"` to clone one checked-out branch directly into `worktreeDir` instead of maintaining one worktree per remote branch:
 
-Simple retry examples:
 ```javascript
-// Global retry configuration
-retry: { maxAttempts: 5 }                    // Try 5 times then stop
-retry: { maxAttempts: 'unlimited' }          // Keep trying forever (default)
-retry: { maxDelayMs: 60000 }                 // Cap retry delay at 1 minute
-retry: { initialDelayMs: 5000 }              // Start with 5 second delay
-
-// Per-repository override
-repositories: [{
-  name: "critical-repo",
-  // ... other config ...
-  retry: { maxAttempts: 'unlimited', initialDelayMs: 10000 }
-}]
-```
-
-### Git LFS Support
-
-For repositories with Git LFS issues or when large files aren't needed:
-
-```bash
-# Skip LFS downloads
-sync-worktrees -u https://github.com/user/repo.git -w ./worktrees --skip-lfs
-
-# Or in config file
-defaults: {
-  skipLfs: true
+{
+  name: "game-platform",
+  repoUrl: "ssh://git@example.com/game-platform.git",
+  worktreeDir: "./slots/game-platform",
+  mode: "clone",
+  branch: "main",
+  depth: 1,                            // optional shallow clone
 }
 ```
 
-The tool automatically handles LFS errors by retrying with LFS disabled (max 2 retries by default, configurable via `retry.maxLfsRetries`).
-
-### Branch Name Filtering
+Clone mode keeps the normal `+refs/heads/*:refs/remotes/origin/*` fetch refspec, so `git branch -r` and `git fetch --all --prune` can see all remote branches. `branch` controls the checked-out branch that sync-worktrees fast-forwards on each sync. Omit `branch` and the remote HEAD is resolved at clone time.
 
-You can control which branches get synced using include and exclude patterns. This is useful for repositories where you only care about specific branch types (e.g., feature branches) or want to skip certain patterns (e.g., WIP branches).
+`depth` is valid only for clone-mode repositories and must be a positive safe integer. Shallow clones use `--no-single-branch` so all remote branch refs remain visible at the configured depth. If you later remove `depth` from the config, the next sync unshallows the existing clone with `git fetch --unshallow`.
 
-**Pattern syntax**: Patterns support `*` wildcards that match any characters (including `/` in branch names).
-- `feature/*` - matches `feature/login`, `feature/auth/oauth`, etc.
-- `release-*` - matches `release-1.0`, `release-2.0-beta`, etc.
-- `*-hotfix` - matches `urgent-hotfix`, `prod-hotfix`, etc.
+Clone mode rejects `branchInclude`, `branchExclude`, `branchMaxAge`, `updateExistingWorktrees`, and `bareRepoDir` at validation time (whether set directly or inherited via `defaults`) — they have no meaning for a single-branch checkout.
 
-**Filtering semantics**:
-- `branchInclude` - only branches matching at least one pattern are synced
-- `branchExclude` - branches matching any pattern are skipped
-- When both are set, include runs first, then exclude removes from the result
-- The default branch (e.g., `main`) is always retained regardless of filters
+### Sparse checkout
 
-**Examples**:
-```bash
-# Command line
-sync-worktrees -u https://github.com/user/repo.git -w ./worktrees \
-  --branchInclude "feature/*,release-*"
+For monorepos where you only need a subset of folders, set `sparseCheckout` per repository entry. The tool runs `git worktree add --no-checkout`, configures sparse-checkout, then materializes only the included paths. The same repository URL can be listed multiple times under different `name`s with different sparse patterns to build domain-grouped layouts.
 
-sync-worktrees -u https://github.com/user/repo.git -w ./worktrees \
-  --branchExclude "wip-*,tmp-*"
+```javascript
+// @ts-check
 
-# Config file - global default
-defaults: {
-  branchExclude: ["wip-*", "tmp-*"]
-}
+/** @satisfies {import("sync-worktrees").SyncWorktreesConfig} */
+const config = {
+  repositories: [
+    {
+      name: "roulette-game-client",
+      repoUrl: "https://github.com/acme/casino-monorepo.git",
+      worktreeDir: "/Users/me/game-clients/roulette",
+      sparseCheckout: { include: ["game-client"] },
+    },
+    {
+      name: "roulette-autocue",
+      repoUrl: "https://github.com/acme/casino-monorepo.git",
+      worktreeDir: "/Users/me/autocues/roulette",
+      sparseCheckout: { include: ["autocue"] },
+    },
+  ],
+};
 
-# Config file - per repository
-repositories: [{
-  name: "frontend",
-  branchInclude: ["feature/*", "release-*"],
-  branchExclude: ["feature/wip-*"],
-}]
+export default config;
 ```
 
-**Combining with age filtering**: Branch name filtering runs first, then age filtering (`branchMaxAge`) is applied to the remaining branches. This lets you narrow down to specific branch types and further filter by activity.
+**Modes:**
 
-```bash
-# Only feature branches active in the last 30 days
-sync-worktrees -u https://github.com/user/repo.git -w ./worktrees \
-  --branchInclude "feature/*" --branchMaxAge 30d
-```
+- `cone` (default): pass folder names in `include`. Fast and recommended.
+- `no-cone`: pass gitignore-style patterns including `!negation`. Required for `exclude` and any `!`-prefixed include.
 
-### Branch Age Filtering
+If you set `exclude` or `!`-prefixed patterns while `mode: "cone"` is explicit, the tool auto-promotes to `no-cone` and logs a warning.
 
-To reduce clutter and save disk space, you can configure sync-worktrees to only sync branches that have been active within a specified time period. This is particularly useful for repositories with many stale or abandoned branches.
+**Duplicate `repoUrl` handling:** The first entry per `repoUrl` keeps the URL-derived bare path (`.bare/<repo-slug>`). Subsequent duplicate entries auto-derive `bareRepoDir` from `name` (`.bare/<name>`). Pin `bareRepoDir` explicitly on duplicate entries if you want config order to be irrelevant.
 
-**Duration format**: `<number><unit>`
-- `h` - hours (e.g., `24h`)
-- `d` - days (e.g., `30d`)
-- `w` - weeks (e.g., `4w`)
-- `m` - months (e.g., `6m`)
-- `y` - years (e.g., `1y`)
+**Narrowing safety:** When a sync would narrow an existing worktree's sparse patterns (remove a previously included path), it first checks the worktree is clean. If there are uncommitted changes, unpushed commits, or in-progress operations, the sparse update is skipped with a warning.
 
-**Examples**:
-```bash
-# Command line
-sync-worktrees -u https://github.com/user/repo.git -w ./worktrees --branchMaxAge 30d
+### Branch filtering
 
-# Config file - global default
+Two filters can be combined:
+
+```javascript
 defaults: {
-  branchMaxAge: "90d"  // Only sync branches active in last 90 days
+  branchInclude: ["feature/*", "release-*", "main"],
+  branchExclude: ["feature/wip-*"],
+  branchMaxAge: "30d",
 }
-
-# Config file - per repository
-repositories: [{
-  name: "active-project",
-  branchMaxAge: "14d",  // Very active project - only last 2 weeks
-}, {
-  name: "legacy-project",
-  branchMaxAge: "1y",   // Legacy project - keep branches from last year
-}]
 ```
 
-When branch filtering is active, the tool will:
-- Fetch commit timestamps for all remote branches
-- Filter out branches older than the specified age
-- Log how many branches were excluded
-- Only create/maintain worktrees for active branches
-
-### Handling Rebased and Force-Pushed Branches
-
-sync-worktrees intelligently handles branches that have been rebased or force-pushed to prevent data loss:
-
-**Automatic behavior (no configuration needed):**
+- **Name patterns** support `*` wildcards (including across `/`): `feature/*` matches `feature/login` and `feature/auth/oauth`.
+- **`branchInclude`** keeps only matching branches; **`branchExclude`** removes matching branches. When both are set, include runs first, then exclude.
+- **`branchMaxAge`** drops branches whose latest commit is older than the duration (`h`/`d`/`w`/`m`/`y` — e.g. `24h`, `30d`, `6m`, `1y`). Applied after name filtering.
+- The default branch is always retained regardless of filters.
 
-1. **Clean rebases** - When a branch is rebased but the file content remains identical:
-   - Automatically resets the worktree to match the upstream
-   - No data loss since the content is the same
+### Diverged branches
 
-2. **Diverged branches with NO local changes** - When someone force-pushes but you haven't made local commits:
-   - Automatically resets to the new upstream state
-   - No move to `.diverged` since you have no work to preserve
-   - Keeps `.diverged` clean by only preserving actual user work
+When upstream is force-pushed and your worktree contains divergent local commits, sync-worktrees moves the worktree to a hidden `.diverged/` directory before creating a fresh one from the new upstream. No data loss; you can review the old state later.
 
-3. **Diverged branches WITH local changes** - When a branch has different content AND you've made local commits:
-   - Moves the worktree to `.diverged` directory within your worktrees folder
-   - Preserves all your local changes and commits
-   - Creates a fresh worktree from the upstream branch
-   - Logs clear instructions for reviewing diverged changes
-
-**Example diverged structure:**
 ```
 my-repo-worktrees/
 ├── main/
 ├── feature-a/
-├── feature-b/
-└── .diverged/                      # Hidden diverged directory
-    ├── 2024-01-15-feature-x/      # Timestamp + branch name
-    │   ├── .diverged-info.json    # Metadata about the divergence
-    │   └── [all your local files]
-    └── 2024-01-16-feature-y/
+└── .diverged/
+    └── 2024-01-15-feature-x/
         ├── .diverged-info.json
         └── [all your local files]
 ```
 
-**Reviewing diverged worktrees:**
+Reviewing a diverged worktree:
+
 ```bash
-# See what's different
 cd my-repo-worktrees/.diverged/2024-01-15-feature-x
 git diff origin/feature-x
 
-# If you want to keep your changes
-git push --force-with-lease
-
-# If you want to discard and use upstream
-cd ../..
-rm -rf .diverged/2024-01-15-feature-x
+# keep local: git push --force-with-lease
+# discard:   cd ../.. && rm -rf .diverged/2024-01-15-feature-x
 ```
 
-This ensures you never lose work due to force pushes while keeping your worktrees in sync with upstream.
+The TUI's worktree status view (`w`) lists diverged directories and offers a guided delete (`d` with `y`/`n` confirmation) once you've decided.
 
-### Sparse Checkout
+Clean rebases where file content matches the upstream are auto-applied with no detour through `.diverged/`. Diverged-but-no-local-commits is also handled without preservation, since there's no user work to keep.
 
-For monorepos where you only need a subset of folders, set `sparseCheckout` per repository entry. The tool runs `git worktree add --no-checkout`, configures sparse-checkout, then materializes only the included paths. The same repository can be listed multiple times under different `name`s with different sparse patterns to build domain-grouped layouts.
+### Retry and LFS
 
-```js
-export default {
-  repositories: [
-    {
-      name: "roulette-game-client",
-      repoUrl: "https://github.com/acme/casino-monorepo.git",
-      worktreeDir: "/Users/me/game-clients/roulette",
-      sparseCheckout: { include: ["game-client"] },
-    },
-    {
-      name: "roulette-autocue",
-      repoUrl: "https://github.com/acme/casino-monorepo.git",
-      worktreeDir: "/Users/me/autocues/roulette",
-      sparseCheckout: { include: ["autocue"] },
-      // bareRepoDir: ".bare/roulette-autocue", // pin to make config reorder-proof
-    },
-  ],
-};
+The tool retries network errors (timeouts, DNS failures, access issues) and filesystem race conditions automatically:
+
+```javascript
+retry: { maxAttempts: 5 }              // try 5 times then stop
+retry: { maxAttempts: "unlimited" }    // keep trying forever (default)
+retry: { maxDelayMs: 60000 }           // cap retry delay at 1 minute
 ```
 
-**Modes:**
+For repositories with Git LFS issues or large files you don't need, set `skipLfs: true` in `defaults` or per repository. The tool also retries LFS-specific failures with LFS disabled (configurable via `retry.maxLfsRetries`).
 
-- `cone` (default): pass folder names in `include`. Fast and recommended.
-- `no-cone`: pass gitignore-style patterns including `!negation`. Required for `exclude` and any `!`-prefixed include.
+### Hooks and file copying
+
+Two lifecycle hooks the example config covers in depth:
+
+- `hooks.onBranchCreated` — array of shell commands run after a new branch's worktree is created. Placeholders: `{BRANCH_NAME}`, `{WORKTREE_PATH}`, `{REPO_NAME}`, `{BASE_BRANCH}`, `{REPO_URL}`. Fire-and-forget.
+- `filesToCopyOnBranchCreate` — paths copied into every newly created worktree (e.g. `.env.local`, `.npmrc`). Glob patterns are resolved relative to the config file's directory.
 
-If you set `exclude` or use `!`-prefixed patterns while `mode: "cone"` is explicit, the tool auto-promotes to `no-cone` and logs a warning.
+In clone mode, `filesToCopyOnBranchCreate` fires once on the initial clone, and `hooks.onBranchCreated` fires only for TUI-initiated branch creation (clone mode tracks a single fixed branch with no later branch-creation events).
 
-**Duplicate `repoUrl` handling:**
+For every knob (timeouts, parallelism, jitter, sparse-update behavior, retry tuning), see [`sync-worktrees.config.example.js`](./sync-worktrees.config.example.js).
 
-The first entry per `repoUrl` keeps the URL-derived bare path (`.bare/<repo-slug>`). Subsequent duplicate entries auto-derive `bareRepoDir` from `name` (`.bare/<name>`) so they do not collide. Pin `bareRepoDir` explicitly on duplicate entries if you want config order to be irrelevant.
+## CLI options
+
+The CLI loads a config file and runs it. Most run-mode settings (branch filters, retry, parallelism, LFS, clone mode, depth, etc.) live in the config file. Use `--runOnce` for an ad-hoc one-shot run without editing config.
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--config` | `-c` | Path to JavaScript config file (auto-detected in CWD when omitted) | - |
+| `--runOnce` | - | Run a sync once and exit, overriding config `runOnce` settings for this invocation | `false` |
+| `--help` | `-h` | Show help | - |
+| `--version` | - | Print version | - |
 
-**Narrowing safety:**
+Subcommands:
 
-When a sync would narrow an existing worktree's sparse patterns (remove a previously included path), it first checks the worktree is clean. If there are uncommitted changes, unpushed commits, or in-progress operations, the sparse update is skipped with a warning. Clean or stash local changes to apply the narrower patterns.
+- `sync-worktrees init [--config <path>] [--force]` — interactive wizard that writes a minimal config file (`./sync-worktrees.config.js` by default). Refuses to overwrite an existing target unless `--force` is passed.
+- `sync-worktrees list [--config <path>] [--filter <pattern>]` — print the resolved repositories and exit.
 
 ## Requirements
 
 - Node.js >= 22.0.0
 - Git
-- [`tmux`](https://github.com/tmux/tmux) (optional, required only for Terminal mode in the TUI)
 - An MCP-capable client (optional, only for the `sync-worktrees-mcp` server)
 
 ## Contributing