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 connects to the Google Gemini CLI via the Agent Communication Protocol (ACP). When you start a Gemini thread, Synara spawns the gemini binary with the --acp flag and communicates with it over a JSON-RPC stdio channel. This gives Synara full session control — it manages turns, approvals, and context — while Gemini handles reasoning and code generation using your Google account. The Gemini CLI must be installed on your machine before Synara can run Gemini sessions.

​
Prerequisites

  • Google Gemini CLI installed — follow the Gemini CLI setup guide to install it.
  • Signed in to your Google account via the CLI (run gemini in your terminal to complete authentication).
Synara does not install or manage the Gemini CLI. If the gemini binary is not found, configure binaryPath or add the CLI to your PATH and restart Synara.

​
Configuration

Gemini is configured under providers.gemini in settings.json. All fields are optional. 
{
  "providers": {
    "gemini": {
      "enabled": true,
      "binaryPath": "gemini",
      "customModels": []
    }
  }
}
​
enabled
boolean
default:"true"
Set to false to disable the Gemini provider. Synara will skip it during startup discovery and will not allow new Gemini threads.
​
binaryPath
string
default:"gemini"
The command or full path used to launch the Gemini CLI. Defaults to "gemini", resolved via your PATH. Use an absolute path if your installation is not on PATH.
​
customModels
string[]
default:"[]"
Additional model slugs to show in the model picker alongside Synara’s built-in Gemini model list. Useful for preview or beta models not yet in the built-in list.

​
Model options

Gemini model options let you tune the thinking behaviour per session. 
// From packages/contracts/src/model.ts
export const GEMINI_THINKING_LEVEL_OPTIONS = ["LOW", "HIGH"] as const;
export const GEMINI_THINKING_BUDGET_OPTIONS = [-1, 512, 0] as const;

export const GeminiModelOptions = Schema.Struct({
  thinkingLevel: Schema.optional(Schema.Literals(GEMINI_THINKING_LEVEL_OPTIONS)),
  thinkingBudget: Schema.optional(Schema.Literals(GEMINI_THINKING_BUDGET_OPTIONS)),
});
​
thinkingLevel
string
The thinking intensity level for models that support it. Available on Gemini 3-series models.
ValueDescription
HIGHHigher reasoning effort — default for Gemini 3 models.
LOWLower reasoning effort — faster, less thorough.
​
thinkingBudget
number
Token budget for the model’s internal reasoning on Gemini 2.5 models.
ValueDescription
-1Dynamic budget — Gemini allocates tokens as needed (default for Gemini 2.5 models).
512Fixed 512-token thinking budget.
0No thinking tokens — direct response without internal reasoning.

​
Built-in model roster

SlugName
auto-gemini-3Auto Gemini 3
auto-gemini-2.5Auto Gemini 2.5
gemini-3.1-pro-previewGemini 3.1 Pro Preview
gemini-3-flash-previewGemini 3 Flash Preview
gemini-3.1-flash-lite-previewGemini 3.1 Flash Lite Preview
gemini-2.5-proGemini 2.5 Pro
gemini-2.5-flashGemini 2.5 Flash
gemini-2.5-flash-liteGemini 2.5 Flash Lite
The default model for new Gemini threads is auto-gemini-3.

​
ACP probe on startup

When Synara starts (or when you open the provider status panel), it probes the Gemini CLI by launching it in ACP mode and performing an initialize + session/new handshake. The probe:
  1. Spawns the gemini binary with --acp and environment variables that prevent any OAuth browser flow (NO_BROWSER=true, BROWSER=www-browser, CI=true).
  2. Sends an initialize request to verify the ACP connection.
  3. Sends a session/new request to discover the list of available models from the live CLI.
  4. Closes the session gracefully and terminates the process.
The probe has a 30-second timeout. If it times out or the CLI exits unexpectedly, Synara marks the provider as warning and falls back to the built-in model list. If the CLI returns an authentication error (JSON-RPC code -32000 or a message containing authentication required, api key is missing, auth method, or not configured), the provider is marked as error with an unauthenticated auth status and you will see a sign-in prompt.
If the probe completes successfully but the CLI reports no available models, Synara falls back to its built-in Gemini model list and shows an informational message. You can still start Gemini sessions normally.

​
Related

Build docs developers (and LLMs) love

Get started for freeTalk to us