A scope is where work happens. Every thread belongs to one, and that scope owns exactly one workspace root: the folder the agent reads, writes, and runs commands in.
The Default scope is the project's own folder. It is always there and cannot be removed. Any other scope can be pointed at a folder of its own, which is where worktrees come in.
One scope, one root
In the Projects view, each scope is its own group with its threads under it. Threads in the same scope share one filesystem, so two of them running at once can overwrite each other's work.
A scope with its own worktree resolves to a separate checkout of the same repository, on its own branch, in a folder the app manages. Two scopes are two filesystems, so two runs cannot reach into each other's files.
The composer names the scope a thread runs in, and a new thread can be pointed at another scope before its first message. After that the thread stays there: its files, its Git state, its terminal, and its checkpoints all resolve through that scope.
Why a second run wants its own worktree
A second run that touches the same files as the first one wants its own worktree for the same reason two people want two copies of a document before editing it. Sharing one folder means the second run reads what the first one is halfway through changing.
With a worktree, the second run gets the branch it should have started from, and the first one keeps working in the copy it already has.
Create one from the scope menu with Create Git worktree. The dialog asks for a display name, the branch to fork from, and whether to run setup, and it warns you when the source checkout has uncommitted changes, because those changes will not be in the new worktree.
Setup and environment files, per scope
A worktree starts as a checkout with nothing installed. Setup commands are how it becomes a working copy, and each worktree keeps the commands it was created with.
When you create a worktree you list the commands it needs, in order. They run one at a time with the new checkout as their working directory. If one fails, you choose between retrying from the failed command and continuing without setup.
Environment files are handled at the same moment. The app finds the environment files the project keeps untracked at its root and carries them into the new checkout. Copy is the default, and a copy never overwrites a file that is already there. Symlink points the new checkout at the original files instead, which ties the two folders together.
Re-running setup is offered from the scope menu whenever the recorded run no longer describes the checkout it produced.
Branch and folder names
A managed worktree gets a branch whose name starts with cio/, followed by a version of the scope's name with spaces and punctuation turned into hyphens and the length kept reasonable.
The folder is named the same way, inside the app's own directory rather than inside your project. Two scopes with the same name get numbered suffixes, so the second one is a distinct branch and a distinct folder rather than a collision.
Renaming a scope changes only the name you see. Its branch and folder stay as they were, which keeps its history and any remote you have already pushed to intact.
Health and repair
A worktree is a real directory with a registration in Git, and either of those can change outside the app. A checkout can be deleted, moved, locked, left on another branch, or left behind in Git's records after a crash.
The app checks a scope's health when you enter the project, switch to it, open its Git panel or its actions menu, and again whenever an operation in it fails. When something is wrong, the scope shows the cause and the fix beside a Repair worktree action, and it refuses to run instead of quietly falling back to the project folder.
Repair does what the fault needs: it unlocks the checkout, prunes a stale record and re-creates the checkout from its branch, moves a relocated checkout back, or relinks a directory Git has lost track of.
A checkout restored from its branch contains only what was committed to that branch, so work that was never committed is gone. Environment files are carried in again and setup is marked out of date, which is why the scope offers Re-run setup afterwards.
Asking before anything is removed
Every destructive action starts with a dialog that states what will be lost. A worktree removal lists uncommitted changes, commits that are not on any remote, and agent processes still running in that scope, and it asks for a second, explicit confirmation before it goes ahead.
Detach worktree removes the checkout and returns the scope to the project folder. The scope, its threads, and its branch all stay.
Delete scope removes the scope, its worktree, and its branch. The dialog also asks what happens to the threads: they return to the Default scope, or they are deleted with it. The removal runs as a job in the dock, so you can keep working while it finishes.
Archive and Restore are the quiet pair. Archiving hides a scope without touching its checkout, branch, or threads.
Merging back
Merge into project brings the worktree's branch into the Default scope. You choose whether the scope stays, whether it is deleted after the merge, or whether it is deleted while its threads move into the target scope.
A conflict stops the merge and deletes nothing. You are handed to the Git panel with the conflicted files, and the worktree is left whole.
When to use a scope instead of the project root
Open a scope of your own when a second run would touch the same files as the run you already have going, when the work is an experiment you may throw away, or when it needs its own install and environment to be tested in.
Stay in the Default scope when the work is the one thing you are doing, or when the change is small enough that a second checkout would only add a merge at the end. One run in one folder needs no isolation.