Agent mode Guide

Gemini Scribe v4.0 is agent-first - every conversation is powered by an AI assistant that can actively work with your vault through tool calling. This guide covers everything you need to know about using the agent effectively and safely.

What is the Agent?

In v4.0+, the agent is always available and can:

• Read and search files in your vault
• Create, modify, and organize notes
• Search the web for information
• Fetch and analyze web pages
• Execute multiple operations in sequence
• Work autonomously while respecting your permissions

New in v4.0: Agent mode is no longer a separate feature you enable - it's the core of how Gemini Scribe works. Every chat is an agent session with full tool-calling capabilities.

Getting Started

1. Open Agent Chat

• Use Command Palette: "Gemini Scribe: Open Gemini chat"
• Or click the sparkles icon (✨) in the ribbon
• Or use your configured hotkey
• You can also manage sessions directly from the command palette with:
  • "New agent session"
  • "Browse agent sessions"
  • "Link project to agent session"
  • "Agent session settings"

2. Initialize vault context (Recommended)

1. In an empty agent session, click "Initialize vault context"
2. The agent will analyze your vault structure and create AGENTS.md
3. This helps the agent understand your vault organization
4. Update periodically as your vault grows

3. Configure Permissions

Choose which operations require confirmation in Settings → Gemini Scribe → Tool permissions (enable Show advanced settings first):

• write_file: Creating or modifying files
• delete_file: Removing files
• move_file: Moving or renaming files
• append_content: Adding text to the end of files
• update_frontmatter: Modifying note properties (frontmatter)
• create_folder: Creating new folders
• create_skill: Creating new skill packages
• edit_skill: Updating existing skill instructions
• generate_image: Generating and saving images
• update_memory: Updating vault memory (AGENTS.md)
• google_search, google_maps, fetch_url, deep_research: External web/research calls (Gemini provider only)

When the agent needs to perform these operations, an in-chat confirmation request appears with interactive buttons. You can also use "Don't ask again this session" for trusted workflows. See Tool Confirmations for details.

Core Features

Tool Calling

The agent can execute various tools to help with your tasks:

User: Find all my meeting notes from this week and create a summary

Agent: I'll help you find and summarize your meeting notes. Let me:
1. Search for meeting notes from this week
2. Read their contents
3. Create a summary document

[Executes find_files_by_name tool]
[Executes read_file tool for each result]
[Executes write_file tool to create summary]

Each tool call in the chat is collapsible — click a tool row to expand its details. When present, the Parameters and Result sections each include a copy button in the header that copies the full, untruncated value to the clipboard (handy for debugging, since long values are abbreviated in the inline display).

File Attachments & Drag-and-Drop

You can include images, audio, video, PDFs, SVGs, and text files in your chat. Files are automatically classified and routed:

Adding Files:

• Paste images directly from your clipboard (Ctrl/Cmd+V)
• Drag and drop files from your vault's file explorer into the input box
• Drag and drop files from your OS file manager (if they're inside the vault)
• Drag and drop folders to include all contained files
• Multiple files can be attached to a single message

How Files Are Routed:

When you drop a file, the plugin classifies it based on its extension:

Category	Extensions	Action
Text	.md, .txt, .ts, .js, .json, .html, .css, .py, etc.	Added as context chips (the AI reads the file content)
Binary (Gemini-supported)	.png, .jpg, .gif, .webp, .pdf, .mp3, .wav, .mp4, .mov, etc.	Sent as inline data (the AI processes the binary content directly)
SVG	.svg, .svgz	Rasterized to PNG on-device, then sent as inline data
Unsupported	.zip, .exe, .dmg, etc.	Skipped with a notification

Supported Binary Formats:

• Images: PNG, JPEG, GIF, WebP, HEIC, HEIF
• Vector images: SVG, SVGZ (rasterized to PNG before sending — see below)
• Audio: WAV, MP3, AAC, FLAC
• Video: MP4, MPEG, MOV, FLV, MPG, WebM, WMV, 3GP
• Documents: PDF

SVG Handling:

Gemini's API can't process image/svg+xml directly, so SVG (and gzip-compressed .svgz) files are rasterized to PNG on your device before being sent — whether you drag, paste, @-mention, or have the agent read them with the Read File tool. Rasterization renders the SVG onto a white background (so transparent artwork like handwritten ink strokes stays legible for OCR) and caps the longest edge at 2048px to keep the payload within the inline-data limit. If an SVG can't be rendered (malformed markup or unresolvable external references), it's skipped with the same "unsupported file type" notice rather than sending unusable data.

How It Works:

1. When you add a binary file, a preview appears above the input (thumbnail for images, icon + filename for other types)
2. Click the × button on any preview to remove it before sending
3. Pasted/external images are saved to your vault's attachment folder; vault files are referenced in place
4. The AI receives both the file content and its vault path for referencing
5. Images appear in the chat as wikilink embeds (e.g., ![[attachments/pasted-image.png]]); non-image attachments (PDF, audio, video) are listed by vault path and type label

Size Limits:

• Cumulative inline data is limited to 20 MB per message
• Files exceeding the limit are skipped with a notification

Privacy Note: Attached files are sent to the Gemini API for analysis. Avoid attaching files containing sensitive, confidential, or personal information.

Usage Examples:

User: [pastes screenshot] What's wrong with this error message?

Agent: I can see a TypeScript error in your screenshot. The issue is...

User: [drops a PDF] Summarize the key points from this document

Agent: Based on the PDF, here are the main points...

User: [drops a folder with mixed files] Review these project files

Agent: I can see the markdown notes in context and the attached images...

Combining with Context Files:

Attachments work alongside @ mentions and context files. You can:

• Reference attached files in context: "Look at the screenshot and update @ProjectNotes with the solution"
• Ask the agent to embed images in notes it creates
• Use file paths in wikilinks: ![[path/to/image.png]]

Edge Cases:

• Large files are sent as-is (no automatic compression)
• Unsupported file types are skipped with a notification
• If file processing fails, you'll see a notification
• Dropping a folder recursively includes all child files

Context Files & the File Shelf

Context files are displayed in a unified file shelf — a horizontal strip above the input area that shows all attached files (text files, folders, and binary attachments) in one place.

Adding files:

1. Type @ in the chat input to open the file picker (supports text files and Gemini-compatible binary files like images, SVGs, PDFs, audio, and video)
2. Type / in an empty chat input to open the skill picker — select a skill to insert an activation prompt you can edit before sending (see Agent Skills for details)
3. Click the file icon in the session header to open the multi-select modal:
   • Already-added files appear pre-checked
   • Type to fuzzy-search; Enter toggles a file or folder; Esc confirms and closes
   • Selecting a folder adds all text files inside it — markdown plus other text formats like .canvas, .base, .json (folders are re-expanded each turn, so newly added files are automatically included)
   • Unchecking a file or folder removes it from context
4. Drag and drop files or folders from the file explorer or your OS
5. Paste images from your clipboard

Interacting with the shelf:

• Click a shelf item to open the file in Obsidian
• Click the × button to remove an item
• Keyboard navigation: Arrow Left/Right to move between items, Enter/Space to open, Delete/Backspace to remove
• Text files and folders show a pin badge indicating they're sent with every message
• Binary attachments are marked as "sent" after a message and cleaned up automatically

For detailed information about context files and advanced usage, see the Context System Guide.

Session Management

• Each conversation is a separate session
• Sessions persist across Obsidian restarts when the "Session History" setting is enabled (off by default — see Settings Reference)
• Access previous sessions from the dropdown
• Configure session-specific settings
• Sessions are automatically titled with a YYYY-MM-DD date prefix and AI-generated description after the first exchange
• All files the agent reads or writes during a session are tracked in accessed_files frontmatter for auditing and session recall
• Tool execution summaries are logged to session history as collapsible callout blocks (controlled by the logToolExecution setting)

Model Reasoning

When you use a thinking model (e.g. Gemini 2.5 Pro), the agent captures the model's reasoning ("thinking") for each turn and keeps it after the response completes:

• Each reasoning step shows as a collapsed 🧠 Reasoning line (collapsed by default) — click to expand and see how the model worked through that step.
• During a tool-using turn, reasoning is interleaved into the tool activity block alongside the tool calls, in the order it happened (reason → call tools → reason → call more tools). Expand the activity block to see the full stream.
• The final answer's reasoning appears as a 🧠 line directly beneath the answer.
• Reasoning is persisted to the session history file as a collapsed [!reasoning] callout, so it round-trips when you reopen a past session — making session files a faithful, self-contained record of the whole interaction: your request → reasoning → tools → answer.
• Sessions created before this feature simply have no reasoning lines — nothing changes for them.
• Reasoning depth is tuned automatically per task and model family — Gemini 3.x models use per-task thinking levels (deepest for agent chat, lightest for completions), while Gemini 2.5 models use a dynamic thinking budget. There is no setting to configure.

Plan Mode

Plan Mode lets you review exactly what the agent intends to do before it acts. When active, the agent first produces a step-by-step implementation plan (with no tool calls) for you to approve or reject — only after approval does it proceed with full tool access.

Enabling Plan Mode:

• Click the checklist icon in the input toolbar (next to the send button) to toggle Plan Mode on/off. When active, it becomes an accent-colored Plan pill.
• Or use the Command Palette: "Gemini Scribe: Toggle Plan Mode".

How it works:

1. With Plan Mode active, type your request and send it as normal.
2. The agent generates a plan in response — it cannot call any tools yet.
3. The plan appears in the chat with Approve & Execute and Reject buttons.
4. Approve & Execute: The plan is saved to session history and the agent proceeds with the full request (tools enabled). The original plan remains visible in the session as context.
5. Reject: The request is cancelled and Plan Mode is automatically turned off.

When to use Plan Mode:

• Before bulk vault operations (moving files, rewriting notes) where you want to preview the agent's approach
• When working with sensitive or important files
• For complex multi-step workflows where you want to verify the agent's understanding before it acts
• Any time you want to preview and potentially redirect the agent's strategy

Plan Mode is purely opt-in and per-message — you can toggle it on for a single complex request and turn it off for routine follow-ups.

Available Tools

Read-Only Tools

find_files_by_name

Search for files by name pattern (searches filenames/paths only). Searches all file types, not just markdown:

Find all files containing "project"
Search for "*.md" files in the Projects folder
Find all PNG images in my vault with "*.png"

find_files_by_content

Search for text within file contents (grep-style search):

Find all notes mentioning "machine learning"
Search for TODO items across my vault
Find files containing the phrase "quarterly review" (case-insensitive)
Search using regex pattern: "deadline.*2024"

Supports:

• Case-sensitive and case-insensitive search
• Regex patterns
• Context lines before/after matches
• Respects system folder exclusions

read_file

Read the contents of any file in your vault. Supports text files (markdown, code, .base, .canvas) and binary files that Gemini can process (images, audio, video, PDF, and SVG — SVGs are rasterized to PNG on-device first):

Read the contents of my daily note
Show me what's in Projects/Todo.md
Describe the image at images/diagram.png
Transcribe the recording at audio/meeting.mp3
Read the PDF at docs/report.pdf
Transcribe the handwriting in Ink/Writing/note.svg

When you ask the agent to read a binary file, it sends the file data directly to Gemini for analysis — enabling image description, audio transcription, PDF reading, and video analysis without manual drag-and-drop. SVG files are rasterized to PNG on-device before sending, so the agent can view and OCR vector artwork (e.g. handwritten ink strokes) that Gemini would otherwise reject.

If a file doesn't exist, the agent receives a non-error response with exists: false and helpful suggestions for similar file names. This allows automation skills to probe for files without triggering error states.

list_files

List files in a folder. Returns all file types (not just markdown):

Show me all files in the Archive folder
List the contents of my Templates directory
What files are in the attachments folder?

get_workspace_state

Get metadata about all Markdown files currently open in the editor. Returns each file's path, wikilink, whether it is visible in a pane, whether it is the active (focused) file, and any text the user has selected. Also includes the current project if the session is linked to one. Note: this tool only reports open Markdown editor views — PDFs, images, canvases, and other non-Markdown files are not included. Use read_file for those.

What files do I have open?
Look at what I'm working on and help me with the current file
What do I have selected?

The agent uses this to understand your workspace context without needing files to be manually added to the session. Use read_file to get the actual content of specific files the agent identifies.

Vault operations

write_file

Create or update files:

Create a new note called "Meeting Minutes"
Update my todo list with these items

delete_file

Move files or folders to Obsidian's trash (requires confirmation). The exact destination depends on your Obsidian "Deleted files" setting — system trash, the vault's .trash folder, or permanent deletion if you've configured it that way. Folder deletions are recursive.

Delete the old draft file
Remove temporary notes from yesterday

append_content

Add text to the end of a file without rewriting the entire content. Ideal for logs, journals, and incremental updates:

Add today's entry to my daily log
Append the meeting action items to the project tracker

update_frontmatter

Safely modify note properties (frontmatter) without touching the body content:

Set the status property to "complete" on my project note
Add the "reviewed" tag to all meeting notes

move_file

Move or rename files:

Move completed tasks to the Archive folder
Rename "Untitled" to "Project Proposal"

create_folder

Create a new folder in your vault:

Create a "Meetings/2026" folder for this year's meeting notes

update_memory / read_memory

Append to or read your vault's AGENTS.md memory file. The agent uses these to remember vault-wide context — folder layout, naming conventions, user preferences — across sessions:

Remember that I keep all meeting notes under "Meetings/" by quarter
What do you remember about my vault?

update_memory requires confirmation; read_memory is read-only. The "Initialize vault context" button is the seed that creates AGENTS.md in the first place.

Web & Research Operations

All four tools in this section (google_search, google_maps, fetch_url, deep_research) are available on the Gemini provider only — they're hidden when Ollama is the active provider. See the Provider Capabilities reference for the full matrix.

google_search

Search the web for current information:

Search for the latest Obsidian plugin development docs
Find recent research on productivity methods

google_maps

Look up real-world places and location information grounded in Google Maps — businesses, points of interest, addresses, opening hours, ratings/reviews, and "near me" style questions. Returns an answer with inline citations and links to the places referenced. Include the location in your request for the best results. Available on the Gemini provider only.

Find highly-rated ramen near Union Square, San Francisco
What are the opening hours for the British Museum?
Coffee shops within walking distance of the Ferry Building

fetch_url

Retrieve and analyze web page content:

Get the content from this documentation page
Analyze this blog post and summarize key points

deep_research

Conduct multi-source research with citations and (optionally) save the report to your vault. Distinct from google_search — Deep Research runs iterative multi-turn investigation that takes minutes rather than seconds. By default it runs as a background task so it doesn't block the conversation; the agent only waits inline when the report is the direct answer to your current question. See the Deep Research guide for scope options (web_only, vault_only, both), background mode, and example prompts.

Research the latest developments in quantum error correction and save it to Research/quantum.md

generate_image

Generate an image from a prompt and save it to your vault. The agent picks a default attachment path if you don't specify one. Like deep_research, it defaults to running as a background task — the agent only generates inline when the image needs to appear in the same turn. Available on the Gemini provider only.

Generate a watercolor diagram of a Zettelkasten workflow and embed it in my notes

Vault Search

vault_semantic_search

Search your vault by meaning, not just keywords, via the indexed File Search Store. Available when Semantic Vault Search is enabled. The agent uses this automatically when a question calls for concept-based retrieval; you don't need to invoke it directly.

Find my notes about machine learning algorithms
What did I write about project deadlines in my work folder?

Session Memory

recall_sessions

Search past agent sessions by file, project, or topic. The agent uses this tool proactively to maintain continuity across sessions — you don't need to explicitly ask it to remember. It will automatically check for relevant past sessions when you're working on files or topics that have prior history.

What did we discuss about the magic system last time?
Find sessions where we worked on the API integration
Show me past sessions for the Novel project
Continue where we left off on the character outline

Returns session summaries with title, date, files accessed, and project linkage. The agent can then read the full conversation from a past session using read_file on the returned historyPath. This enables continuity-aware conversations where the agent remembers prior decisions, approaches, and context.

Skill Tools

Gemini Scribe supports an extensible skills system based on the agentskills.io specification. Skills are self-contained packages of instructions that give the agent specialized knowledge and workflows. If you're wondering whether to use a skill or a custom prompt, see the comparison in the Skills guide.

How Skills Work

Skills are stored in your plugin state folder at gemini-scribe/Skills/. Each skill is a directory containing a SKILL.md file with instructions the agent can load on demand. The agent automatically knows which skills are available — their names and descriptions are included in every agent session.

When the agent encounters a task that matches an available skill, it will activate the skill to load its full instructions before proceeding.

activate_skill

Load a skill's full instructions or resources:

Activate the code-review skill and review my latest note
Use the meeting-notes skill to process my meeting notes

You can also ask the agent to load specific resources from a skill:

Load the reference docs from the code-review skill

create_skill

Create new skills from your conversations:

Create a skill called "daily-review" that helps me review and organize my daily notes

The agent will create a properly formatted SKILL.md file with the name, description, and instructions you provide. Skills you create will be available in all future sessions.

edit_skill

Update an existing skill's description, instructions, or both:

Update the meeting-notes skill to also extract key decisions
Change the description of my code-review skill

The agent reads the current skill content (via activate_skill), then uses edit_skill to write the updated description or body. You can update either field independently — omitting one preserves the existing value. Requires user confirmation before writing.

SKILL.md Format

Each skill follows a simple format — YAML frontmatter with a name and description, followed by markdown instructions:

---
name: my-skill
description: >-
  Description of what this skill does and when to use it.
---
# My Skill

Step-by-step instructions for the agent...

Skills can also include optional subdirectories:

• references/ — Detailed reference documents
• assets/ — Templates, data files
• scripts/ — Reference scripts (read-only in Obsidian)

Discovering Available Skills

The agent automatically knows which skills are installed. Simply ask:

What skills do you have available?

Session Configuration

Session-Level Settings

Override global settings for specific conversations:

1. Click the settings icon next to session name
2. Configure:
   • Model (e.g., switch to Gemini 2.5 Pro for harder reasoning)
   • Temperature (creativity level)
   • Top-P (response diversity)
   • Custom prompt template

Permissions

Set session-specific permissions:

• Bypass confirmations for trusted operations
• Temporarily enable additional tools
• Restrict access for sensitive sessions

Tool Confirmations

When the agent needs to perform operations that require your approval (like creating, modifying, or deleting files), an in-chat confirmation request appears directly in the conversation.

How Confirmations Work

Instead of popup modals, confirmation requests appear as interactive messages in the chat:

🔒 Permission required

📝 Write File
Vault operation • Requires Confirmation

Create or update a file in the vault

Parameters:
• path: "notes/Meeting-Summary.md"
• content: "# Meeting Summary..." (1,234 chars)

[✓ Allow] [✗ Cancel] [☑ Don't ask again this session]

Confirmation Actions

✓ Allow - Approve this operation

• The agent proceeds with the operation
• Confirmation message updates to show approval
• The agent continues with subsequent steps

✗ Cancel - Decline this operation

• The agent cancels the operation
• Confirmation message updates to show cancellation
• The agent may explain why it cannot continue or suggest alternatives

☑ Don't ask again this session - Create session-level permission

• Check this box before clicking Allow
• The agent won't request confirmation for this tool again during the current session
• Useful for repetitive operations you trust
• Important: Permission resets when you create a new session or restart Obsidian

After You Respond

Once you click a button, the confirmation request updates to show the result:

✓ Permission granted: Write File was allowed

or

✗ Permission denied: Write File was cancelled

Diff view for File Changes

When the agent proposes file changes (via write_file, append_content, create_skill, or edit_skill), the confirmation card includes a View changes button that opens a side-by-side diff view. This lets you:

• See exactly what will change before approving
• Edit the proposed content directly in the diff view before clicking Allow
• If you modify the content, the tool result reports userEdited: true so the agent knows

Enable "Always show diff view for file writes" in settings to automatically open the diff view with every confirmation instead of requiring a button click.

What Operations Require Confirmation

By default, these operations require confirmation:

• write_file: Creating or modifying files
• delete_file: Removing files
• move_file: Moving or renaming files
• append_content: Adding text to the end of files
• update_frontmatter: Modifying note properties (frontmatter)
• create_folder: Creating new folders
• create_skill: Creating new skill packages
• edit_skill: Updating existing skill instructions
• generate_image: Generating and saving images
• update_memory: Updating vault memory (AGENTS.md)
• google_search, google_maps, fetch_url, deep_research: External web/research calls (Gemini provider only)

You can configure which operations require confirmation in Settings → Gemini Scribe → Tool permissions (enable Show advanced settings first).

Session-Level Permissions

When you check "Don't ask again this session" and click Allow:

1. The permission is remembered for the current session only
2. Future uses of that tool won't prompt for confirmation
3. Other tool types still require confirmation (unless you've also allowed them)
4. The permission is cleared when you:
   • Create a new session
   • Load a different session
   • Restart Obsidian

Use case example:

User: Organize my daily notes into monthly folders

[Agent requests permission to move first file]
🔒 Permission required - Move File
[You check "Don't ask again this session" and click Allow]

[Agent proceeds to move all remaining files without additional prompts]

Reviewing Confirmation Details

Before clicking Allow, always review:

1. Tool Name: What operation the agent wants to perform
2. Parameters: File paths, content snippets, and other details to verify
3. File Paths: Ensure paths are correct and won't overwrite important files
4. Content Preview: Check the content looks reasonable (for write operations) Example - Be careful with destructive operations:

🔒 Permission required

🗑️ Delete File
Vault operation • Requires Confirmation

Delete a file from the vault

Parameters:
• path: "important-research.md"  ⚠️ Double-check this path!

[✓ Allow] [✗ Cancel] [☑ Don't ask again this session]

Best Practices for Confirmations

1. Start Cautious: Don't use "Don't ask again" until you trust the agent's behavior for your specific task
2. Review File Paths: Always check paths before allowing file operations
3. Read-Only First: Test with read-only operations before allowing writes
4. Backup Important Data: Have backups before bulk operations
5. Cancel and Clarify: If unsure, click Cancel and ask the agent to explain what it's trying to do
6. Session Scope: Remember that "Don't ask again" only applies to the current session

Best Practices

1. Start with Read-Only

Begin with read-only operations to understand how the agent works:

Show me all my notes tagged with #important
Find notes I haven't updated in 30 days
Search for broken links in my vault

2. Use Clear Instructions

Be specific about what you want:

Good: "Create a weekly summary of all notes tagged #meeting from the past 7 days"
Less clear: "Summarize my meetings"

3. Review Before Confirming

When in-chat confirmation requests appear:

• Read the tool name and operation type
• Review all parameters (especially file paths)
• Check content previews for write operations
• Ensure you have backups for destructive operations
• See the Tool Confirmations section for detailed guidance

4. Leverage Context Files

Add relevant files as context for better results:

• Template files for consistent formatting
• Style guides for writing tasks
• Reference documents for research

5. Use Sessions Effectively

• Create new sessions for different projects
• Name sessions descriptively
• Review session history for insights

Advanced Usage

Plan Mode

Plan mode lets you review what the agent intends to do before any tools are executed. This is useful for high-stakes workflows where you want to understand and approve the approach before the agent starts making changes.

How to use Plan Mode:

1. Click the checklist icon in the input toolbar to toggle plan mode on. When active it becomes an accent-colored Plan pill.
2. Type your request and send it as normal.
3. The agent responds with a plan describing the steps it will take — but does not execute anything yet.
4. Review the plan. Click Approve & Execute to proceed with full tool access, or Reject to cancel without changes.
5. After approval, the agent executes the plan automatically. Plan mode turns off after each request.

When to use Plan Mode:

• Before bulk operations (renaming, reorganizing, or deleting many files)
• When trying a new complex workflow for the first time
• Whenever you want to verify the agent's interpretation before it acts

Plan entries are saved to session history with a distinct purple border so you can review approved plans later.

Multi-Step Workflows

The agent excels at complex, multi-step tasks:

User: Organize my research notes. Group them by topic, create an index, and archive anything older than 6 months.

Agent: I'll help organize your research notes. This will involve:
1. Finding all research notes
2. Analyzing their topics
3. Creating topic-based folders
4. Moving files to appropriate folders
5. Creating an index file
6. Archiving old notes

Let me start by searching for research notes...
[Executes multiple tools in sequence]

Template-Based Operations

Use templates for consistent results:

User: Create a new project using my project template

Agent: I'll create a new project structure for you.
[Reads template]
[Creates folder structure]
[Populates with template files]
[Updates project index]

Research Assistant

Combine vault and web operations:

User: Research productivity methods and create notes for the most promising ones

Agent: I'll research productivity methods and create notes.
[Searches web for productivity methods]
[Fetches relevant articles]
[Creates structured notes]
[Links to existing notes]

Safety Features

Protected Folders

The following folders are automatically protected:

• .obsidian/ - Obsidian's configuration folder (or your renamed config directory)
• gemini-scribe/ - Plugin state files
• Any folder containing plugin data

Loop Detection

Prevents infinite execution loops:

• Detects repeated identical operations
• Stops after threshold (default: 3)
• Configurable time window

Turn Budget

Long agent turns (many tool-call batches in a row) are bounded by a soft budget instead of a hard cutoff:

• As a turn nears its limit, the agent is reminded how many tool-call batches it has left so it can wrap up cleanly
• If it runs out mid-task, it gets a one-time extension (half the original budget, rounded up) with a nudge to finish
• Interactive agent chat sessions default to 50 tool-call batches per turn — high enough to stay out of the way of normal multi-step work
• See Scheduled Tasks → Tool Iteration Limit for the same mechanism as it applies to headless runs (default 20, configurable via maxIterations)

Error Handling

• Operations stop on errors (configurable)
• Clear error messages explain failures
• Non-destructive fallback behaviors

Confirmation System

• In-chat confirmation requests for vault operations (create, modify, delete, move)
• Interactive buttons to Allow or Cancel each operation
• Review tool details and parameters before approving
• "Don't ask again this session" option for repetitive trusted operations
• Session-level permissions reset when session ends
• See Tool Confirmations for complete workflow details

Troubleshooting

Agent Not Responding

1. Verify API key supports function calling
2. Ensure selected model supports tools (all current Gemini models do)

Tools Not Available

1. Check tool category is enabled in settings
2. Verify session has proper permissions
3. Some tools may be incompatible with search grounding

Operations Failing

1. Check file paths are correct
2. Ensure you have vault permissions
3. Verify files aren't open in other applications
4. Check for protected folder restrictions

Performance Issues

1. Reduce number of context files
2. Use more specific search patterns
3. Break complex tasks into steps
4. Consider using faster models for simple tasks

Examples and Recipes

Daily Review

Review all notes modified today, summarize key points, and update my daily journal

Knowledge Management

Find all notes without tags, analyze their content, and suggest appropriate tags

Content Creation

Create a blog post outline based on my notes about [topic], then draft the introduction

Vault Maintenance

Find duplicate notes, broken links, and orphaned files, then create a cleanup report

Research Project

Search for information about [topic], create structured notes, and link to relevant existing notes

Tips and Tricks

1. Save Useful Prompts: Keep a note with prompts that work well
2. Chain Operations: Use "then" to connect multiple tasks
3. Iterate Gradually: Start simple and add complexity
4. Use Naming Conventions: Consistent file names help the agent
5. Review History: Learn from past sessions
6. Set Boundaries: Use permissions to stay in control
7. Backup Important Data: Before major operations
8. Experiment Safely: Use a test vault for learning

Future Possibilities

As agent mode evolves, consider these use cases:

• Automated vault organization
• Intelligent note linking
• Research automation
• Content generation pipelines
• Knowledge graph analysis
• Workflow automation

Remember: The agent is a powerful tool, but you remain in control. Use it to augment your thinking, not replace it.

Further Reading

• What I Did On My Summer Vacation — The story behind Agent mode's development
• Everything Becomes an Agent — How every AI project evolves into an agent, and the patterns behind tools, memory, and autonomy
• Gemini Scribe: From Agent to Platform — The evolution from chat plugin to AI platform, covering projects, skills, MCP, and the philosophy of seamless AI integration