Skip to content

settings.md

Latest commit

 

History

History
599 lines (441 loc) · 39.2 KB

settings.md

File metadata and controls

599 lines (441 loc) · 39.2 KB
Raw

Settings Reference

This document provides a comprehensive reference for all Obsidian Gemini Scribe settings.

The settings tab is organised into a permanently-open General section at the top — covering provider, API key, models, and the plugin state folder — followed by collapsible sections (▶ collapsed, ▼ expanded). Click any header to toggle it; expand/collapse state is remembered between sessions in the expandedSettingsSections setting. All collapsible sections start collapsed.

The order of sections is:

  1. General (always open) — provider, API key, models, plugin state folder, Show advanced settings toggle.
  2. User experience — your name, frontmatter key, streaming, diff view, session history toggle, tool execution logging.
  3. Automation — scheduled tasks, scheduler catch-up, and lifecycle hooks combined.
  4. Vault search index — semantic search over your vault using Google File Search.

Advanced sections — Tool permissions, MCP servers, Agent config, Debug — are tagged with an ADVANCED pill and only appear after toggling Show advanced settings at the bottom of General. Agent config bundles four related sub-areas (Custom Prompts, API configuration, Context management, Tool loop detection) under one collapsible since they all tune how the agent talks to the model.

Table of Contents

The reference below groups settings by topic for lookup, which doesn't always map 1:1 to the UI section names. The annotation in parentheses tells you which UI section a topic appears under.

UI sections without a dedicated topic in this reference: Vault search index (covered in Semantic Search). The Automation section's task and hook management UI is covered in the Scheduled tasks and Lifecycle Hooks guides; the two persistent settings (autoRunCatchUp, hooksEnabled) are documented in Automation Settings below.

Basic Settings

Provider

  • Setting: provider
  • Type: 'gemini' | 'ollama' | 'openai'
  • Default: 'gemini'
  • Description: The default model backend, used by every feature without an explicit override (see Per-feature provider). gemini calls the Google Cloud API; ollama calls a local Ollama daemon; openai calls the OpenAI Chat Completions API (or a compatible server at a custom base URL).
  • Notes: Changing the provider re-initialises the plugin. Model selections persist across the change — the Gemini fields (chatModelName, summaryModelName, completionsModelName, imageModelName), the Ollama fields (ollamaModelName, ollamaSummaryModelName, ollamaCompletionsModelName), and the OpenAI fields (openaiModelName, openaiSummaryModelName, openaiCompletionsModelName) are each stored separately, so returning to a provider restores the model you had there; a value is only reset if it's actually stale for its own provider (e.g. a deprecated Gemini model id), never merely because you switched providers. Cloud-only features (Google Search, URL Context, Deep Research, image generation, RAG indexing) are off when ollama or openai is the default — unless you route them to Gemini individually. See the Ollama Setup Guide and OpenAI Setup Guide for details.

Per-feature provider

  • Setting: providerOverrides
  • Type: Partial<Record<'chat' | 'summary' | 'completions' | 'rewrite' | 'webSearch' | 'rag' | 'imageGen', 'gemini' | 'ollama' | 'openai'>>
  • Default: {} (every feature uses provider)
  • Description: Routes individual features to a provider other than the default. Each settings row lists only the providers that support that feature, so e.g. Image generation offers Gemini only, while Chat/Summaries/Completions/Rewrite offer all three. This is what enables a mixed setup — chat on a local Ollama or OpenAI-compatible model, web search and image generation on Gemini.
  • Notes:
    • A feature is never routed to the cloud on your behalf. If the resolved provider can't serve a feature, that feature stays off; the plugin does not substitute a different one. Enabling a cloud feature is always an explicit choice.
    • Choosing Gemini for a feature means that feature's requests — including note content — go to Google. Choosing OpenAI means they go to your configured OpenAI base URL. The settings UI names the affected features whenever this is the case.
    • The API key field is shown whenever any feature is routed to Gemini, not just when Gemini is the default; the OpenAI API key field works the same way for OpenAI.
    • Changing any override re-initialises the plugin, since tool registration, RAG, and image generation all key off the resolved providers.
    • Unknown keys or provider ids in a hand-edited data.json are dropped on load.
  • Full capability matrix: Provider Capabilities

Ollama base URL

  • Setting: ollamaBaseUrl
  • Type: String
  • Default: http://localhost:11434
  • Required when any feature uses ollama: Yes
  • Description: HTTP endpoint of your Ollama daemon. Update if Ollama runs on a different host or port.

OpenAI base URL

  • Setting: openaiBaseUrl
  • Type: String
  • Default: https://api.openai.com/v1
  • Required when any feature uses openai: Yes (falls back to the default if cleared)
  • Description: Endpoint OpenAI Chat Completions requests are sent to. Point this at an OpenAI-compatible local server instead — LM Studio, MLX, Ollama's OpenAI-compatible endpoint, etc. — to keep requests on your machine. See the OpenAI Setup Guide.

API Key

  • Type: String
  • Required: Yes, whenever any feature is routed to gemini — including a single per-feature override under an ollama or openai default. Not needed for an all-Ollama setup.
  • Storage: Stored securely using Obsidian's SecretStorage API (not saved in data.json)
  • Description: Your Google AI API key for accessing Gemini models
  • How to obtain: Visit Google AI Studio
  • Migration: If upgrading from a previous version, your API key is automatically migrated from data.json to secure storage on first load

OpenAI API key

  • Setting: openaiApiKeySecretName
  • Type: String (SecretStorage key name; the key value itself is never in data.json)
  • Default: "" (unset)
  • Required: Yes, whenever any feature is routed to openai — including a single per-feature override under a different default. For a local compatible server that doesn't validate keys, any placeholder value satisfies this requirement.
  • Storage: Stored securely using Obsidian's SecretStorage API, mirroring apiKeySecretName for Gemini
  • How to obtain: Visit platform.openai.com/api-keys

Your name

  • Setting: userName
  • Type: String
  • Default: "User"
  • Description: Name used by the AI when addressing you in responses

Plugin state folder

  • Setting: historyFolder
  • Type: String
  • Default: gemini-scribe
  • Description: Folder where plugin stores history, prompts, and sessions
  • Notes: The value is normalized on load and when saved (via normalizePath semantics) — a hand-typed trailing, leading, or duplicate slash is corrected automatically, so folder exclusion and subfolder paths never break on a malformed state-folder path.
  • Structure: 
    gemini-scribe/
├── History/          # Legacy note-centric chat history files (v3.x and earlier)
├── Prompts/          # Custom prompt templates
├── Skills/           # Custom agent skills (<skill-name>/SKILL.md)
├── Agent-Sessions/   # Agent mode sessions with conversation history
├── Scheduled-Tasks/  # Scheduled task definitions and run output
├── Background-Tasks/ # Output from background deep-research and image-gen tasks
├── Hooks/            # Lifecycle hook definitions and run output (created when hooksEnabled is true)
├── debug.log         # Current log file (when file logging is enabled)
└── debug.log.old     # Previous rotated log file

Enable session history

  • Setting: chatHistory
  • Type: Boolean
  • Default: false
  • Description: Store agent session history as markdown files in your vault
  • Note: Sessions are saved in the Agent-Sessions subfolder with auto-generated titles

Summary frontmatter key

  • Setting: summaryFrontmatterKey
  • Type: String
  • Default: "summary"
  • Description: Frontmatter key used when storing document summaries

Model Configuration

Each model picker is filtered to the models of the provider serving its own feature, so a chat-on-Ollama / summaries-on-Gemini setup offers the right models in each row. Every provider in use has its list loaded independently.

  • Gemini — models are loaded from the bundled list and auto-refreshed from GitHub on startup (cached for 24h). Click Refresh model list in Settings → General — or run the Gemini Scribe: Refresh model list command — to fetch the latest list immediately (bypasses the cache). imageModelName is Gemini-only.
  • Ollama — dropdowns are populated from GET <ollamaBaseUrl>/api/tags, listing whatever you have pulled. Click Refresh Ollama model list if a freshly pulled model doesn't appear. Ollama keeps only one model resident at a time, so its summary and completions pickers default to Same as chat model ('') — picking a distinct model there is supported but costs a model reload on every switch.
  • OpenAI — dropdowns are populated from GET <openaiBaseUrl>/models, enriched with curated metadata (context window, vision support) for current api.openai.com models; unrecognized ids (typically from a compatible server) get conservative defaults. Click Refresh OpenAI model list if a model doesn't appear. Unlike Ollama, OpenAI has no single-resident-model constraint, so chat, summary, and completions each default to their own model rather than inheriting the chat model.

Because each provider uses its own settings fields, re-routing a feature between providers preserves every provider's choice — returning to a provider restores the exact model you had.

Chat model

  • Setting: chatModelName
  • Type: String
  • Default: gemini-flash-latest
  • Description: Model used for agent chat conversations and the Rewrite text with AI command
  • Available Models (representative sample — the full list is auto-refreshed; see Model Discovery):
    • gemini-flash-latest - Gemini Flash Latest (fast and efficient, default for chat/summary/rewrite)
    • gemini-flash-lite-latest - Gemini Flash Lite Latest (lightweight, default for completions)
    • gemini-2.5-flash - Gemini 2.5 Flash
    • gemini-2.5-pro - Gemini 2.5 Pro
    • gemini-3-flash-preview - Gemini 3 Flash Preview
    • gemini-3.1-pro-preview - Gemini 3.1 Pro Preview
    • gemini-3.5-flash - Gemini 3.5 Flash
  • Note: The full model list is loaded from the bundled models.json and auto-refreshed from GitHub on startup (cached 24h). Click Refresh model list in Settings → General for an immediate refresh.

Summary model

  • Setting: summaryModelName
  • Type: String
  • Default: gemini-flash-latest
  • Description: Model used for document summarization
  • Used by: Summarize active file command, conversation compaction
  • Note: Used when summaries are served by Gemini. When they're served by Ollama, ollamaSummaryModelName applies instead and this value is left untouched.

Completions Model

  • Setting: completionsModelName
  • Type: String
  • Default: gemini-flash-lite-latest
  • Description: Model used for IDE-style auto-completions
  • Note: Completions must be enabled via command palette
  • Note: Used when completions are served by Gemini. When they're served by Ollama, ollamaCompletionsModelName applies instead and this value is left untouched.

Image model

  • Setting: imageModelName
  • Type: String
  • Default: gemini-2.5-flash-image
  • Only shown when: Image generation is routed to a provider that supports it (Gemini today)
  • Description: Model used for image generation via the generate_image tool and the Generate image command. Only models with image-generation capability appear in this dropdown.
  • Note: Interactions-only image models (e.g. gemini-omni-flash-preview) generate through the Interactions API instead of generateContent, regardless of the Use Interactions API toggle.

Ollama model

  • Setting: ollamaModelName
  • Type: String
  • Default: '' (backfilled to the first pulled model once the daemon's list loads)
  • Only shown when: Chat is served by ollama
  • Description: The local model used for chat and rewrite, and for any other Ollama-served feature left on Same as chat model. Stored separately from the Gemini chatModelName so re-routing preserves each provider's choice. Populated from GET <ollamaBaseUrl>/api/tags.

Ollama summary / completions models

  • Settings: ollamaSummaryModelName, ollamaCompletionsModelName
  • Type: String
  • Default: '' — Same as chat model
  • Only shown when: That feature is served by ollama
  • Description: Optional per-feature Ollama models. Ollama keeps one model resident at a time, so the default inherits ollamaModelName and avoids a reload on every call; set one only when the swap is worth it (a small, fast completions model is the usual case). A value naming a model the daemon no longer serves is reset to '' rather than to another model, so the feature falls back to the chat model instead of silently switching.

OpenAI chat / summary / completions models

  • Settings: openaiModelName, openaiSummaryModelName, openaiCompletionsModelName
  • Type: String
  • Default: 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna' respectively
  • Only shown when: That feature is served by openai
  • Description: The OpenAI model used for each use case. Unlike Ollama, OpenAI has no single-resident-model constraint, so each use case keeps its own model rather than defaulting to "inherit the chat model." Populated from GET <openaiBaseUrl>/models.

Custom Prompts

Custom prompts allow you to create reusable AI instruction templates that modify how the AI behaves for specific sessions.

Allow System Prompt Override (legacy, currently non-functional)

  • Setting: allowSystemPromptOverride
  • Type: Boolean
  • Default: false
  • Description: Intended to gate whether custom prompts can completely replace the default system prompt. Currently has no effect: any prompt with override_system_prompt: true in its frontmatter replaces the system prompt regardless of this setting. Toggling it on or off does not change that behavior.
  • Warning: Because the frontmatter flag alone controls the override, a custom prompt with override_system_prompt: true can break expected functionality if it doesn't include essential instructions — this setting will not prevent that.

Creating Custom Prompts

  1. Create a markdown file in [Plugin state folder]/Prompts/
  2. Write your custom instructions in the file
  3. Select it in the session settings modal (gear icon in the agent panel)

See the Custom Prompts Guide for detailed instructions.

UI Settings

Enable streaming

  • Setting: streamingEnabled
  • Type: Boolean
  • Default: true
  • Description: Enable streaming responses in the chat interface for a more interactive experience
  • Note: When disabled, full responses are displayed at once

Log Tool Execution to Session History

  • Setting: logToolExecution
  • Type: Boolean
  • Default: true
  • Description: Append a summary of each tool execution to the session history file for auditing
  • Format: Collapsible callout blocks showing tool name, key parameters, status, and duration
  • Note: Takes effect immediately when toggled — no plugin reload needed

Always Show Diff view for File Writes

  • Setting: alwaysShowDiffView
  • Type: Boolean
  • Default: false
  • Description: Automatically open a diff view when the agent proposes file changes, instead of requiring a button click
  • When off: The confirmation card shows a summary and a "View changes" button. Click it to open the diff view
  • When on: The diff view opens automatically alongside the confirmation card
  • Note: The diff view lets you edit the proposed content before approving. If you modify content, the tool result reports userEdited: true so the agent knows

Expanded Settings Sections

  • Setting: expandedSettingsSections
  • Type: string[]
  • Default: []
  • Description: Internal list of section ids that are currently expanded in the settings tab. Updated automatically when you toggle a section. Known ids: ui, automation, rag, tool-permissions, mcp-servers, agent-config, debug, per-feature-provider. (General itself is always open and has no id; its Per-feature provider sub-section is separately collapsible and tracked as per-feature-provider.)
  • Note: Edit data.json directly to pre-expand sections (for example, on a new install) or restore a custom layout after migrating vaults.

Automation Settings

These settings appear in the Automation section of the plugin settings (UI: Automation). Task and hook management controls (creating, editing, and running tasks/hooks) are covered in the Scheduled tasks and Lifecycle Hooks guides.

Auto-run missed scheduled tasks on startup

  • Setting: autoRunCatchUp
  • Type: Boolean
  • Default: false
  • Description: When enabled, tasks with runIfMissed: true that were missed while Obsidian was closed are submitted silently as background tasks on startup, without showing the approval modal.
  • When disabled: The "Missed scheduled runs" modal appears on startup so you can choose Run or Skip per task. A red ! badge on the status bar persists if the modal is dismissed without acting.
  • See also: Catch-up Runs

Enable lifecycle hooks

  • Setting: hooksEnabled
  • Type: Boolean
  • Default: false
  • Description: Subscribe to vault events (file created/modified/deleted/renamed) and dispatch them to hook definitions in [state-folder]/Hooks/. Each matching event fires a headless agent run with debounce, rate-limit, and loop-prevention guards.
  • Why opt-in: Vault events fire continuously; an unintentionally-broad hook can drain API quota quickly. The default is off so users opt in deliberately.
  • See also: Lifecycle Hooks

Context management

Context management automatically monitors and controls conversation size to prevent exceeding model token limits.

Context Compaction Threshold

  • Setting: contextCompactionThreshold
  • Type: Number (percentage, 5-50)
  • Default: 20
  • Description: Percentage of the model's input context window at which automatic compaction occurs
  • How it works: When conversation tokens exceed this percentage, older turns are summarized and replaced with a compact summary while preserving recent messages
  • Hard ceiling: Aggressive compaction triggers at 80% of the input limit to prevent API errors

Two-phase compaction

When a session crosses the compaction threshold the plugin runs a cheaper pass before reaching for full summarization:

  1. Phase 1 — tool-result truncation. Walks history and replaces oversized (>4 KB) functionResponse payloads in older turns with a small { truncated: true, truncatedFrom: N, note: "..." } marker. The most recent two tool-result turns are kept intact so the agent reasoning across recent tool calls still has the full text. This is purely structural — no LLM call, no extra tokens spent.
  2. Re-evaluation. If phase 1 freed enough room to put us back under the threshold (e.g., a single 600 KB read_file was responsible for most of the bloat), the request goes out with the truncated history and phase 2 is skipped entirely.
  3. Phase 2 — summarization. Only fires when truncation alone wasn't enough. Older turns are summarized via an LLM call into a single context-summary entry preserving recent messages.

Below the threshold, neither phase fires — older history bytes are left untouched so Gemini's implicit prefix cache stays valid and subsequent turns keep their cached-token discount. Truncation breaks the cache from the modified point forward, so it's restricted to turns where we'd be paying that cost anyway (compaction would have run otherwise).

Re-issuing a tool call brings the full output back if the agent needs it. The behavior is always-on and not currently exposed as a setting.

Compaction isn't only checked before the initial request — AgentLoop re-checks after every tool batch, so a long tool chain (many iterations in a single turn) can be compacted mid-flight instead of only at the start of the next user turn. Mid-loop compaction never touches the current tool chain's own turns (the ones carrying the in-flight functionCall/thoughtSignature continuity) — only turns from before the chain started are eligible, so an in-progress multi-step tool sequence is never summarized out from under itself.

Developer Settings

Advanced settings for developers and power users. Access by clicking "Show advanced settings" in the plugin settings.

Debug mode

  • Setting: debugMode
  • Type: Boolean
  • Default: false
  • Description: Enable detailed console logging for troubleshooting
  • Use case: Debugging API issues, tool execution problems, or unexpected behavior

Show Token Usage

  • Setting: showTokenUsage
  • Type: Boolean
  • Default: false
  • Description: Display estimated token count in the agent input area
  • Display format: Tokens: ~N / M (X%) showing total prompt tokens, model limit, and percentage used. When part of the prompt was served from Gemini's cache, an additional · Y% cached suffix appears; when the model reports its reasoning (thinking) token count for the last response, a · Z reasoning suffix appears. Both suffixes can appear together
  • How it works: Token counts update live after each API response, including during tool call chains. Gemini's implicit caching means repeated content (system prompt, tool definitions) is often served from cache — the cached percentage rewards stable prefixes (system prompt, pinned history). The reasoning count appears only for models that report thinking tokens (Gemini thinking models); reasoning tokens are output-side and included in the response's total, so they don't count against the context window the percentage measures
  • Visual indicators:
    • Normal (muted text) — well under threshold
    • Yellow — approaching compaction threshold (≥80% of threshold)
    • Orange/red — at or above compaction threshold

Log to File

  • Setting: fileLogging
  • Type: Boolean
  • Default: false
  • Description: Write log entries to a file (debug.log) in the plugin state folder
  • Behavior:
    • Errors and warnings are always written to the log file when enabled
    • Debug-level entries (log(), debug()) are only written when Debug mode is also enabled
    • Log files are automatically rotated at 1 MB (previous log kept as debug.log.old)
    • Writes are batched and debounced to minimize I/O impact
  • Use case: Sharing diagnostic information in bug reports, or letting the agent self-diagnose issues via the bundled gemini-scribe-help skill (which exposes debug.log and debug.log.old as activatable resources only when this setting is on)
  • Note: Log files are stored in the plugin state folder and are automatically excluded from RAG indexing. The standard read_file tool blocks the state folder; the help skill is the supported path for the agent to read these logs.

API configuration

Use Interactions API

  • Setting: useInteractionsApi
  • Type: Boolean
  • Default: true
  • Only applies when: Gemini serves at least one use case (the toggle is hidden when no feature is routed to Gemini — e.g. an all-Ollama or all-OpenAI setup — and shown whenever chat, summary, or any other feature is routed to Gemini)
  • Description: Routes Gemini requests through Google's GA Interactions API (interactions.create) instead of the legacy generateContent API. This is now the default transport; existing installs are migrated to it automatically (a one-time flip you can reverse by turning the toggle off).
  • Privacy: Runs statelessly (store: false) — conversation history is replayed with each request, and the plugin does not persist Interactions state on Google's side between turns. (Requests are still sent to Google to generate each response, subject to Google's standard API data-handling terms.)
  • Status: Default-on. Responses stream incrementally (text, reasoning, and tool calls); turn it off to fall back to the legacy generateContent path if you hit issues.
  • Scope: Governs the conversational chat transport only. Image generation (the generate_image tool and Generate image command) always uses generateContent regardless of this setting — unless the selected image model is interactions-only (see below), in which case it uses the Interactions API.
  • Interactions-only models: Models flagged interactionsOnly in the model catalog (e.g. gemini-omni-flash-preview, an image-generation model) are only served by the Interactions API, so requests to them always route through it even when this toggle is off. Features that still run on generateContent (Google Search grounding, web fetch, RAG semantic search) substitute the default chat model if an interactions-only model ever ends up configured as the chat model.

Custom API Endpoint

  • Setting: customBaseUrl
  • Type: String
  • Default: "" (empty)
  • Only applies when: Gemini serves at least one use case (Ollama has its own ollamaBaseUrl setting and OpenAI has its own openaiBaseUrl setting; both ignore this value, and the field is hidden when no feature is routed to Gemini)
  • Description: Overrides the default Google API base URL for all SDK calls. Use this to route requests through a corporate proxy, local gateway, or regional mirror.
  • Example: https://my-proxy.example.com
  • Scope: Applies to every Google API call site in the plugin (chat, streaming, image generation, web fetch, Google Search/Maps grounding, RAG indexing, deep research, context management).
  • Note: Leave blank to use the official Google endpoint. Invalid URLs will show a warning and be cleared automatically.
  • Security note: Requests routed through this proxy will include your Google API key in the x-goog-api-key header.

Maximum retries

  • Setting: maxRetries
  • Type: Number
  • Default: 3
  • Description: Maximum number of retry attempts when a model request fails
  • Note: Uses exponential backoff between retries. Applies to streaming and non-streaming requests alike, which share one retry policy.

Initial Backoff Delay

  • Setting: initialBackoffDelay
  • Type: Number (milliseconds)
  • Default: 1000
  • Description: Initial delay before the first retry attempt
  • Note: Subsequent retries use exponential backoff (2x, 4x, 8x, etc.), plus up to 10% random jitter so that several clients retrying after the same rate limit don't do so in lockstep. Each wait is capped at 60 seconds, so a large initial delay cannot push a retry arbitrarily far out.
  • Note: When the API supplies its own retry delay (a RetryInfo hint on a 429), that value is used instead of the backoff — also capped at 60 seconds.

Model Parameters

Temperature

  • Setting: temperature
  • Type: Number (0.0-2.0)
  • Default: 0.7
  • Description: Controls response creativity and randomness
    • Lower (0.0-0.5): More focused, deterministic, consistent
    • Medium (0.5-1.0): Balanced creativity and coherence
    • Higher (1.0-2.0): More creative, varied, unpredictable
  • Note: Ranges automatically adjusted based on selected model's capabilities

Top-P

  • Setting: topP
  • Type: Number (0.0-1.0)
  • Default: 1.0
  • Description: Controls response diversity via nucleus sampling
    • Lower values (0.1-0.5): More focused on likely tokens
    • Higher values (0.5-1.0): More diverse vocabulary
  • Note: Works in conjunction with temperature

Model Discovery

Model discovery is automatic — no user-configurable settings are required. On startup, the plugin fetches the latest available Gemini models from GitHub and falls back to the bundled list if the fetch fails. The remote list is cached in data.json under remoteModelCache for 24 hours; subsequent reloads within that window are no-ops.

To pick up a newly-published model without waiting for the cache to expire, click Refresh model list in Settings → General, or run the Gemini Scribe: Refresh model list command (gemini-scribe:refresh-model-list). Both honor the same skip conditions as the auto-fetch — they no-op when no feature is routed to Gemini or the host reports offline, and surface the outcome via a Notice. When any feature uses Ollama, a separate Refresh Ollama model list row re-queries the daemon for newly pulled models; when any feature uses OpenAI, a Refresh OpenAI model list row re-queries GET <openaiBaseUrl>/models. In a mixed setup, only the rows for providers actually in use are shown.

When Google retires a model (the API starts returning 404 "no longer available" — e.g. gemini-3-pro-preview in July 2026), it is removed from the catalog and any settings still pointing at it are migrated automatically on the next reload: to the retired model's designated successor when one exists (gemini-3-pro-preview → gemini-3.1-pro-preview), otherwise to the default model for that role.

Tool Execution

Stop on Tool Error

  • Setting: stopOnToolError
  • Type: Boolean
  • Default: true
  • Description: Stop agent execution when a tool call fails
  • When enabled: Agent stops immediately if any tool fails
  • When disabled: Agent continues executing subsequent tools despite failures

Tool loop detection

Prevents the AI agent from executing identical tools repeatedly, which can cause infinite loops.

Enable Loop Detection

  • Setting: loopDetectionEnabled
  • Type: Boolean
  • Default: true
  • Description: Detect and prevent infinite tool execution loops

Loop Threshold

  • Setting: loopDetectionThreshold
  • Type: Number
  • Default: 3
  • Range: 2-10
  • Description: Number of identical tool calls before a loop is detected

Time Window

  • Setting: loopDetectionTimeWindowSeconds
  • Type: Number (seconds)
  • Default: 30
  • Range: 10-120
  • Description: Time window for detecting repeated calls
  • Example: If threshold is 3 and window is 30s, calling the same tool 3+ times within 30 seconds triggers detection

Tool permissions

Controls which agent tools execute automatically, which require user confirmation before each run, and which are blocked entirely. Access via Settings → Gemini Scribe → Show advanced settings → Tool permissions.

Permission Preset

  • Setting: toolPolicy.activePreset
  • Type: String
  • Default: cautious
  • Options:
Preset Label Read tools Write tools Destructive tools External tools
read_only Read only Auto Blocked Blocked Blocked
cautious Cautious (default) Auto Ask Ask Ask
edit_mode Edit mode Auto Auto Ask Ask
yolo YOLO mode Auto Auto Auto Auto
custom Custom Per-tool overrides Per-tool overrides Per-tool overrides Per-tool overrides
  • YOLO mode warning: Selecting YOLO mode requires explicit confirmation in a modal. All operations execute without prompts — use only in trusted, well-understood workflows.
  • Custom preset: Automatically activated when you override any individual tool's permission. Selecting a named preset resets all per-tool overrides.

Per-Tool Overrides

  • Setting: toolPolicy.toolPermissions
  • Type: Object (tool name → permission)
  • Default: {} (empty — preset governs all tools)
  • Description: Each registered tool can be individually set to deny (blocked), ask_user (confirmation required), or approve (runs automatically) — these are the values persisted in data.json for this setting. Overrides take precedence over the active preset. Setting an override causes the preset to switch to custom. (This is distinct from the toolPolicy YAML block used by Projects, Scheduled Tasks, and Hooks, which uses the shorter deny/ask/allow aliases in frontmatter — see those guides.)

MCP servers

MCP (Model Context Protocol) server support allows the agent to use tools from external MCP servers. Supports both local (stdio) and remote (HTTP) servers.

Enable MCP servers

  • Setting: mcpEnabled
  • Type: Boolean
  • Default: false
  • Description: Enable connections to MCP servers for external tool integration

Server List

  • Setting: mcpServers
  • Type: Array of server configurations
  • Default: []
  • Description: List of MCP server configurations

Each server configuration includes:

Field Type Description
name String Unique server name
transport String Transport type: "stdio" (local) or "http" (remote). Default: "stdio"
command String Command to spawn the server (stdio only)
args String[] Command arguments (stdio only)
url String Server URL (http only, e.g., http://localhost:3000/mcp)
envSecretName String SecretStorage key for the server's env vars (stdio only; values are not stored in data.json)
enabled Boolean Connect on plugin load
trustedTools String[] Tools that skip confirmation

Environment variable values are kept in Obsidian's SecretStorage (the OS keychain), not in data.json. The config only stores envSecretName, a pointer to the keychain entry.

See the MCP servers Guide for setup instructions.

Session-Level Settings

Session settings override global defaults for specific agent sessions. Access via the settings icon in the session header.

Model Configuration

  • Model: Override the default chat model for this session
  • Temperature: Session-specific temperature setting
  • Top-P: Session-specific top-p setting
  • Custom Prompt: Select a custom prompt template for this session

Context Files

  • Add specific notes as persistent context for the session
  • Context files are automatically included with every message
  • Use @ mentions in chat to add files
  • Active note is automatically included by default

Permissions

Session-level permissions allow bypassing confirmation dialogs for specific operations during the current session only.

Available permission bypasses:

  • File creation
  • File modification
  • File deletion
  • File moving/renaming

Note: Permissions reset when you create a new session or load a different session.

Performance Considerations

  • Model Selection: Flash models (8B, standard) are faster but less capable than Pro models
  • Temperature: Higher values may require more processing time
  • Model Discovery: Minimal performance impact; runs in background
  • Loop Detection: Negligible overhead; recommended to keep enabled

Security Best Practices

  1. API Key: Your API key is stored securely via Obsidian's SecretStorage and is not written to data.json. Never share your API key or commit it to version control
  2. System Folders: Plugin automatically protects Obsidian's configuration folder (.obsidian by default, or a renamed one) and plugin state folders from tool operations
  3. Tool permissions: Review tool operations before approving (when confirmations are enabled)
  4. System Prompt Override: Use with caution; can break expected functionality

Troubleshooting

Models not appearing

  1. Check API key is valid
  2. For Gemini: click Refresh in the Refresh model list row (Settings → General), or run the Gemini Scribe: Refresh model list command. The auto-fetch runs at most once every 24 hours, so a freshly published model won't appear until the cache expires unless you force a refresh.
  3. For Ollama: go to Settings → General and click Refresh in the Refresh Ollama model list row after pulling new models
  4. For OpenAI: go to Settings → General and click Refresh in the Refresh OpenAI model list row — useful after changing the base URL or loading a different model in a compatible server
  5. Check console for errors (with Debug mode enabled)

Tool execution issues

  1. Enable Debug mode and Log to File
  2. Check Loop Detection settings
  3. Review Stop on Tool Error setting
  4. Examine console logs or debug.log in the plugin state folder for specific errors

Chat history not saving

  1. Verify "Enable session history" is toggled on
  2. Check Plugin state folder path is valid
  3. Ensure you have write permissions to vault

For more help, see the Getting Started Guide or open an issue.