diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index c61ab2ae686a..daf857d79c5b 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -74,9 +74,9 @@ for available options. ## Agents view Claude Code's [agents view](https://code.claude.com/docs/en/agent-view) -dispatches tasks to subagents that work in parallel, each in its own -Git worktree. Pair it with [clone mode](../workflows.md#clone-mode) for an -isolated multi-agent workflow: +starts background sessions that run tasks in parallel. Pair it with +[clone mode](../workflows.md#clone-mode) to keep their changes inside the +sandbox: ```console $ sbx run --clone claude -- agents @@ -92,10 +92,14 @@ use Claude Code's auto mode or pass the flag explicitly: $ sbx run --clone claude -- --dangerously-skip-permissions agents ``` -The subagents' worktrees live inside the sandbox's private clone — none -of them touches your host repository. Each subagent commits to its own -branch, and you review the work from the host by fetching the -`sandbox-` remote: +Claude Code may use branches or worktrees to keep changes from its background +sessions separate. This depends on the task, Claude Code configuration, and +project instructions. The `--clone` flag doesn't control this behavior. Claude +Code creates any branches and worktrees inside the sandbox, not in your host +checkout. + +To review a branch created by a session, fetch the +`sandbox-` remote from the host: ```console $ git fetch sandbox- diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 5b5008b3c721..b6ec903dd3f2 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -135,8 +135,10 @@ it when you create the sandbox: - Direct mode is the default. The agent has read-write access to your working tree, and changes appear on your host immediately. -- [Clone mode](#clone-mode) uses `--clone`. The agent works in a private Git - clone inside the sandbox, and your host repository is mounted read-only. +- [Clone mode](#clone-mode) uses `--clone`. The agent edits a separate Git clone + inside the sandbox. Its changes stay there until you fetch them or the agent + pushes them. Your host repository is also available at + `/run/sandbox/source`, but only with read access. For guidance on branch strategy, fetching work from a sandbox, and parallel agent workflows, see [Git workflows](workflows.md#git-workflows). For the diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 1de3477ae845..1d66e8d0cd92 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -59,16 +59,16 @@ turn-by-turn. ### Clone mode -In clone mode, the sandbox gets a private Git clone. The agent manages its -own branches and commits inside that clone; your host working tree is never -touched. When the agent is done, you either fetch its branches to the host or -ask the agent to push directly to your fork. +In clone mode, `sbx` creates a separate Git clone inside the sandbox. The agent +edits this clone instead of your host working tree. Its changes stay inside the +sandbox until you fetch a branch or the agent pushes one to a remote. Your host +repository is also available at `/run/sandbox/source`, but only with read +access. The sandbox clone is not a Git worktree linked to your host checkout. -Clone mode is designed for parallelism: a single clone-mode sandbox can hold -many branches at once, and subagent orchestrators (such as Claude Code's -[agents view](agents/claude-code.md#agents-view)) can dispatch independent -tasks to separate agents, each working on its own branch or worktree inside -the clone. +A single clone-mode sandbox can hold multiple branches and worktrees for +parallel tasks. The `--clone` flag creates the clone, but it doesn't separate +one task from another. To keep parallel tasks isolated, instruct your agent tool +to create a separate branch or worktree for each task. > [!NOTE] > `--clone` is a create-time flag and cannot be changed on an existing @@ -135,10 +135,9 @@ It's only reachable while the sandbox is running: $ sbx run --clone claude ``` -2. Dispatch each independent task to a separate subagent. Claude Code handles - branch isolation for subagents automatically in agents view. For other - agents (such as Codex), add an instruction to `AGENTS.md` to get the same - behavior: +2. Dispatch each independent task to a separate background session. Your agent + tool may use branches or worktrees to keep their changes separate. If it + doesn't, add a project instruction such as: ```markdown Always start each task on its own git branch before making changes.