Isolate a task with a worktree

A worktree is another working directory for the same Git repository. Use one to let AI try changes while keeping your work in the original directory. An ordinary local conversation uses the original directory; a new worktree task gets its own directory and branch.

1. Start a worktree conversation#

1. Create a new conversation in the intended project and check its path.
2. Enable Worktree on the right of the project and branch row beside the composer (Figure 1).
3. Click Start from. Usually, keep Current branch; choose Other branches… for a different starting version. Select Include uncommitted local changes only when you want to continue edits that have not been committed in the original directory.
4. Send the first message. Onevium now creates the directory and a onevium/… branch, prepares the workspace, and starts the task.

Enlarge imageFigure 1: Enable Worktree on the right, then choose a starting point on the left. Real 1.2.4 development components with sample project data; no task has been sent.

For a first try, send:

Check the working directory and Git branch.
List the included repositories.
Tell me which copy this task will edit.
Do not edit any files yet.

Continuing this conversation reuses its worktree; each message does not create another one. Onevium remembers the project's Worktree setting, so check it when starting your next conversation.

2. Include repositories inside the project#

Suppose your project folder contains two independent Git repositories: app and website.

1. Enable Worktree, then click Start from or Choose repositories.
2. Under Repositories, select the ones this task needs (Figure 2). Select only website for a website change, or both for work across the application and website.
3. Under Start point, click each repository to choose its starting branch. Including uncommitted changes is also a separate choice for each repository.

Enlarge imageFigure 2: Select repositories above, then set their starting points below. The same development UI demo uses sample app and website repositories.

Onevium creates a worktree for each selected repository, preserving its relative location in the new directory. The repositories remain independent: commit and merge each separately.

Independent nested repositories are different from Git submodules, which are not checked out automatically. If a repository you need is missing from the list, open that repository's directory as a project directly.

3. Check the result and keep your changes#

Once preparation finishes, the conversation shows Worktree · branch name. Verify the actual path and branch in the conversation before editing. Use Files, terminal, and Review to inspect file changes.

Finishing the task does not merge changes into the original branch. Review the diff and run the project's checks, then explicitly ask the assistant to commit and merge into your chosen target branch. Handle each repository separately.

To compare two approaches, start two separate worktree conversations. Continuing or adding a conversation inside an existing worktree shares that copy of the files. Split view does not create additional isolation.

4. Clean up and restore#

1. Open Settings → Worktrees → General. Find the target under Managed worktrees, make sure your work is kept, then click Delete (Figure 3). Automatic cleanup only removes older worktrees without unsaved changes.

Enlarge imageFigure 3: Click Delete beside the target worktree. Real development UI components with sample project data and paths.

2. Read the confirmation dialog (Figure 4). If there are unsaved changes, confirm that a snapshot can be created. If it cannot, cancel and keep your files first. Manual deletion also archives linked conversations.

Enlarge imageFigure 4: Check the snapshot and archiving information before deleting. This demo only opens the confirmation dialog; nothing was deleted.

Git-ignored local configuration, such as .env.local, is not included in snapshots; keep it separately.

3. To recover the worktree, open its original conversation, click Restore worktree (Figure 5), and wait for setup to finish. If the conversation is archived, first go to Settings → Archived sessions and click Restore, then open it.

Enlarge imageFigure 5: Click Restore worktree in the original conversation. The same development UI demo uses a sample path.

Deleting or restoring a worktree does not merge its code.

Troubleshooting#