feat(worktree): add Git worktree support for isolated parallel sessions

Introduces a central Git worktree management system to enable isolated, parallel agent orchestration. This allows running multiple Gemini sessions on different branches within the same repository without file contention. Key Features: - Added 'WorktreeService' in @google/gemini-cli-core to manage creation, lifecycle, and cleanup of Git worktrees. - Implemented smart cleanup logic that detects untracked files and new commits, automatically preserving worktrees with uncommitted work. - Added '--worktree' (-w) flag to the CLI to launch sessions in fresh, isolated environments. - Enhanced the session exit experience with detailed status messages and instructions for resuming work in preserved worktrees.
2026-03-26 14:01:14 -07:00 · 2026-03-18 13:48:50 -04:00
parent fac3661980
commit 94ce4aba8b
25 changed files with 1159 additions and 8 deletions
--- a/docs/cli/cli-reference.md
+++ b/docs/cli/cli-reference.md
@@ -50,6 +50,7 @@ These commands are available within the interactive REPL.
 | `--model`                        | `-m`  | string  | `auto`    | Model to use. See [Model Selection](#model-selection) for available values.                                                                                            |
 | `--prompt`                       | `-p`  | string  | -         | Prompt text. Appended to stdin input if provided. Forces non-interactive mode.                                                                                         |
 | `--prompt-interactive`           | `-i`  | string  | -         | Execute prompt and continue in interactive mode                                                                                                                        |
+| `--worktree`                     | `-w`  | string  | -         | Start Gemini in a new git worktree. If no name is provided, one is generated automatically. Requires `experimental.worktrees: true` in settings.                       |
 | `--sandbox`                      | `-s`  | boolean | `false`   | Run in a sandboxed environment for safer execution                                                                                                                     |
 | `--approval-mode`                | -     | string  | `default` | Approval mode for tool execution. Choices: `default`, `auto_edit`, `yolo`                                                                                              |
 | `--yolo`                         | `-y`  | boolean | `false`   | **Deprecated.** Auto-approve all actions. Use `--approval-mode=yolo` instead.                                                                                          |
--- a/docs/cli/git-worktrees.md
+++ b/docs/cli/git-worktrees.md
@@ -0,0 +1,112 @@
+# Parallel sessions with Git worktrees
+
+When working on multiple tasks at once, you can use Git worktrees to give each
+Gemini session its own copy of the codebase. Git worktrees create separate
+working directories that each have their own files and branch while sharing the
+same repository history. This prevents changes in one session from colliding
+with another.
+
+Learn more about [session management](./session-management.md).
+
+> **Note:** This is a preview feature currently under active development. Your
+> feedback is invaluable as we refine this feature. If you have ideas,
+> suggestions, or encounter issues:
+>
+> - [Open an issue] on GitHub.
+> - Use the **/bug** command within Gemini CLI to file an issue.
+
+Learn more in the official Git worktree
+[documentation](https://git-scm.com/docs/git-worktree).
+
+## How to enable Git worktrees
+
+Git worktrees are an experimental feature. You must enable them in your settings
+using the `/settings` command or by manually editing your `settings.json` file.
+
+1.  Use the `/settings` command.
+2.  Search for and set **Enable Git Worktrees** to `true`.
+
+Alternatively, add the following to your `settings.json`:
+
+```json
+{
+  "experimental": {
+    "worktrees": true
+  }
+}
+```
+
+## How to use Git worktrees
+
+Use the `--worktree` (`-w`) flag to create an isolated worktree and start Gemini
+CLI in it.
+
+- **Start with a specific name:** The value you pass becomes both the directory
+  name (within `.gemini/worktrees/`) and the branch name.
+
+  ```bash
+  gemini --worktree feature-auth
+  ```
+
+- **Start with a random name:** If you omit the name, Gemini generates a random
+  one automatically (for example, `worktree-a1b2c3d4`).
+
+  ```bash
+  gemini --worktree
+  ```
+
+> **Note:** Remember to initialize your development environment in each new
+> worktree according to your project's setup. Depending on your stack, this
+> might include running dependency installation (`npm install`, `yarn`), setting
+> up virtual environments, or following your project's standard build process.
+
+## How to exit a worktree session
+
+When you exit a worktree session (using `/quit` or `Ctrl+C`), Gemini
+automatically determines whether to clean up or preserve the worktree based on
+the presence of changes.
+
+- **Automatic removal:** If the worktree is completely clean—meaning it has no
+  uncommitted changes and no new commits have been made—Gemini automatically
+  removes the worktree directory and deletes the temporary branch.
+- **Safe preservation:** If Gemini detects any changes, it leaves the worktree
+  intact so your work is not lost. Preservation occurs if:
+  - You have **uncommitted changes** (modified files, staged changes, or new
+    untracked files).
+  - You have made **new commits** on the worktree branch since the session
+    started.
+
+Gemini prioritizes a fast and safe exit: it **does not display an interactive
+prompt** to ask whether to keep the worktree. Instead, it ensures your work is
+safely preserved by default if any modifications are detected.
+
+## Resuming work in a worktree
+
+If a worktree was preserved because it contained changes, Gemini displays
+instructions on how to resume your work when you exit.
+
+To resume a session in a preserved worktree, navigate to the worktree directory
+and start Gemini CLI with the `--resume` flag:
+
+```bash
+cd .gemini/worktrees/feature-auth
+gemini --resume latest
+```
+
+## Managing worktrees manually
+
+For more control over worktree location and branch configuration, or to clean up
+a preserved worktree, you can use Git directly:
+
+- **Clean up a preserved worktree:**
+  ```bash
+  git worktree remove .gemini/worktrees/feature-auth --force
+  git branch -D worktree-feature-auth
+  ```
+- **Create a worktree manually:**
+  ```bash
+  git worktree add ../project-feature-a -b feature-a
+  cd ../project-feature-a && gemini
+  ```
+
+[Open an issue]: https://github.com/google-gemini/gemini-cli/issues
--- a/docs/cli/session-management.md
+++ b/docs/cli/session-management.md
@@ -96,6 +96,12 @@ Compatibility aliases:
 - `/chat ...` works for the same commands.
 - `/resume checkpoints ...` also remains supported during migration.

+## Parallel sessions with Git worktrees
+
+When working on multiple tasks at once, you can use
+[Git worktrees](./git-worktrees.md) to give each Gemini session its own copy of
+the codebase. This prevents changes in one session from colliding with another.
+
 ## Managing sessions

 You can list and delete sessions to keep your history organized and manage disk
@@ -206,3 +212,5 @@ becoming too large and expensive.
  across sessions.
 - Learn how to [Checkpoint](./checkpointing.md) your session state.
 - Check out the [CLI reference](./cli-reference.md) for all command-line flags.
+
+[Open an issue]: https://github.com/google-gemini/gemini-cli/issues
--- a/docs/cli/settings.md
+++ b/docs/cli/settings.md
@@ -147,6 +147,7 @@ they appear in the UI.
 | UI Label                   | Setting                                  | Description                                                                                                                                               | Default |
 | -------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | Enable Tool Output Masking | `experimental.toolOutputMasking.enabled` | Enables tool output masking to save tokens.                                                                                                               | `true`  |
+| Enable Git Worktrees       | `experimental.worktrees`                 | Enable git worktrees.                                                                                                                                     | `false` |
 | Use OSC 52 Paste           | `experimental.useOSC52Paste`             | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
 | Use OSC 52 Copy            | `experimental.useOSC52Copy`              | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
 | Plan                       | `experimental.plan`                      | Enable Plan Mode.                                                                                                                                         | `true`  |