Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Emanuele-web04/synara/llms.txt

Use this file to discover all available pages before exploring further.

Not every provider is equally good at every part of the work. You might start a planning conversation with Claude Code, let it draft an architecture and produce a detailed task breakdown, and then hand that context to Codex or OpenCode to do the actual file edits. Provider handoff makes this transition explicit and lossless — the receiving provider gets the full message history and can resume where the previous one stopped.

​
What provider handoff is and why it matters

A handoff creates a new thread that is linked to the original. The new thread carries a copy of every message from the source thread, marked with source: "handoff-import" so the UI can distinguish imported history from messages the user typed directly in the new session. The link between source and new thread is recorded on the thread itself: 
// From orchestration.ts
export const ThreadHandoff = Schema.Struct({
  sourceThreadId: ThreadId,
  sourceProvider: ProviderKind,
  importedAt: IsoDateTime,
  bootstrapStatus: ThreadHandoffBootstrapStatus,
});
export type ThreadHandoff = typeof ThreadHandoff.Type;

export const ThreadHandoffBootstrapStatus = Schema.Literals(["pending", "completed"]);
bootstrapStatus starts as "pending" while the new provider session is initialising and transitions to "completed" once the context has been delivered to the provider process.

​
How context is transferred

Synara packages the thread’s conversation as a list of ThreadHandoffImportedMessage entries: 
export const ThreadHandoffImportedMessage = Schema.Struct({
  messageId: MessageId,
  role: Schema.Literals(["user", "assistant"]),
  text: Schema.String,
  attachments: Schema.optional(Schema.Array(ChatAttachment)),
  createdAt: IsoDateTime,
  updatedAt: IsoDateTime,
});
These messages are written to the new thread before the first turn is dispatched. Because they are stored locally in Synara’s SQLite event store, the context transfer is instant — no network round-trip to a cloud service is involved. For providers that support a native resume cursor (a provider-specific opaque token that lets the provider process restore its own internal context), Synara can pass sourceResumeCursor through ProviderForkThreadInput: 
// From provider.ts
export const ProviderForkThreadInput = Schema.Struct({
  sourceThreadId: ThreadId,
  threadId: ThreadId,
  sourceResumeCursor: Schema.optional(Schema.Unknown),
  cwd: Schema.optional(TrimmedNonEmptyString),
  modelSelection: Schema.optional(ModelSelection),
  providerOptions: Schema.optional(ProviderStartOptions),
  runtimeMode: RuntimeMode,
});
export type ProviderForkThreadInput = typeof ProviderForkThreadInput.Type;
The resumeCursor is stored on ProviderSession and updated after each turn: 
export const ProviderSession = Schema.Struct({
  provider: ProviderKind,
  status: ProviderSessionStatus,
  runtimeMode: RuntimeMode,
  cwd: Schema.optional(TrimmedNonEmptyString),
  model: Schema.optional(TrimmedNonEmptyString),
  threadId: ThreadId,
  resumeCursor: Schema.optional(Schema.Unknown),
  // ...
});

​
Steps to hand off a thread in the UI

1

Open the thread you want to hand off

Navigate to the thread in the sidebar or Kanban view. The thread does not need to be idle — you can initiate a handoff while it is running and the current turn will be interrupted first.
2

Open the Provider menu

Click the provider badge in the thread header (the pill showing the current model name). This opens the provider and model picker.
3

Select a new provider and model

Choose a different provider from the list, for example switching from claudeAgent to codex. You can also change the model at the same time.
4

Confirm the handoff

Click Hand off. Synara creates a new thread linked to the current one and imports the full message history. The original thread is left intact in read-only form so you can refer back to it.
5

Continue in the new thread

The new thread opens with the imported messages visible. Send your next message to the new provider; it sees the full history and can continue the work.

​
Forking vs handing off

Synara distinguishes two ways to branch from an existing thread:

Fork

Creates a new sibling thread from the current conversation up to a chosen point. The original thread keeps running. Both threads share the same history up to the fork point, then diverge. Use fork when you want to explore a different approach in parallel without abandoning the original path. The new thread records forkSourceThreadId linking it back to the original.

Handoff

Transfers the conversation to a new provider. The original thread is retired and the new one continues the work. Use handoff when you have finished the planning or design phase with one model and want a different model to handle the implementation. The new thread records a ThreadHandoff with the sourceThreadId and sourceProvider.
Both operations import messages with a distinct source marker so the UI can display them differently from messages the user typed directly: 
export const OrchestrationMessageSource = Schema.Literals([
  "native",
  "handoff-import",
  "fork-import",
]);

​
Limitations

Not all providers support resuming from another provider’s checkpoint. The resumeCursor field is provider-specific and opaque. A Claude Code cursor passed to Codex will be ignored — Codex will bootstrap from the plain-text message history instead. The conversation context is still transferred via the imported messages; only the provider-internal state (tool call history, token offsets, etc.) cannot be bridged across provider types.
  • Attachments: Image attachments from the source thread are included in the imported message list if the receiving provider supports images. Providers that do not support images will skip those attachment entries.
  • Skills and mentions: Skill references attached to individual messages in the source thread are included in the imported messages. Whether the new provider can act on them depends on the provider’s skill support.
  • Approval policies: The new thread inherits the runtimeMode you select at handoff time. It does not automatically inherit the source thread’s runtime mode.

​
Related

Build docs developers (and LLMs) love

Get started for freeTalk to us