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.

Synara is built around the idea that meaningful coding work rarely fits into a single conversation. You might be drafting a new feature, hunting a regression, and reviewing a colleague’s pull request at the same time — all on the same codebase. Rather than context-switching between windows or serializing that work, Synara lets you run each task as an independent thread with its own provider session, its own branch, and optionally its own Git worktree.

​
What parallel agents means in Synara

Each thread in a project maps to exactly one provider session at a time. Sessions are not shared. When you open two threads simultaneously — say, one with Claude Code and one with Codex — each agent process runs independently with its own working directory, its own conversation history, and its own file system state. Changes made by one agent are invisible to the other until you explicitly merge them.
Each active provider session spawns its own subprocess. Running three or four parallel sessions is practical on most developer machines; running dozens at once will compete for CPU and memory. Consider keeping intensive agents in worktree mode so their file I/O stays physically separated.

​
Thread environment modes

Every thread has an envMode that controls where the agent reads and writes files. 
export const ThreadEnvironmentMode = Schema.Literals(["local", "worktree"]);
export type ThreadEnvironmentMode = typeof ThreadEnvironmentMode.Type;
ModeWhat it means
"local"The agent works directly inside the project’s working directory. All threads in local mode share the same branch checkout.
"worktree"Synara creates a dedicated Git worktree at a separate path on disk. The agent gets its own branch checkout and cannot disturb other threads.
When to use "local": Quick questions, documentation edits, or sessions where you want the agent to see your current uncommitted work-in-progress. When to use "worktree": Any work that writes to files — feature development, bug fixes, refactors — especially when you are running multiple agents in parallel. Worktrees make it physically impossible for two agents to overwrite each other’s changes because each one lives in a separate directory.

​
How each thread gets its own provider session

When a thread starts a turn, Synara’s orchestration layer spins up a provider session bound to that thread’s ID. The session carries:
  • modelSelection — the specific provider and model for this thread (e.g., claudeAgent with your chosen model)
  • envMode — "local" or "worktree"
  • branch and worktreePath — the Git branch and filesystem path the agent operates in
  • runtimeMode — "full-access" or "approval-required", controlling whether the agent can execute commands without asking
// From orchestration.ts
export const OrchestrationThread = Schema.Struct({
  id: ThreadId,
  projectId: ProjectId,
  title: TrimmedNonEmptyString,
  modelSelection: ModelSelection,
  runtimeMode: RuntimeMode,
  envMode: Schema.optional(ThreadEnvironmentMode).pipe(
    Schema.withDecodingDefault(() => "local")
  ),
  branch: Schema.NullOr(TrimmedNonEmptyString),
  worktreePath: Schema.NullOr(TrimmedNonEmptyString),
  // ...
});

​
A practical parallel workflow

1

Create a thread for your feature

Open your project, create a new thread, set envMode to worktree, and give it a descriptive name like “feat/user-auth”. Assign a provider such as Claude Code or Codex and describe the feature. The agent will work on a dedicated branch without touching your main checkout.
2

Create a second thread for your bug fix

Create another thread with envMode: worktree targeting a different branch, e.g. “fix/null-pointer-login”. This agent runs in a completely separate worktree directory. Both agents can run at the same time.
3

Create a review thread in local mode

Use a third thread in local mode to run /review against your uncommitted main-branch changes or against the base branch diff. Code review threads rarely need to write files, so local mode is fine.
4

Monitor all threads from Kanban view

Switch to the Kanban board to see all threads for the project at once. Each card shows the thread’s title, current session status (idle, running, interrupted, etc.), and latest agent activity. You can respond to approval requests or send follow-up messages to any thread without switching away.

​
Kanban view for managing multiple threads

The Kanban board is the primary view for parallel agent work. It renders one card per thread grouped by session status. Cards surface:
  • The thread title and the model assigned to it
  • The latest agent message or activity summary
  • Pending approval requests that need your input
  • Whether a proposed plan is waiting to be implemented
You can open any card to see the full conversation, send a new message, or hand the thread off to a different provider — all without disrupting the other agents still running.

​
Tips for working with parallel agents

Pin important threads

Set isPinned: true on threads you need to keep in quick reach. Pinned threads float to the top of the thread list and the Kanban board. Up to MAX_PINNED_PROJECTS = 3 projects can be pinned at the project level.

Name threads clearly

Thread titles are the only label visible across the Kanban, the sidebar, and notification toasts. Use names like “feat/search — indexing” rather than “New Thread 3” so you can glance at the board and know what each agent is working on.

Use worktrees for file-writing work

Any thread where the agent will create, edit, or delete files should run in worktree mode. This prevents accidental overwrites when two agents race to modify the same file.

Watch resource usage

Each active session runs a provider subprocess (e.g., claude, codex, or an OpenCode server). Idle threads don’t consume resources, but three or more actively running agents will. Interrupt agents that are blocked on slow tasks and let others run first.

​
Related

Build docs developers (and LLMs) love

Get started for freeTalk to us