Parallel work with worktrees

A git worktree is a second checkout of the same repository in another folder, on its own branch. Give each Syntic Code session its own worktree and you can run several tasks at once without them editing the same files.

Open a worktree session

syntic --worktree payment-retries      # or: syntic -w payment-retries

• The worktree is created at .syntic/worktrees/payment-retries, on a branch named syntic/payment-retries.
• Run the same command again later and the same worktree is reused.
• Leave out the name and one is generated for you.

Open a second terminal, start another worktree session, and the two work side by side.

Work on a pull request

Pass a pull request (or GitLab merge request) instead of a name, and its head is fetched and checked out for you:

syntic -w https://github.com/acme/api/pull/482
syntic -w '#482'                 # GitHub pull request on origin
syntic -w '!45'                  # GitLab merge request on origin

The branch is called syntic/pr-482 (or syntic/mr-45).

Keep each session in tmux

syntic -w <name> --tmux runs the session inside a tmux session named after the worktree, and attaches to it if it is already running. Close the terminal and reattach later with tmux.

When you are done

On exit, Syntic Code keeps the worktree and tells you where it is. To remove it, leave with /exit remove (the branch is kept), or run git worktree remove <path> yourself. Merge or open a pull request from the branch as usual.

Choose what a new worktree starts from

{
  "worktree": {
    "baseRef": "fresh",
    "sparsePaths": ["services/billing", "libs/shared"]
  }
}

These apply to --worktree, to worktrees the agent creates, and to agents that run isolated.

Worktrees the agent makes

• The agent can step into a worktree mid-session with its EnterWorktree tool, and back out with ExitWorktree.
• A custom agent with isolation: worktree always gets a separate worktree (Subagents).
• /batch <task> splits a big change into parts and gives each part an agent with its own worktree.
• syntic --bg runs a background session in a fresh worktree, so your checkout is left alone.

Hooks

WorktreeCreate and WorktreeRemove hooks run when worktrees are made or removed. A WorktreeCreate hook can create the worktree itself (for example with extra setup) and report where, or refuse.