Provider handoffs
Continue the same Tejus thread and working environment with another provider.
A provider handoff changes which provider continues a Tejus thread. Use it when the objective and environment should remain the same but another provider is better suited to the next phase or useful as an independent second opinion.
This page covers switching providers. To move a thread between the local checkout and a worktree, see Worktrees.
Handoff or new thread
| Choose | When |
|---|---|
| Handoff | Another provider should continue the same objective, branch, files, and thread history |
| New thread | Both providers should work independently, produce separate diffs, or use different environments |
| Review-only thread | A second provider should inspect a completed diff without inheriting ownership of the implementation |
A handoff is continuation, not parallelism. Do not leave two providers actively editing the same environment.
Same thread or new thread
The Hand off thread button in the chat header (also Handoff in the thread’s right-click menu in the sidebar) lists each available provider under two destinations:
- Continue in this thread keeps the same thread: its ID, visible history, project, and worktree. The receiving provider starts a new session right away, and the timeline records a handoff row (“Handed off from … to …”) along with the context transferred to the new provider. Earlier messages stay attributed to the provider that wrote them, and the receiving provider’s next turn includes that context. If the receiving provider cannot start, the thread stays on the original provider and the timeline records the failure instead.
- Continue in a new thread creates a separate thread with a copy of the transcript on the chosen provider, leaving the original thread untouched. The new thread carries the same runtime and interaction mode.
You can also pick another provider in the composer’s model picker. Choosing it changes nothing until you send: the next message first hands the thread off in place (as with Continue in this thread) and is then sent to the new provider. If the new provider cannot start, the message goes back into the composer and the thread keeps its original provider.
A handoff is refused while a turn is running or while an approval or question is waiting for you. Wait for the turn to finish, answer any pending request, then try again.
Switching between two accounts of the same provider always creates a new thread.
Good reasons to hand off
- A different provider has a capability better suited to the next phase
- The first provider completed implementation and another should review it critically
- The current provider is unavailable or rate-limited
- The work needs a fresh approach without losing its working state
- You want to move from planning to implementation with a different provider
- You want one provider to diagnose a failure produced by another
Do not hand off merely because the first attempt was confusing. First make the environment and objective understandable to the receiver.
Before handing off
Stop at a stable boundary
Let the active turn finish, interrupt it, or otherwise confirm that it is no longer changing the environment. Check the Background tasks panel for commands or subagents that are still running.
Review the current state
Inspect pending approvals, unanswered questions, changed files, untracked files, test results, and running terminal processes.
Create a checkpoint
For risky or substantial work, commit a checkpoint before changing providers:
git status --short
git diff --check
git add <reviewed-files>
git commit -m "checkpoint: preserve work before provider handoff"Do not commit secrets, temporary files, or changes you have not reviewed merely to make the tree clean.
State the next role explicitly
Tell the receiving provider whether it should investigate, review, continue implementation, repair failures, or verify the result.
What Tejus preserves
The thread remains associated with:
- Its project
- Local checkout or managed worktree
- Branch and file changes
- The Tejus transcript and thread metadata
- Git and terminal surfaces belonging to the thread
Tejus passes the earlier conversation to the receiving provider as context. The receiving provider should still inspect the actual repository state rather than trusting the transcript alone.
What does not transfer
Provider-native state does not become portable merely because the Tejus thread continues.
The receiving provider does not inherit another provider’s:
- Native session identifier
- Hidden context or reasoning
- Provider-specific tools
- Permission implementation
- Model-specific capabilities
- Native subagents or background tasks
- Exact compaction or resume behavior
The new provider starts its own session according to its own capabilities and account.
Write the handoff instruction
A good implementation handoff:
Continue the same objective from the current worktree.
First inspect git status, the complete diff, and the latest test output.
Do not assume the previous provider’s summary is correct.
Preserve the existing public API and do not widen scope.
Fix only confirmed issues, run the listed verification, and report the exact results.A good review handoff:
Review the current branch without editing first.
Check correctness, lifecycle behavior, security, error handling, and test coverage.
Verify claims against the source and diff.
List findings with file references before proposing changes.
Do not rewrite code unless I explicitly continue after the review.Verification after handoff
When the receiving provider finishes:
- Compare the current diff with the checkpoint or handoff boundary.
- Identify which provider introduced each additional change.
- Re-run the relevant checks from the thread’s environment.
- Confirm the objective is still unchanged.
- Review any new permissions, configuration, or generated artifacts.
- Commit only the combined result you understand.
A second provider does not automatically make a result independent. Both may repeat the same assumption unless the review objective asks for evidence.
Failure cases
The receiver cannot understand the current state
Stop implementation. Ask it to summarize the repository, diff, failing checks, and unresolved questions first. Narrow the objective before continuing.
The receiver wants to replace the approach entirely
Require a written comparison and preserve the checkpoint. A rewrite should be a deliberate new decision, not an accidental consequence of switching models.
The handoff is refused
A turn is still running, or an approval or question is pending. Interrupt or wait, answer the request, and try again. Do not permit concurrent edits in one environment.
The receiving provider could not start
The timeline shows the failure and the thread stays on its original provider. Check the provider’s status and sign-in in Settings → Agent providers, then retry.
Provider capabilities differ
Adjust the workflow. A model option, tool, slash command, or Plan mode available to one provider may not exist for the receiver.
The handoff introduces unrelated changes
Separate or revert them. The handoff does not expand the original ownership boundary.
Handoff checklist
- The active turn is stopped or complete
- The environment and diff were reviewed
- Valuable work is checkpointed
- The next provider has one explicit role
- The objective and constraints remain unchanged
- Provider-native state is not assumed to transfer
- Verification runs after the receiving provider finishes
- Only reviewed combined changes are committed
The thread still owns one body of work. Create a separate thread and worktree when both providers should proceed independently.