Workspaces, projects, and worktrees
A workspace is a top-level context. It holds one or more projects and carries its own chrome and accent colors, agent defaults, and workflow settings.
The app opens Git repositories and plain project folders inside a workspace. For Git repositories, it uses git worktrees to isolate task branches; each worktree gets a working directory that shares the repository’s history.
Plain folders open as non-Git projects for local files, terminals, and agent sessions. They do not support branch-backed worktrees, target-branch comparisons, or Git review until you initialize Git.
Git worktrees
Section titled “Git worktrees”Git worktrees let one repository check out multiple working directories at once. The app uses that feature for task branches.
For a plain folder, the app keeps you in that folder rather than creating a worktree. Initialize Git first when you need isolated task directories.
Workspace context
Section titled “Workspace context”Workspaces hold durable context such as personal work, company work, a client, or a group of related repositories. Workspace-level settings include:
- Chrome and accent colors for the active context.
- Agent provider and model defaults.
- Per-workspace provider profile overrides.
- Multiple projects grouped under one workspace.
For theme and layout controls, see Themes and appearance and Layout, sidebars, and PiP.
Branches
Section titled “Branches”By default, the app creates a temporary worktree immediately and names its branch from the first meaningful agent prompt. This keeps ⌘N and the sidebar + action fast: start the task first, then let the app apply a descriptive branch name.
Turn off Automatic worktree naming under Settings → Worktrees if you prefer to name branches yourself. ⌘⇧N also opens the creation flow when you want to choose a branch or pull request before opening the worktree.
Example branch names:
feat/docs-systemfix/api-download-redirectrefactor/sidebar-stateTarget branch
Section titled “Target branch”The target branch is the branch the app compares against for status, review, and pull-request creation. A project can set both a Default branch for new worktrees and a Default target branch for comparisons.
When no target is configured, the app detects one from the remote default branch (origin/HEAD), then origin/main, origin/master, or the local main or master. Release branches work, too.
Set the target to the branch into which the work will merge. Existing worktrees keep their current target when you change the project default. See Branches and targets for switching, retargeting, and naming details.
Task directories
Section titled “Task directories”Each Git-backed task worktree owns a directory. Terminals and agent sessions opened from that worktree run there.
Cleanup
Section titled “Cleanup”Remove a task worktree after its branch merges, you abandon it, or you no longer need it. Durable workspaces, such as work or personal contexts, persist after you remove their task worktrees.
Before cleanup
Section titled “Before cleanup”Before you delete a task worktree, decide what to do with its work:
- Commit and push changes you want to keep.
- Save notes or prompts you want to keep available.
- Confirm the branch has merged if that was the goal.
- Confirm you do not need the provider’s session history for follow-up work.
To keep the code, preserve it through Git before you delete the worktree.
If you delete a worktree by mistake, stop cleanup and try the recovery steps in Troubleshooting.
What cleanup removes
Section titled “What cleanup removes”Cleanup removes the worktree and clears the app’s local runtime state for that task branch. It can also delete the local branch and local remote-tracking references, depending on your settings. Removing a remote-tracking reference does not delete the branch from GitHub, GitLab, or another remote.
The app clears related caches so stale diffs, pull request state, setup markers, and session metadata disappear with the worktree.
Cleanup hooks
Section titled “Cleanup hooks”Projects can define pre-cleanup and post-cleanup commands in user-owned app project settings. Repository config can define teardown commands. This separation prevents a checked-in file from silently adding the guards that run automatically before or after deletion.
If a pre-cleanup hook fails, the app keeps the worktree intact.
The app reports post-cleanup hook failures after it removes the worktree.
Branch cleanup settings
Section titled “Branch cleanup settings”Branch cleanup is configurable under Settings → Worktrees. Local task-branch deletion is enabled by default. Local remote-tracking-reference deletion is disabled by default. Remote forge branches are outside these cleanup settings.
See Project config and scripts for script order, ownership, and examples.