Worktrees

A Git worktree gives a thread a separate working directory and checked-out branch while sharing the repository’s object database and history. In Tejus, it is the standard isolation boundary for concurrent threads that may edit the same repository.

Local or worktree

A separate conversation is not filesystem isolation. Two threads using the same local checkout can overwrite files, invalidate tests, and confuse Git state.

Choose the environment in the Work in menu below the composer (also available in the chat header's Environment panel). Set the default for new threads in Settings → General → Core defaults → New threads (Local or New worktree).

Where worktrees live

Tejus creates managed worktrees under your Tejus data folder:

%USERPROFILE%\.tejus\worktrees\<repository-name>\<folder>

The folder is named after the branch the worktree was created with, with slashes turned into dashes (for example tejus-1a2b3c4d). It keeps that name if the branch is renamed later. If you moved the data folder with the SYNARA_HOME environment variable, worktrees live in its worktrees subfolder instead. Branches that Tejus creates for worktrees use the tejus/ prefix.

Before creating the worktree

Inspect the source checkout:

git status --short
git branch --show-current
git log -1 --oneline

Decide:

• Which repository and checkout are the source
• Which base branch the work should start from
• Whether current local changes should come along (see below)
• Which thread owns the resulting branch
• How the branch will be integrated or discarded

Do not start several worktrees from an accidental or poorly understood base state.

How a new worktree thread starts

How thread ownership works

A worktree-backed thread owns:

• Its working directory
• Its checked-out branch
• Its provider session
• Its terminal processes
• Its file changes and diff
• Its review and delivery lifecycle

Terminals, file tools, the Editor view, provider operations, and Git actions for that thread run inside the worktree rather than the primary checkout.

Move a thread between local and a worktree

A thread that already has messages can change environment without starting over. Open Work in:

• Hand off to new worktree asks for a worktree name (for example tejus/feature-name), creates the worktree from the current branch, stops the active session, and moves the thread into it. Uncommitted changes from the local checkout are carried over. If the thread already has a worktree from an earlier handoff, Tejus moves it back into that worktree instead of asking for a name.
• Hand off to local moves the thread back to the main local checkout and carries the worktree’s uncommitted changes over. If the local checkout had its own uncommitted changes, Tejus restores them as well.

If Git reports conflicts while applying the moved changes, Tejus rolls the handoff back so the thread stays where it was, and keeps the stash entry for recovery. A success toast tells you what was moved; read it before continuing.

Working inside the thread

Run repository commands from the thread’s terminal so they use the correct working directory:

pwd
git status --short
git branch --show-current
git diff --check

Before trusting a test result, confirm that the terminal belongs to the same worktree as the diff you are reviewing.

Avoid editing the same branch from another checkout while the thread is active.

Moving work between environments

Use Git history rather than manual file copying.

Common integration paths:

• Merge the worktree branch
• Rebase it onto a newer base
• Cherry-pick reviewed commits
• Open a pull request from the branch
• Recreate a small change manually when the branch contains too much unrelated work

Manual copying loses authorship, branch ancestry, and conflict information. It can also overwrite newer work without Git noticing the intended relationship.

Updating a long-running worktree

When the base branch moves:

1. Stop or finish the active provider turn.
2. Commit or preserve the worktree’s current state.
3. Fetch the latest refs.
4. Rebase or merge deliberately.
5. Resolve conflicts with one owner.
6. Re-run focused and broad verification.

Do not rewrite the branch underneath a running provider session. The provider may continue acting on stale file and commit assumptions.

Reviewing the result

Before integrating:

git status --short
git diff --check
git diff --stat
git log --oneline --decorate --max-count=10

Then inspect the exact range against the intended base:

git diff <base-ref>...HEAD
git log <base-ref>..HEAD --oneline

Confirm that:

• Only intended files changed
• The branch starts from the expected base
• No temporary or generated artifacts remain
• Tests were run from this worktree
• The commits are understandable and independently reviewable

Cleanup and retention

Tejus manages worktree cleanup conservatively:

• Active threads keep their worktrees.
• Archived threads: the worktrees of the 15 most recently archived threads are kept. Older ones are removed automatically.
• Deleted threads: their worktrees are removed automatically.
• Automatic removal only happens when the worktree has no uncommitted changes; a dirty worktree is left in place. Tejus saves a recovery snapshot before removing it, and keeps snapshots for 30 days.
• The branch is kept, unless it still has its temporary tejus/ name (the first message never got a descriptive branch name); automatic cleanup deletes such temporary branches with the worktree. Push or rename branches you want to keep.
• Worktrees that no thread owns are never removed automatically.

Settings → General → Core defaults → Delete worktree on archive (off by default) removes a clean worktree after Archive’s Undo period, but only if the thread has stopped and no other thread uses it. Its branch remains available for recovery.

To clean up by hand, open Settings → Managed worktrees (in the Coding group). It lists the worktrees Tejus created, grouped by repository, with the conversations linked to each. Delete asks for confirmation; if archived conversations are linked, they are deleted first.

Before archiving or removing a worktree-backed thread:

1. Review changed and untracked files.
2. Commit changes you intend to keep.
3. Push the branch when it must survive outside the machine.
4. Stop terminal processes and dev servers that depend on the directory (the Background tasks panel lists them).
5. Confirm the branch is merged, preserved, or intentionally disposable.
6. Archive or delete the thread only after that decision is explicit.

Never assume the conversation transcript preserves uncommitted files.

Recovery cases

The worktree contains valuable uncommitted work

Stop cleanup. Inspect git status, create a commit or patch, and push the branch before removing anything.

The branch was deleted remotely

The local worktree and commits may still exist. Inspect local refs and reflogs before creating replacement work.

Tests pass in one checkout but fail in the worktree

Compare environment variables, installed dependencies, generated files, ports, and the exact commit. Passing checks from another checkout do not verify this branch.

Two worktrees now modify the same files

Choose one integration owner. Merge or rebase one branch at a time and resolve conflicts with the full combined behavior in view.

A process keeps the directory busy

On Windows, an open terminal, dev server, watcher, or editor can lock files in the worktree. Stop those processes before cleanup. Do not force-delete an active environment simply to remove a filesystem error.

Worktree checklist

• Source checkout and base branch are understood
• One thread owns the worktree and branch
• Concurrent writers use separate worktrees
• Tests run inside the correct environment
• Changes are committed or intentionally discarded
• Important branches are pushed
• Integration is reviewed against the intended base
• No dependent process remains before cleanup