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 doesn’t ship its own AI model. Instead, it wraps the AI coding agents you already have on your machine — tools like Claude Code, Codex, Gemini CLI, and others — and orchestrates them through a unified session layer. Each provider is one of those locally-installed CLIs or SDKs. Synara starts, monitors, and routes messages to each provider process on your behalf, so you can switch models, run multiple agents in parallel, and hand off context between providers without manually managing terminal sessions.

​
Provider kinds

Every session in Synara is backed by exactly one ProviderKind. The full list of supported providers is defined in the contracts layer: 
export const ProviderKind = Schema.Literals([
  "codex",
  "claudeAgent",
  "cursor",
  "gemini",
  "grok",
  "kilo",
  "opencode",
  "pi",
]);
export type ProviderKind = typeof ProviderKind.Type;

codex

OpenAI Codex CLI. Requires the codex binary on your PATH and a valid OpenAI authorization. Default provider when no other is specified.

claudeAgent

Anthropic Claude Code CLI. Requires the claude binary. Supports thinking tokens via maxThinkingTokens and custom launch args.

cursor

Cursor agent CLI (cursor-agent). Supports a configurable apiEndpoint for self-hosted or enterprise Cursor deployments.

gemini

Google Gemini CLI. Requires the gemini binary. Minimal additional configuration — drop in the binary and go.

grok

xAI Grok CLI. Requires the grok binary on your PATH. Configuration mirrors the Gemini provider shape.

kilo

Kilo Code agent. Supports optional serverUrl and serverPassword for connecting to a running Kilo server.

opencode

OpenCode agent. Supports serverUrl, serverPassword, and an experimentalWebSockets flag for real-time streaming.

pi

Pi agent. Requires the pi binary and optionally an agentDir pointing to your agent configuration directory.

​
Provider session lifecycle

When Synara starts a thread, it opens a provider session for that thread. The session progresses through a well-defined set of statuses: 
const ProviderSessionStatus = Schema.Literals([
  "connecting",
  "ready",
  "running",
  "error",
  "closed",
]);
StatusMeaning
connectingSynara is spawning the provider process and establishing the IPC channel.
readyThe session is live and waiting for a turn to be dispatched.
runningA turn is actively in flight — the provider is processing a prompt.
errorThe session encountered an unrecoverable error. lastError carries the diagnostic message.
closedThe session was stopped cleanly (user-requested or natural completion).
Sessions are attached to threads. A thread’s OrchestrationSession tracks the current status, the active activeTurnId, and any lastError so the UI always reflects the real provider state.

​
Approval policy

ProviderApprovalPolicy controls when Synara pauses and asks you to review an action before the provider proceeds: 
export const ProviderApprovalPolicy = Schema.Literals([
  "untrusted",
  "on-failure",
  "on-request",
  "never",
]);
export type ProviderApprovalPolicy = typeof ProviderApprovalPolicy.Type;

untrusted

Maximum friction. Every tool call is paused and shown to you for explicit approval before the provider can proceed. Use this when exploring an unfamiliar codebase or running a provider for the first time.

on-failure

Synara only interrupts when a tool call returns a non-zero exit code or otherwise fails. Successful operations run automatically.

on-request

The provider drives when it requests approval — Synara surfaces the request to you but does not add extra gates beyond what the provider natively asks for.

never

Fully autonomous. All provider actions are allowed without interruption. Equivalent to --dangerously-skip-permissions in many provider CLIs. Pair with a safe sandbox mode when using this.

​
Sandbox mode

ProviderSandboxMode constrains what the provider process is allowed to touch on disk: 
export const ProviderSandboxMode = Schema.Literals([
  "read-only",
  "workspace-write",
  "danger-full-access",
]);
export type ProviderSandboxMode = typeof ProviderSandboxMode.Type;
ModeAllowed operations
read-onlyThe provider can read files but cannot write, delete, or execute shell commands that modify state.
workspace-writeReads and writes are permitted within the project workspace root. Changes outside the worktree boundary are blocked.
danger-full-accessNo filesystem restrictions. The provider may read and write anywhere the OS user can. Use with caution.
danger-full-access gives the provider the same permissions as your user account. Only use it with providers and workflows you trust completely.

​
Runtime mode

RuntimeMode determines the base execution context the server is running in: 
export const RuntimeMode = Schema.Literals(["approval-required", "full-access"]);
export type RuntimeMode = typeof RuntimeMode.Type;
export const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
  • approval-required — mirrors the session into an interactive approval flow; the provider cannot proceed through tool calls without an explicit accept or acceptForSession decision from the user.
  • full-access — the default. The provider runs autonomously within the bounds of the configured ProviderSandboxMode.
RuntimeMode operates at the thread level and can be toggled mid-session via a thread.runtime-mode.set command without stopping the provider process.

​
Model selection

Each thread carries a ModelSelection that pins the provider and model for that conversation. Every provider kind has its own typed selection struct: 
// Example: Claude model selection
export const ClaudeModelSelection = Schema.Struct({
  provider: Schema.Literal("claudeAgent"),
  model: TrimmedNonEmptyString,
  options: Schema.optional(ClaudeModelOptions),
});

// The union type covers all providers
export const ModelSelection = Schema.Union([
  CodexModelSelection,
  ClaudeModelSelection,
  CursorModelSelection,
  GeminiModelSelection,
  GrokModelSelection,
  KiloModelSelection,
  OpenCodeModelSelection,
  PiModelSelection,
]);
export type ModelSelection = typeof ModelSelection.Type;
You can set a default ModelSelection at the project level (OrchestrationProject.defaultModelSelection) and override it per-thread or even per-turn via the ThreadTurnStartCommand.

​
Provider discovery

Synara scans each provider’s capabilities at runtime through a discovery layer. Before a session starts, the server queries what the provider can do — which skills it exposes, which models it can list, whether it supports plugin discovery, thread compaction, or turn steering. The ProviderComposerCapabilities shape captures these flags: 
export const ProviderComposerCapabilities = Schema.Struct({
  provider: ProviderDiscoveryKind,
  supportsSkillMentions: Schema.Boolean,
  supportsSkillDiscovery: Schema.Boolean,
  supportsNativeSlashCommandDiscovery: Schema.Boolean,
  supportsPluginMentions: Schema.Boolean,
  supportsPluginDiscovery: Schema.Boolean,
  supportsRuntimeModelList: Schema.Boolean,
  supportsThreadCompaction: Schema.optional(Schema.Boolean),
  supportsThreadImport: Schema.optional(Schema.Boolean),
});
The discovery service also loads skills (ProviderListSkillsResult), native slash commands (ProviderListCommandsResult), and plugins (ProviderListPluginsResult) for the active worktree’s cwd. Results are cached and can be force-refreshed with forceReload: true.
Custom models not in the provider’s default list can be added under settings.providers.<kind>.customModels in your settings.json. They appear alongside the dynamically discovered list in the model picker.

​
Provider start options

Each provider exposes a typed options struct you can pass when starting a session. These map directly to CLI flags or API parameters for the underlying tool: 
export const ClaudeProviderStartOptions = Schema.Struct({
  binaryPath: Schema.optional(TrimmedNonEmptyString),
  permissionMode: Schema.optional(TrimmedNonEmptyString),
  maxThinkingTokens: Schema.optional(NonNegativeInt),
});

export const OpenCodeProviderStartOptions = Schema.Struct({
  binaryPath: Schema.optional(TrimmedNonEmptyString),
  serverUrl: Schema.optional(TrimmedNonEmptyString),
  serverPassword: Schema.optional(TrimmedNonEmptyString),
  experimentalWebSockets: Schema.optional(Schema.Boolean),
});
These options can be passed inline on each ThreadTurnStartCommand via providerOptions or stored as defaults under settings.providers.<kind> in your settings file.

Provider setup guides

Step-by-step installation and authorization instructions for each supported provider.

Settings reference

Full reference for settings.json including per-provider binary paths, custom models, and launch arguments.

Build docs developers (and LLMs) love

Get started for freeTalk to us