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.

A thread is the core unit of work in Synara. It pairs a single conversation history with a live provider session, a model selection, and an optional Git worktree — everything the agent needs to read, edit, and commit code in one coherent context. Because every thread is independent, you can run a bugfix thread and a feature thread against the same repository at the same time without the two agents ever reading each other’s in-progress changes.

​
What a thread contains

Every OrchestrationThread carries: 
export const OrchestrationThread = Schema.Struct({
  id: ThreadId,
  projectId: ProjectId,
  title: TrimmedNonEmptyString,
  modelSelection: ModelSelection,       // provider + model
  runtimeMode: RuntimeMode,             // "approval-required" | "full-access"
  interactionMode: ProviderInteractionMode, // "default" | "plan"
  envMode: ThreadEnvironmentMode,       // "local" | "worktree"
  branch: Schema.NullOr(TrimmedNonEmptyString),
  worktreePath: Schema.NullOr(TrimmedNonEmptyString),
  parentThreadId: Schema.NullOr(ThreadId),
  forkSourceThreadId: Schema.NullOr(ThreadId),
  isPinned: Schema.Boolean,
  handoff: Schema.NullOr(ThreadHandoff),
  messages: Schema.Array(OrchestrationMessage),
  checkpoints: Schema.Array(OrchestrationCheckpointSummary),
  session: Schema.NullOr(OrchestrationSession),
  // ...markers, pinned messages, notes, proposed plans
});
The conversation history (messages), the live session status (session), and the Git state (branch, worktreePath) are all first-class fields — Synara keeps them synchronized as the agent works.

​
Thread environment mode

ThreadEnvironmentMode decides where the provider’s working directory is rooted: 
export const ThreadEnvironmentMode = Schema.Literals(["local", "worktree"]);
export type ThreadEnvironmentMode = typeof ThreadEnvironmentMode.Type;
ModeBehaviour
localThe provider runs directly inside the project’s main working tree. Changes land on whatever branch is currently checked out. Use this for quick explorations or single-branch work.
worktreeSynara creates a dedicated Git worktree for this thread — a separate directory linked to its own branch. The provider’s cwd is the worktree root. Changes are completely isolated from your main branch and from every other thread’s worktree.
The server default is controlled by settings.defaultThreadEnvMode. Set it to "worktree" to make every new thread isolated by default.

​
Git worktree isolation

When a thread uses envMode: "worktree", Synara calls git worktree add under the hood and sets the thread’s worktreePath and branch fields. The worktree lives at: 
~/.synara/worktrees/<thread-id>/
Each worktree is a full checkout of the repository on its own branch. Git tracks the mapping between the main repo and each worktree through standard .git/worktrees/ pointer files — Synara reads and parses those to keep worktreePath accurate across restarts.
Two threads can target the same repository at the same time. Because each thread has its own branch and worktree directory, git status, staged changes, and uncommitted edits are completely isolated. There is no risk of one agent overwriting another’s work-in-progress.
The associatedWorktreePath, associatedWorktreeBranch, and associatedWorktreeRef fields let a thread record a secondary worktree link — useful when a parent thread has already set up a branch that a child subagent thread should inherit.

​
Thread lifecycle

Threads move through a series of states as work progresses. The session layer tracks this through OrchestrationSessionStatus: 
export const OrchestrationSessionStatus = Schema.Literals([
  "idle",
  "starting",
  "running",
  "ready",
  "interrupted",
  "stopped",
  "error",
]);
A typical thread lifecycle looks like this:
  1. Creation — thread.create command registers the thread with its modelSelection, envMode, and initial branch. If envMode is "worktree", Synara provisions the Git worktree before the session starts.
  2. Running — A thread.turn.start command sends a user message. The session status moves to starting then running. The provider processes the prompt, edits files, and streams assistant output back.
  3. Checkpoint — When a turn completes, Synara records a OrchestrationCheckpointSummary (a Git snapshot) so you can revert to any prior turn count.
  4. Handoff — A thread can be handed off to a different provider via thread.handoff.create. The conversation history is imported into the new thread so the next provider picks up with full context.
  5. Fork — A thread can be forked to explore an alternative approach without discarding the original. The fork starts from the same conversation history and optionally the same Git commit.

​
Handoff: passing context to another provider

ThreadHandoff records the lineage when a thread’s work is transferred to a new provider session: 
export const ThreadHandoff = Schema.Struct({
  sourceThreadId: ThreadId,
  sourceProvider: ProviderKind,
  importedAt: IsoDateTime,
  bootstrapStatus: ThreadHandoffBootstrapStatus, // "pending" | "completed"
});
During a handoff, the messages from the source thread are imported into the new thread via ThreadHandoffImportedMessage records, giving the incoming provider the full conversation context. bootstrapStatus tracks whether the import has finished loading before the new session begins.

​
Forking a thread

Forking creates a divergent copy of a thread’s conversation and Git state. The ProviderForkThreadInput contract defines what the fork operation needs: 
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,
});
The sourceResumeCursor is a provider-specific opaque value that lets the new session resume from a particular point in the conversation rather than re-sending the full history. Not all providers support native forking; when a provider adapter omits forkThread, Synara falls back to conversation-history-only forking (importing messages without a cursor). Forked threads record their origin in forkSourceThreadId on the OrchestrationThread, so the UI can show the fork lineage.

​
Markers, pinning, and notes

Synara gives you lightweight annotation tools to stay organized across long-running threads: Thread markers let you highlight a span of text inside any assistant message and tag it with a color, style, and optional label: 
export const ThreadMarker = Schema.Struct({
  id: ThreadMarkerId,
  messageId: MessageId,
  startOffset: NonNegativeInt,
  endOffset: NonNegativeInt,
  selectedText: TrimmedNonEmptyString,  // up to 4,000 chars
  style: ThreadMarkerStyle,             // "highlight" | "underline"
  color: ThreadMarkerColor,             // "yellow" | "blue" | "green" | "pink"
  label: Schema.NullOr(ThreadMarkerLabel),
  done: Schema.Boolean,
});
Up to 200 markers per thread. Each marker has a done toggle so you can track which insights you’ve acted on. Pinned messages surface important messages in a sidebar checklist. Up to 100 messages can be pinned per thread, each with an optional label override and a done state. Thread notes are a free-text scratchpad attached to the thread — up to 16,384 characters of markdown you can use for running observations, acceptance criteria, or anything else. Thread pinning (isPinned: true) promotes a thread to the top of the project sidebar so your most active threads are always in view. Up to 3 projects can be pinned across the workspace.

​
Practical example: parallel feature and bugfix threads

Say you’re working on a repository with a long-running feature branch and a time-sensitive bug report at the same time.
  1. Feature thread — Create a thread with envMode: "worktree". Synara checks out feat/new-dashboard into ~/.synara/worktrees/<thread-a>/. The Claude agent works there, committing incrementally.
  2. Bugfix thread — Create a second thread, also with envMode: "worktree". Synara checks out fix/auth-race-condition into ~/.synara/worktrees/<thread-b>/. The Codex agent works in complete isolation.
  3. Both threads run simultaneously. The feature agent and the bugfix agent each see a clean checkout of the branch they were given. Neither agent’s uncommitted changes, staged files, or partial edits are visible to the other.
  4. When the bugfix is ready, you review the diff in Synara, commit, push, and open a PR — all without leaving the app and without disturbing the still-running feature thread.

Running agents in parallel

How to set up and manage multiple concurrent threads across projects.

Git workflow with worktrees

Branching, diffing, committing, and opening pull requests from inside Synara.

Provider handoffs

How to hand off a thread’s context from one provider to another mid-conversation.

Providers overview

Install and authorize each supported provider before starting a thread.

Build docs developers (and LLMs) love

Get started for freeTalk to us