Gemini CLI --worktree for Parallel Sessions

To run Gemini CLI --worktree parallel sessions, enable experimental.worktrees, then start each session in a separate terminal with a unique worktree name. The experimental --worktree flag creates a worktree and starts Gemini CLI in it. Each session gets its own working directory, so two agents can edit the same repository without writing to the same files. You still need to review and combine their changes afterward.

Enable worktrees

Start Gemini CLI normally and use /settings to turn on Enable Git Worktrees. Alternatively, put this JSON in settings.json:

{
  "experimental": {
    "worktrees": true
  }
}

The setting defaults to false and requires a restart. Use ~/.gemini/settings.json if you want it for your user account across projects, or .gemini/settings.json at the project root for project settings. If that file already exists, add the experimental entry to its existing JSON rather than replacing other settings.

Run the commands below from a Git repository. If Gemini CLI is not installed yet, use its official installation page to choose an installation method. Worktree support is experimental, so check the current CLI help and worktree guidance if your installed version behaves differently.

Launch concurrent sessions

For example, suppose auth-api and docs-nav are two independent tasks. Open two terminals at the same repository root. In the first, run:

gemini --worktree auth-api

In the second, run:

gemini --worktree docs-nav

Give each session a bounded request: specify the change, the files or component it owns, and the check it should run. One could update an authentication endpoint while the other edits navigation documentation. If both tasks must change the same interface or configuration file, decide who owns that shared change before launching them. Separate directories prevent simultaneous edits to one checkout; they do not make overlapping changes easy to merge.

Gemini places named worktrees under .gemini/worktrees/. You can also run gemini --worktree without a name and let it generate one. Naming them yourself makes it easier to match a terminal, task, directory, and branch later. Use a distinct name for every active session.

From the repository, run:

git worktree list

Git lists each linked worktree with its path and checked-out branch. Keep that output handy when reviewing or merging. Use the branch shown there rather than assuming its spelling from the worktree name.

What the directory separation covers

Git worktrees have separate working directories and per-worktree files such as HEAD and the index, while remaining attached to one repository. That gives each Gemini session its own place to create, stage, and commit source changes. It does not give each session a separate database, port, external service, or account. If both agents run an app server, assign different ports; if both run tests against a mutable database, give each a separate database or test environment. The same principle applies to caches and generated files stored outside the worktree. See isolating test databases for parallel agents for that part of the setup.

Initialize each new directory according to your project’s normal workflow. Dependencies, virtual environments, local configuration, and generated artifacts may need setup in each worktree. Tell each agent which checks to run and where their output belongs. Avoid asking one session to modify files in another session’s directory, because that defeats the reason for creating separate worktrees.

Before starting, make prerequisite source changes available in a commit if both sessions need them. Give the agents tasks that can begin from the same agreed state, and avoid moving that starting point between launches. This reduces the chance that their work is based on different assumptions.

Choose manual worktrees when you need another location

Gemini’s flag is convenient when its managed location suits your project. If you need directories elsewhere or want to choose the Git branch names yourself, create the worktrees with Git and start ordinary Gemini sessions inside them. For example, from the project root:

git worktree add -b api-tests ../project-api-tests
git worktree add -b ui-copy ../project-ui-copy

Then open a terminal in each new directory and run gemini there:

cd ../project-api-tests
gemini

In the other terminal, use cd ../project-ui-copy followed by gemini. Git’s -b option creates the named branch from the current HEAD when you omit a starting commit. A branch already checked out in another worktree, or a branch name that already exists, needs a different plan; choose a fresh name instead of forcing Git past the safeguard.

The two approaches solve the same directory problem. The native flag handles worktree creation at Gemini startup; manual creation gives you explicit paths and branch names. Pick one approach for a task rather than creating a manual worktree and then passing --worktree inside it, which would request another worktree.

Review and merge one task at a time

When an agent says it is finished, enter that task’s worktree and check its state. For the named worktree above, run these commands from the repository root, replacing <integration-branch> with the branch you intend to merge into:

cd .gemini/worktrees/auth-api
git status --short
git diff
git diff --cached
git diff <integration-branch>...HEAD

git status --short gives a compact list of changed and untracked paths. git diff shows unstaged changes, git diff --cached shows staged changes, and git diff <integration-branch>...HEAD compares committed changes from the branches’ common ancestor to HEAD. The last comparison matters even when status is empty because an agent may already have committed its work. An untracked file appears in status but not in an ordinary unstaged diff; after you stage it with git add, inspect its contents with git diff --cached. Inspect the implementation, tests, generated files, and any unexpected edits before recording the result.

When the change is ready, stage only the files you intend to keep. For instance, git add places selected file contents in the index; git add -A stages all changes in that worktree, so use it only after checking the complete status. Review the staged result with git diff --cached, then create a commit: git commit records the staged contents. Run the project’s relevant checks in that worktree before integrating it.

Back in the main worktree, merge the completed branch shown by git worktree list:

git merge <branch-from-worktree-list>

git merge incorporates the named branch into the current branch. Replace the placeholder with the actual branch name. Merge one task, inspect the result and run the relevant checks, then merge the next. If both agents changed the same lines or relied on incompatible assumptions, resolve that interaction as part of review. The guide to merging parallel agent branches covers the integration step in more depth.

Resume and clean up

Leaving Gemini does not mean discarding the worktree. To continue a conversation, go to its directory and resume the saved session:

cd .gemini/worktrees/auth-api
gemini --resume <session-id>

Gemini’s session management supports resuming by session ID. Use the ID Gemini shows when exiting, or list the sessions available for that project before choosing one. Keep the directory if there are uncommitted changes or commits you still need to review.

After the work has been merged and the worktree is clean, return to the repository root and remove the linked directory with git worktree remove .gemini/worktrees/auth-api. Git refuses to remove an unclean worktree unless forced; treat that refusal as a prompt to inspect what remains. If you also want to remove its branch, use the actual name from your worktree list. git branch -d requires the branch to be merged, which is a useful final check. Repeat cleanup for each finished task.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux. It runs several AI coding agents, including Gemini CLI, in parallel with each agent isolated in its own git worktree, and provides a diff-first review surface. You can bring your existing agent CLI and editor; the app runs locally and does not require an extra subscription.

Frequently asked questions

Do I need a separate clone for each Gemini CLI session?

No. Git worktrees let one repository have multiple working directories, so you can use the native --worktree flag or create linked directories manually. Give concurrent sessions distinct worktrees and branch names.

Can two sessions use the same worktree?

They can be started from one directory, but then both can edit the same files, which removes the file-level separation this workflow is meant to provide. Start each concurrent task in its own worktree and coordinate any shared files during review and merge.

Does exiting Gemini delete the worktree or its changes?

No. Gemini leaves the worktree in place when you exit a worktree session, including uncommitted changes and commits. Resume from that directory when needed, then remove it yourself after reviewing and integrating the work.

Does a worktree isolate test databases and local servers?

No. It separates Git working directories, not services outside them. Assign distinct database instances, database names, ports, or other mutable resources when concurrent tasks would otherwise use the same ones.