Cursor CLI with Git Worktree

Worktree lets you have multiple directories (each on a different branch) for the same repo. Cursor CLI works on whichever directory it's run in. Combine them and you get multiple terminals running CLI Agents in parallel on different branches — no need for multiple Cursor windows, pure keyboard-driven multi-tasking.

Why Combine Them?

Common ground: each worktree is an independent directory → each has its own context → parallel development without stepping on each other's toes. Like having multiple clones working on different branches simultaneously.

Basic Usage: One Terminal Per Worktree

Assuming you've already created your worktrees:

~/projects/
├── my-app/                  ← main
├── my-app--feature-auth/    ← feature/auth
└── my-app--feature-payment/  ← feature/payment

Terminal 1 (working on auth):

cd ~/projects/my-app--feature-auth
cursor agent "Implement JWT login"

Terminal 2 (working on payment):

cd ~/projects/my-app--feature-payment
cursor agent "Add Stripe checkout flow"

The CLI defaults to the current working directory as its context, so both terminals only modify their respective worktrees. This is "two CLI Agents running in parallel" — no need to open two Cursor windows, saves resources and avoids context switching.

Without Changing Directories: Use --path to Target a Worktree

Sitting in the main project directory but want the CLI to work on a specific worktree:

cd ~/projects/my-app
cursor agent "Add unit tests for feature/auth" --path ../my-app--feature-auth

--path tells it which directory to look at — the worktree path. Good for handling one worktree at a time, or when the path is fixed in a script.

Non-Interactive + Worktree (Scripts / Batch Operations)

Run the same type of task on multiple worktrees in sequence (e.g., add a README to all, fix lint in all):

# Example: run "fix lint" on both worktrees
cursor agent "Fix all auto-fixable errors per .eslintrc" --path ../my-app--feature-auth --no-interactive
cursor agent "Fix all auto-fixable errors per .eslintrc" --path ../my-app--feature-payment --no-interactive

Or write a loop (adjust paths to match your setup):

for dir in ../my-app--feature-auth ../my-app--feature-payment; do
  cursor agent "Fix linter errors" --path "$dir" --no-interactive
done

Give one instruction, clean up multiple branches at once — great for a final sweep before raising PRs.

Relationship to "Worktree + Multiple Windows"

• Multiple windows: each Cursor window opens a worktree, using the IDE's Agent, Chat, Tab completion.
• CLI + Worktree: terminal + cursor agent — same idea of "one directory, one context," just open more terminals to parallelize.

You can also mix and match: main development in the window, while using the CLI on a server to make small fixes to another branch.

Summary

• Worktree = multiple directories, multiple branches; CLI = acts on the current directory or --path → a natural pair.
• Parallel: open multiple terminals, each cd into a different worktree, then run cursor agent.
• Single terminal: use --path <worktree-path> to target the worktree you want.
• Scripts/batch: --path + --no-interactive to run the same task across multiple worktrees.

Next: 07-unlimit-loop-debug — Let the CLI automatically loop and fix code until tests pass (you can go grab a coffee).