Host workspaces

If you run Synthex inside an agent workspace manager such as Orca or Herdr, /synthex:next-priority/synthex:next-priority can launch each parallel Tech Lead as its own agent session in a child workspace. The workspace manager owns the checkout, so Synthex creates nothing under worktrees.base_path. You can watch every task in the tool's UI and step in when one is stuck. Host workspaces are opt-in.

#Turning it on

Pass --in-workspace for one run, or make it the project default:

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

The execution environment resolves in this order:

1. --local wins over everything.
2. --in-workspace or --in-cloud for this call. Passing both is refused with a one-line error.
3. next_priority.execution_environment from your config.
4. local.

Detecting Orca or Herdr never switches this on by itself. Child workspaces open tabs, sessions and checkouts in your tool, so you choose when that happens.

#Supported workspace managers

Synthex runs scripts/lib/detect-workspace-host.sh once per batch. It prints one of these:

A fallback prints one line and continues with a normal local run:

Host workspaces are not supported here (none) — falling back to local worktrees.

#What happens during a workspace run

Task selection, validation, the [H] gate and plan updates are the same as a local run. Four steps change.

#Step 4: prepare briefs

Each child workspace is a fresh checkout of your current branch, so it can't see uncommitted edits. If the selected tasks depend on them, Synthex stops and asks you to commit first (or to run with --local).

Synthex writes one brief per task into a temporary directory outside every checkout. The brief holds the task, its acceptance criteria, the project context and the git rules. Keeping it out of the checkout means a worker's git add -A can never commit it.

#Step 5: launch child workspaces

Every worker is launched before Synthex waits on any of them. Each one is told to act as the Synthex Tech Lead, work on branch {worktrees.branch_prefix}[task-id]-[short-description] (the same name a local run uses), commit there, and write its completion summary to a result file next to its brief. It launches the same agent you are running: claude, codex, gemini and so on.

In Orca the child workspace is created under your current one, so the task tree shows up in Orca's sidebar.

A brand-new checkout path can stop the agent at startup, for example on Claude Code's "Do you trust this folder?" question. Synthex never accepts a trust or permission prompt for you. It tells you which workspace is waiting, and continues once you have answered.

#Step 6: wait for results

Synthex waits on each worker (orca terminal wait --for tui-idle, or herdr agent wait), then reads its result file. If a worker is blocked on a question or approval, or finished without a result, Synthex tells you which workspace needs you. It never answers a worker's question for you.

#Step 8: merge and remove

The task branch is in the same repository, so Synthex merges it with the usual fast-forward first, merge commit if needed policy. Then it removes the child workspace through the tool (orca worktree rm / herdr worktree remove) before moving on. It never forces removal. A workspace with uncommitted changes is kept and reported to you.

#Claude Code worktree isolation

Without --in-workspace or --in-cloud, Claude Code runs use the Agent tool's built-in isolation: "worktree" for each Tech Lead. Synthex no longer runs git worktree add itself:

• This applies when worktrees.base_path is the default .claude/worktrees. Claude Code always puts its worktrees there, so a custom base_path keeps the manual git worktree add.
• Each worker first renames the branch Claude Code made to the task branch, so your worktrees.branch_prefix still shows up in history and PRs.
• Claude Code keeps a worktree that has commits and returns its path. Synthex merges the task branch and removes that worktree right after the merge.
• Specialists a Tech Lead delegates to start in the same isolated worktree.
• .worktreeinclude (created by /synthex:init/synthex:init) copies your gitignored env files into each worktree.

If a shell hook rewrites git so the isolation guard refuses it (the RTK token-saving hook does this), the worker retries with git's absolute path. If git is still refused, it reports back and Synthex reruns that task in a manual worktree.

Other hosts keep the manual git worktree add.

#Local, workspace or cloud

#Next

• Parallel execution — task selection, isolation and the merge gate
• Cloud agents — run each task on a Cursor cloud VM
• Configuration — execution_environment and the worktree settings