> worktrees & cloud
Worktrees let the agent edit in an isolated git checkout under ~/.cursor/worktrees instead of your working tree, so experiments never dirty your current branch. Base them on any ref and bootstrap them with setup scripts. When a task outgrows your terminal, prepend & to hand it to a Cloud Agent that keeps running remotely.
// worktrees & cloud
4 commands$ cursor-agent -w feature-auth$ cursor-agent -w hotfix --worktree-base main$ { "setup": ["npm install", "cp .env.example .env"] }$ & refactor the auth module and add comprehensive tests// faq
Where does cursor-agent -w put the worktree?
Under ~/.cursor/worktrees/<reponame>/<name>, alongside worktrees created from the editor. Omit the name and Cursor generates one. Only file edits move there — your current checkout stays clean — and Cursor cleans them up with the same retention rules as editor worktrees.
How do I copy .env files into a new worktree?
A fresh worktree is a clean git checkout, so gitignored files like .env and node_modules are not carried over. Add a .cursor/worktrees.json with setup scripts (for example npm install and cp .env.example .env) that run on creation. Skip them for a single run with --skip-worktree-setup.
How do I hand a task to a Cloud Agent from the CLI?
Prepend & to any message in a session — for example "& refactor the auth module and add tests" — and the task moves to a Cloud Agent that runs in Cursor's infrastructure while you step away. Pick it back up on web or mobile at cursor.com/agents.
Is there a --cloud flag?
No. Cloud handoff is done with the & message prefix inside a session, not a command-line flag. The CLI parameters reference has no --cloud option, so running cursor-agent --cloud will not start a cloud agent — use the & prefix on your prompt instead.