Cloud agents

On Cursor, /synthex:next-priority/synthex:next-priority can run each parallel Tech Lead as a cloud subagent instead of in a local git worktree. Each worker gets its own VM and its own branch, shows up as a subagent under your session, and pushes its work to the remote. Your session validates each task, fetches the branch, and merges it. Cloud execution is opt-in, and on every other host Synthex falls back to local worktrees.

#Turning it on

Three inputs decide where the workers run. They resolve in this order:

1. A flag on the call. --in-cloud forces cloud for this run. --local forces local worktrees for this run. If you pass both, --local wins, because it is the safer choice.
2. The config key next_priority.execution_environment, set to local or cloud.
3. The default, local.

To make cloud the default for a project, set the key in .synthex/config.yaml:

next_priority:
  execution_environment: cloud # local | cloud (default: local)

--local exists so you can override a project-level cloud default for one run. The default stays local because cloud runs need a pushed remote and a configured cloud environment, and switching people to them silently would surprise anyone working locally.

#Prerequisites

• Cursor. Cloud fan-out needs a spawn tool that takes an environment parameter. Cursor's Task tool does. Claude Code's Agent and Task tools do not support cloud VMs today.
• A cloud environment for the repo. Configure the repository's environment at cursor.com/agents and give cloud agents write access to the remote. Workers have to push their branches.
• Committed, pushed work. A cloud worker clones from the remote, so it cannot see your uncommitted changes or your unpushed commits. If the selected tasks depend on local edits the cloud clone would not have, Synthex stops before spawning anything. It tells you which paths or commits to commit and push, or suggests --local.
• Cloud secrets may differ from local ones. Workers run with the team's cloud environment, not your machine's MCP servers and secrets.

#What happens during a cloud run

Steps 1–3 and 6–9 of /synthex:next-priority/synthex:next-priority are the same as a local run: select independent tasks, search for existing work, mark the tasks in progress, monitor, validate, and update the plan. Cloud mode changes three steps.

#Step 4: no worktrees, one base branch

Synthex skips git worktree add. It resolves cloud_base_branch, the remote-tracking branch the workers fork from. That is usually the current branch's upstream, otherwise the repo's default branch. It never passes a local-only or detached ref. This is also where the unsynced-changes check runs.

#Step 5: spawn every worker at once

Each Tech Lead is a Cursor Task call with:

• environment: "cloud"
• run_in_background: true
• cloud_base_branch: <resolved base>

All the calls go out in one message, so the workers run at the same time. Each one appears as a subagent under your session. Each worker:

1. Creates its branch from the cloud base: {worktrees.branch_prefix}[task-id]-[short-description]. This is the same naming a local run uses, for example feature/12-login-form with the default prefix.
2. Implements the task, writes a test for every [T] criterion, and commits.
3. Pushes the branch to the remote and reports the branch name in its completion summary, plus a PR URL if it opened one.
4. Does not merge. Merging is the parent's job.

#Step 8: fetch and fast-forward

There is no worktree to remove. After the pre-merge gate passes (every [T] criterion has a passing test, every [H] criterion is approved by you, and the full test suite passes), the parent fetches the worker's branch and merges it with the same policy as a local run:

git fetch origin feature/12-login-form
git merge --ff-only FETCH_HEAD

If a fast-forward isn't possible, it tries a merge commit. If the worker only opened a PR, the parent fetches the PR's head ref instead.

#Foreground and background

Cursor's Task tool runs in the foreground by default, which would make a parallel batch run one task at a time. Synthex sets the mode on each call:

The same background rule applies to local runs on Cursor. Synthex never sends an empty cloud_base_branch with a non-cloud environment, because Cursor rejects that combination.

#Limits

• One level of nesting. On Cursor, a subagent can spawn children only one level deep. A cloud Tech Lead must not have its specialists fan out further subagents of their own.
• No inbox messaging. Cloud workers talk to the parent only through the Task result, resume, the completion notification, and git branches. They never use the standing-pool filesystem inboxes or any mailbox protocol.
• Subagents, not sibling agents. Synthex uses Task with environment: "cloud" rather than the Cloud Agents API, which would create separate top-level agents instead of subagents of your session.

#On other hosts

If cloud resolves but the host's spawn tool has no environment parameter, Synthex prints one line and continues with local worktrees:

Cloud execution is not supported on this host — falling back to local worktrees.

That includes Claude Code. Claude Code has cloud sessions, but messages from a cloud session back to its parent are incomplete, and the merge gate depends on them. Cloud orchestration from a Claude Code parent is deferred until that works.

#Unattended runs

Cloud execution works with native looping and --auto-decide:

# Use cloud workers for this run only
/synthex:next-priority --in-cloud

# Keep delivering batches until the plan is done
/synthex:next-priority --in-cloud --loop

# Unattended: take the recommended option at discretionary decisions
/synthex:next-priority --in-cloud --loop --auto-decide

--auto-decide never applies to [H] criteria. A loop still stops to ask you for every human approval before that task merges. See Native looping for loop state and cancellation.

#Local worktrees vs cloud agents

#Cursor Task agent wrappers

Synthex ships generated Cursor subagent wrappers in the plugin's cursor-agents/ directory, one per agent. Each wrapper has Cursor frontmatter (name, description, model: inherit, and readonly: true for advisory roles such as code-reviewer, security-reviewer, and architect) and points at the canonical file in agents/. The wrappers never set is_background; the parent chooses foreground or background on each Task call.

To use them in your project, copy or symlink the plugin's cursor-agents/ directory to .cursor/agents/, or merge just the roles you want. Cursor also loads .claude/agents/; the wrappers are the path with Cursor-native frontmatter. Don't edit them by hand: they are regenerated from the canonical agents.

#Next

• Parallel execution — task selection, worktrees, and the merge gate
• Workspaces & config layers — where execution_environment and the worktree settings can live
• Agent compatibility — Cursor and the other supported hosts