obsidian-plugin/logancyang_obsidian-copilot
1
0
Fork 0
mirror of https://github.com/logancyang/obsidian-copilot.git synced 2026-07-22 07:50:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
logancyang_obsidian-copilot/docs/agent-mode-and-tools.md

11 KiB
Raw Blame History

Agent Mode and Tools

Copilot Plus includes an autonomous agent that can reason step-by-step and decide which tools to use to answer your question. Instead of you specifying every step, the agent figures out what to do on its own.

This feature requires a Copilot Plus license.

Overview

When the autonomous agent is enabled, Copilot can:

  1. Break down your request into sub-tasks
  2. Use tools to gather information (search your vault, search the web, read a note)
  3. Create or edit notes
  4. Combine results and give you a comprehensive answer

Example: Ask "What did I work on last week?" and the agent will automatically search your vault for dated notes from the past 7 days, read the relevant ones, and summarize your week.

Enabling Agent Mode

  1. Go to Settings → Copilot → Plus
  2. Turn on Enable Autonomous Agent

The agent activates automatically when you're in Copilot Plus mode. You don't need to do anything special — just ask your question.

Max Iterations

The agent works in iteration cycles (think → use a tool → think → use a tool → answer). You can control the maximum number of iterations before the agent stops:

  • Default: 4 iterations
  • Maximum: 16 iterations
  • Setting: Settings → Copilot → Plus → Autonomous Agent Max Iterations

The agent also has a maximum runtime of 5 minutes per response, regardless of iteration count.

Available Tools

Copilot Plus has 13 built-in tools. Some are always active; others can be enabled or disabled.

Built-in Obsidian skills

Copilot also seeds four Obsidian-native skills for Claude, Codex, and OpenCode:

  • Obsidian Markdown — wikilinks, embeds, block references, callouts, properties, tags, and comments.
  • Obsidian Bases — valid .base schemas, filters, formulas, views, summaries, quoting, and date/duration behavior.
  • JSON Canvas — the .canvas schema, nodes, edges, groups, layout, colors, IDs, and link integrity.
  • Obsidian CLI — runtime and indexed operations such as currently open notes and tabs, workspace layout, daily notes, typed properties, tasks, backlinks, Bases queries, template resolution, link-aware moves, registered commands, and plugin debugging.

These skills appear under Settings → Copilot → Skills, where each one can be enabled or disabled per agent. Existing choices are preserved when Copilot refreshes a built-in skill.

The Obsidian CLI skill first verifies that obsidian version succeeds. The CLI requires a compatible Obsidian installer, registration, and a running Obsidian app; if it is unavailable, the agent falls back to normal filesystem operations where possible. Copilot does not change its minimum supported Obsidian version or attempt to install or repair the CLI.

When inspecting open tabs, the agent preserves Markdown notes, other file-backed tabs, and non-file views as workspace context. It reads content only from explicit vault paths reported by Obsidian and never treats a tab title or ID as a filename.

Always-Enabled Tools

These tools are always available and cannot be disabled:

Get Current Time

Gets the current time in any timezone. Useful for time-aware queries like "what should I do today?"

Get Time Range

Converts natural time expressions (like "last week" or "yesterday") into exact date ranges. Usually called automatically before a time-based vault search.

Get Time Info

Converts an epoch timestamp to a human-readable date and time.

Convert Timezones

Converts a time from one timezone to another. Ask: "What time is 3pm EST in Tokyo?"

Read Note

Reads the content of a specific note. The agent uses this to inspect a note it found via search, or that you mentioned explicitly. Works on large notes by reading them in chunks.

File Tree

Browses the file structure of your vault. The agent uses this to find folder paths before creating new notes or to count files in a folder.

Tag List

Lists all tags in your vault with usage statistics. Useful for tag reorganization or finding notes by tag patterns.

Update Memory

Saves information to your memory when you explicitly ask the AI to remember something. See Copilot Plus and Self-Host for details.

Requires: Settings → Copilot → Plus → Reference Saved Memories must be enabled. If this setting is off, the tool is not registered and memory commands will not work.

Configurable Tools

These tools can be individually enabled or disabled in Settings → Copilot → Plus → Tool Settings:

Vault Search

Searches your vault notes by content. The agent uses this to find notes relevant to your question.

  • Trigger: Automatically for vault-related questions, or explicitly with @vault
  • Uses: Both semantic search (if enabled) and lexical search

Web Search

Searches the internet for current information.

  • Trigger: Automatically when your question implies web/online content, or explicitly with @websearch or @web
  • Requires: A web search service configured (Firecrawl or Perplexity in self-host mode, or handled by Plus)

Write to File

Creates a new note or overwrites an existing one entirely.

  • Trigger: Automatically for "create a note" requests, or explicitly with @composer (available in both Copilot Plus and Projects mode)
  • Behavior: Shows a preview of the content before writing. You can review and accept or reject the change.
  • Auto-accept: Enable Settings → Copilot → Plus → Auto-accept edits to skip the preview

Replace in File

Makes targeted changes to an existing note using search-and-replace blocks.

  • Use case: Small edits (adding a bullet, updating a section) — more precise than rewriting the whole note
  • Behavior: Shows a diff preview before applying the change
  • Auto-accept: Same setting as Write to File

YouTube Transcription

Fetches the transcript of a YouTube video.

  • Trigger: Automatically when you paste a YouTube URL in your message
  • No extra setup needed: Just include the URL in your message
  • Self-host option: Use your own Supadata API key for transcription in self-host mode

Tool Settings

Go to Settings → Copilot → Plus → Tool Settings to:

  • See all available tools
  • Enable or disable individual configurable tools
  • View what each tool does

Using Tools Explicitly

While the agent automatically decides when to use tools, you can also trigger them explicitly with @-mentions:

@vault find all notes about my reading list
@websearch what is the latest version of Python?
@composer create a new meeting notes template
@memory remember that I prefer bullet points for lists

See Context and Mentions for the full @-mention reference.

Tool Call Indicators

While the agent is working, the chat shows status indicators for each tool call:

  • "Reading files"
  • "Searching the web"
  • "Reading file tree"
  • "Compacting"

This lets you see what the agent is doing as it works.

Delegated Agents and Shell Commands

For v4, Claude runs delegated agents and Bash commands synchronously. Copilot waits for each supported tool to finish within the current response so the result arrives predictably before the turn ends. This temporarily favors reliable completion over parallel background execution.

The Workflow tool and remote-isolated agents are temporarily unavailable because they require background execution. Local agents, including worktree-isolated agents, remain available and run synchronously. Background execution will return after Copilot moves Claude sessions to a persistent streaming lifecycle.

This requires Claude Code 2.1.206 or newer. Copilot checks the installed version when it starts and whenever you apply or auto-detect a Claude binary. An older binary is marked Incompatible version in Settings → Copilot → Agents → Claude and cannot start a session. If you select Claude in chat, Copilot shows the required version and a Configure Claude button that opens the same setup dialog; installation guidance stays in that dialog.

If Claude's usage is exhausted, Copilot shows Claude's own error in chat, including the reset time when Claude provides one. You can wait until the limit resets or switch to another agent.

File Editing: Preview and Diff

When the agent uses Write to File or Replace in File, it shows a preview before making changes:

  • Split view: Before/after shown side by side
  • Side-by-side view: Changes highlighted inline

You can choose your preferred diff view in Settings → Copilot → Plus → Diff View Mode.

Review the proposed change and click:

  • Accept — Apply the change to your note
  • Reject — Discard without making any changes
  • Revert — Undo a change that was already accepted

Auto-Accept Edits

If you trust the agent and don't want to review every file change, enable Auto-accept edits in Settings → Copilot → Plus. File changes will be applied immediately without a confirmation step.

Reporting an Issue

When something goes wrong in Agent Mode, the Report an Issue button under Settings → Copilot → Advanced → Agent Mode debugging bundles everything a maintainer needs to diagnose it.

Clicking it opens a short form where you describe what happened. When you submit, Copilot:

  1. Saves a screenshot of the Agent Mode chat pane (just the agent panel, not your whole screen).
  2. Saves a recent Agent Mode log of the behind-the-scenes messages between Copilot and the agent. This log is captured automatically so a report always has recent activity to include; you can turn it off under Settings → Copilot → Advanced → Keep an Agent Mode activity log.
  3. Opens the folder containing those files in your file manager.
  4. Opens a prefilled GitHub issue in your browser.

The files are not uploaded for you — drag them from the opened folder into the GitHub issue to attach them.

Privacy note: The Agent Mode log can contain your prompts, note contents, and tool inputs/outputs in plaintext. Review the saved files before sharing them publicly.

Including the OpenCode log

When the OpenCode backend is active, the form shows an optional checkbox to include OpenCode's own log. It is off by default because OpenCode's log is shared across all of your OpenCode sessions, so it may contain activity from unrelated projects. Turn it on only when the issue involves the OpenCode backend itself.

This feature is available on desktop only.

Related