Agent Threads documentation

Agent Tools Reference

Every MCP tool available inside a Claude thread — vault, UI, session, thread-coordination, Vault Bridges, and Skills Manager tools.

Every thread runs with built-in tools for vault access, session control, and — for multi-agent workflows — live coordination with other threads. Claude receives them through the host-neutral claude_threads MCP server; Codex receives the supported canonical definitions through its dynamic-tool protocol. No configuration is required.

The former obsidian server and obsidian_* names remain callable as deprecated compatibility aliases until the next major release. New prompts, permission rules, and automation should use the canonical names below.

Vault tools

Read and search your vault from within any thread.

ToolParametersDescription
vault_searchquery, limit?Full-text search across all Markdown files. Tokenizes multi-word queries so each term is matched independently. Returns results ranked by relevance (filename hits weighted 10×) with a ~300-char excerpt from the densest matching region. Default limit: 20.
vault_get_note_metadatapathReturns the full metadata cache entry for a note: frontmatter, tags, wikilinks, and headings.
vault_get_backlinkspathReturns all notes that link to the specified file, with source path and original link text.
vault_get_outgoing_linkspathReturns all wikilinks and Markdown links a note makes to other files, with display text and resolved vault paths.

Workspace and host tools

Interact with the active Obsidian or Geode workspace.

ToolParametersDescription
workspace_get_active_file—Returns metadata (path, basename, extension, size, mtime, ctime) for the file currently open in the editor, or null if nothing is open.
workspace_get_open_tabs—Returns all open tabs with path, title, view type, and which one is active.
workspace_navigate_to_filepath, newLeaf?Opens a vault file in the editor. Pass newLeaf: true to open in a new tab.
workspace_insert_at_cursortextInserts text at the cursor in the active editor, replacing any current selection.
host_list_commandsquery?Returns all registered host commands (id + name), sorted alphabetically. Pass a query string to filter. Use this to discover command IDs before calling host_execute_command.
host_execute_commandcommandIdRuns any host command by its ID (e.g. obsidian-git:push, editor:toggle-bold). Third-party command IDs are unchanged.
host_open_urlurl, newTab?Opens a URL in the host Web Viewer panel. Reuses an existing tab by default; set newTab: true to force a fresh tab.

Session tools

Control the current thread’s session state.

ToolParametersDescription
set_working_directorypathChanges the working directory for this session. Accepts an absolute path; ~ is expanded. Takes effect on the next turn.
EnterDesignModebriefContributed by the separate Design for Agent Threads desktop plugin. Creates or reuses the calling thread’s static design artifact, focuses that thread, and opens its preview and artifact controls. Returns artifact paths and design instructions so Claude or Codex can continue in the same turn. Requires a nonblank brief, a desktop filesystem vault, and write permission; unavailable during Plan mode or pending plan approval. See Design artifacts.
EnterPlanMode—Requests Plan mode without asking for permission. For Codex, the current turn hands off at a safe boundary and Agent Threads starts one fresh native Plan collaboration turn under a read-only sandbox; its structured plan opens the existing Approve/Edit/Reject card. Claude uses its native plan-mode capability for the equivalent transition.
ScheduleWakeupdelaySeconds, prompt, reasonSchedules a message to be injected into this thread after a delay. Useful for polling CI, waiting for a deploy, or self-pacing a loop. While the wake-up is pending, the Agents List and Agent Board keep the thread in Waiting with a live countdown (Resumes in 4m — <reason>). In the conversation, a compact scheduled-activity pill shows the countdown instead of a permanent banner; click it to inspect all wakeups and loops for the thread and cancel only the selected wakeup. Wakeups are persisted to disk (the same durable store backing Scheduled Tasks), so a pending wakeup survives an Obsidian restart, plugin reload, or the machine sleeping — it fires on schedule, or immediately on next load if the fire time already passed.
EnterWorktreebranch?, baseBranch?, repoPath?Creates a git worktree for the current repo and switches the session cwd to it. Automatically routed to the plugin’s MCP implementation, which tracks the in-session cwd correctly after set_working_directory.
ExitWorktreeworktreePath?, force?Removes the worktree and restores the session cwd to the original repo root. Defaults to the current effective cwd. Pass force: true to remove even if there are uncommitted changes.
request_secretsecretName, reason, force?Prompts the user (via a modal) to provide a secret value such as an API key. The value is stored in the OS keychain under the plugin’s namespace and injected into future sessions as an environment variable — it never appears in the conversation. On success, the calling thread’s live session is also flagged to restart at its next turn (conversation history is preserved via session resume), so the new secret becomes available to this same thread right away rather than only in later sessions. Returns {success: true, secretName, alreadyExisted: boolean} if the user saves, or {success: false, reason} if cancelled. If a secret with the same name already exists, returns alreadyExisted: true immediately without prompting. Pass force: true to always re-prompt (e.g. when rotating a stale token) — the modal will indicate that the existing value will be replaced.
mcp_register_servername, type, command?, args?, env?, url?, headers?Proposes a global external stdio, http, or sse MCP server and saves it only after a separate host confirmation. Registration is create-only: an identical retry is an unchanged no-op, while a different configuration under the same name is rejected. Credentials must use ${VAR_NAME} placeholders and be collected with request_secret. It affects newly initialized sessions, never hot-loads the current session, and is unavailable to scheduled or noninteractive threads. See Managing MCP Servers.
watch_documentpathWatches a vault note for content changes, owned by the calling thread. Any subsequent edit — from you, another thread, or a sync — sends this thread an injected alert message referencing the file via an @[[filename]] mention. Re-watching an already-watched path is a no-op that keeps the existing watch. See Watch a document.
unwatch_documentpath?, id?Removes a watch owned by the calling thread, by path or watch id (at least one required). Never affects another thread’s watch on the same path.
list_watched_documents—Returns the calling thread’s own active watches: path, watch id, creation time, and last-alerted time.

Sandbox VM tools

On macOS 26+ with Apple silicon, agents can run coding commands in a separate Linux VM. See Sandbox VMs for setup, network modes, and the writable workspace boundary. Ordinary host shell and file tools remain on the host.

ToolParametersDescription
enter_vmimage?, network?, mountPath?Starts the thread’s VM and mounts its working directory at /work; your vault is also mounted read-write at /vault, and Geode external roots read-only at /ext/<label>. Network choices are default (internet enabled), internal (host-only), or none.
vm_execcommand, timeoutSeconds?Runs a command inside the VM, returning exit code and bounded stdout/stderr. Default timeout: 300 seconds.
host_execcommand, cwd?, reason, timeoutSeconds?Runs one command on the Mac host from an interactive, VM-routed Claude thread after a required Allow once approval; scheduled and other non-interactive calls are denied. It is not exposed on host fallback, mobile, Codex, OpenCode, or the deprecated obsidian alias. See Host commands from a VM-routed Claude thread.
exit_vmforce?Removes the thread’s VM. Writes to the mounted host workspace persist. enter_vm and exit_vm are not offered in container-routed Claude sessions, where the harness already runs inside the container.
github_list_access—Lists the GitHub repositories the connected Geode GitHub App can access (names only, never credentials). Requires Geode with GitHub connected.
github_check_reporepoChecks whether the Geode GitHub App can access owner/name; if not, returns the install URL to grant access.

Thread coordination tools

Discover, read, and message other running threads. These tools enable agent-to-agent delegation — one thread can assign work to another, wait for it to finish, and read the result.

Project threads coordinate only within their Project, and threads with no Project coordinate with each other. One narrow exception applies to threads_set_project: a thread with no Project may place itself into any Project. Nothing else can — so without it, a thread that creates a Project could never join it. This is an escape hatch out of statelessness, not a scope hop: it does not let a thread move anyone else, and it does not let a Project thread hop to a different Project.

ToolParametersDescription
threads_get_current—Returns this thread’s metadata, live status, project, cwd, PR, schedule origin, raw-log path, and message count.
threads_getthreadId, recentMessages?, elevatedProjectId?Returns one thread’s full snapshot in O(1) — including goal, managerNotes, proposedReply, pendingDecisions, parsed v2 triage metadata, and optionally the last N messages (recentMessages, up to 50). Canonical-only read tool.
threads_listprojectId?, view? ("full" | "triage")Returns authorized thread metadata. Pass view: "triage" during orchestrator heartbeats to receive compact parsed v2 triage summaries (outcome, strategy, disposition, needsReview, pending counts) without multi-line note or proposal bodies. The Portfolio Orchestrator passes a Project id for explicit one-call elevation.
threads_createprompt, title?, cwd?, projectId?Creates an independent thread, queues its initial prompt immediately, and returns {threadId, title} without waiting for the thread to finish. Omitted cwd and projectId inherit from the calling thread; pass projectId: null to create the thread without a project. Spawning into a different project or working directory asks you first — see Cross-project spawns.
threads_list_projects—Returns configured Projects, including each vaultFolder, optional cwdOverride, and resolved effectiveCwd.
threads_create_projectname, vaultFolder, description?, cwdOverride?Creates and persists a project.
threads_update_projectprojectId, name?, description?, cwdOverride?, elevatedProjectId?Durably updates the caller’s Project name, context description, or cwd override and returns the complete updated Project snapshot, including its resolved effectiveCwd.
threads_set_projectthreadId, projectId, alignCwd?Assigns a thread to a Project, or detaches it with null. Association-only by default; alignCwd: true switches to a non-null Project’s cwd on the next safe turn. Detaching never relocates the thread. A thread with no Project may target itself with any Project id; every other caller is held to normal coordination scope.
threads_get_messagesthreadId, limit?Returns recent user and assistant messages.
threads_openthreadId, elevatedProjectId?Opens and focuses the exact thread UUID. A successful open marks it reviewed and persists the active selection.
threads_get_logthreadId?, limit?, type?Returns parsed JSONL event-log entries. Codex logs compact redundant streaming events and retain completed records plus bounded diagnostics; see Log retention.
threads_waitthreadId, timeoutSeconds?Waits until a target thread becomes idle.
threads_send_messagethreadId, messageQueues a message on another thread and triggers it.
threads_archivethreadId, confirm?, elevatedProjectId?Saves and removes a completed thread. A scheduled thread may target itself; the tool acknowledges with deferred: true. Archiving any referenced orchestrator requires confirm: true.

Project members and Project Orchestrators coordinate only inside their Project. Unassigned threads coordinate only with unassigned threads. The Portfolio Orchestrator sees unassigned work by default and must provide a matching projectId/elevatedProjectId on each raw cross-Project call. Project manager notes remain owned by the Project Orchestrator even during portfolio elevation.

For threads_update_project, projectId is required and at least one editable field must actually change. name is trimmed and must remain nonblank. Omitted fields are preserved; pass null for description or cwdOverride to clear that field. A non-null cwdOverride is trimmed and must be an absolute filesystem path. Project members and Project Orchestrators may update their own Project; unassigned and cross-Project callers are denied, while the Portfolio Orchestrator must pass elevatedProjectId matching the target. Existing threads keep their current cwd and live session. New Project threads and dynamic Project schedules resolve the updated cwd, and newly initialized sessions receive updated context. The deprecated compatibility name is obsidian_update_project on the former obsidian server.

This tool updates stored Project configuration only. Automatic vault-relative/repo-relative path disambiguation is a separate product follow-up and is not injected by this feature.

ToolParametersDescription
threads_set_notesthreadId, notes, elevatedProjectId?Sets orchestrator tracking notes. Portfolio may pass elevatedProjectId when that Project’s orchestrator is disabled.
threads_get_ledgerprojectId?, elevatedProjectId?Reads the caller-authorized Tier 2 cross-thread campaign ledger note (Products/<Project>/orchestrator-ledger.md or Products/Portfolio/orchestrator-ledger.md). Canonical-only read tool.
threads_set_ledgercontent, projectId?, elevatedProjectId?Writes (or clears with "") the caller-owned Tier 2 cross-thread campaign ledger note in the vault (up to 64 KiB, secret-redacted at rest) without requiring filesystem Write/Edit tools.
threads_set_proposed_replythreadId, textStages a proposed reply for human approval, rendered inline in the thread’s Chat view and on its Agent Board card.
threads_clear_proposed_replythreadIdClears a stale proposed reply.
threads_post_decisionthreadId?, question, options, header?, multiSelect?, allowOther?Posts a decision card (2–4 { label, description? } options plus optional free-text Other, labeled with the posting orchestrator’s title) inline in the thread’s Chat (conversation) view and on its Agent Board card (defaults to the calling thread). Send answer delivers your choice to the calling orchestrator thread as a user message — never into the target thread’s context. Returns a decisionId. Pending decisions on a thread are dismissed automatically if you manually send a message to that thread yourself, while automated or agent sends (threads_send_message, wakeups, heartbeats) leave them intact.
threads_clear_decisiondecisionId, threadId?Withdraws a pending decision card posted with threads_post_decision (defaults to the calling thread). Only the author that posted the decision can clear it.

These five tools (threads_set_notes, threads_set_proposed_reply, threads_clear_proposed_reply, threads_post_decision, and threads_clear_decision) back the bundled thread-orchestrator skill (resources/skills/thread-orchestrator), which lets one thread supervise several peers: it tracks per-thread notes across polling passes, posts directional decisions when blocked on a choice only you can make, and proposes replies for human review rather than sending on a peer’s behalf. See Project and Portfolio Orchestrators.

isRunning vs status: status is a persisted field (waiting, active, error, archived, reconnecting) that reflects the last known state. isRunning is a live flag that is true only while Claude is actively streaming a response. Use isRunning for coordination decisions; use status to filter out archived or errored threads. reconnecting is a transient state covering two auto-recovered failure modes: either the underlying claude CLI transport was force-closed mid-tool-call (a spurious “Stream closed” error) and the plugin is auto-firing one follow-up turn so Claude can verify whether the interrupted action actually succeeded, or the API rejected the turn with a rate-limit/overload error and the plugin is silently retrying the same turn after a backoff delay. Either way it is not necessarily a real failure — treat it as in-flight, not errored. See Errors and auto-retry for the full behavior.

Coordination pattern

A typical delegation loop:

  1. Call threads_create with a prompt to create and immediately assign a dedicated thread, or call threads_list to find an existing peer
  2. For an existing peer, call threads_send_message to assign the task
  3. Call threads_wait to block until the peer finishes
  4. Call threads_get_messages to read the result

This pattern works across any combination of threads — you can fan out to multiple peers simultaneously by sending messages to several threads before waiting on any of them.

Cross-project spawns

threads_create can start a thread in a different project folder by passing cwd or projectId. Because that puts a new agent to work outside the calling thread’s own project, you are asked to approve it. Approval is requested when the target differs from the calling thread:

  • a different projectId,
  • an explicit cwd that differs from the caller’s, or
  • projectId: null from a project-scoped thread.

The standard permission card appears, titled Spawn thread in another project. It shows the target project, the working directory, and the first line of the prompt. See Permissions for the card.

  • Allow creates the thread.
  • Deny creates nothing, and the agent receives the error Cross-project spawn was denied by the user.
  • Always Allow lets later cross-project spawns through without prompting. Revoke it from the always-allowed tools list in the plugin settings.

Spawns that stay in the caller’s own project remain automatic. The coordination-scope rules above still apply first, so a spawn they already forbid is refused before any card is shown.

Tools from other plugins on a daemon

Peer plugins such as Design add their own tools to your threads (for example EnterDesignMode). Threads that run on a daemon get them too, through the Tools from other plugins option.

  • Local (container) daemon: on by default, together with the read groups, mcp and host_exec. A new local daemon entry already has it ticked.
  • Daemons you add yourself: off. In Settings, Remote, edit daemon, Advanced, switch on Tools on this computer and tick Tools from other plugins.
  • Turning it off: untick the option. On the local daemon this is remembered, so the default does not switch it back on.
  • Only tools registered when the thread starts are offered; a plugin you enable later appears on the next thread session. Tools that change something still show an approval card in the app, and tools that write, schedule or touch secrets stay unavailable to a daemon whatever you tick.

Peer-plugin voice lifecycle tools

Obsidian Orchestrator consumes the public voice-orchestration bundle, which is separate from the internal threads_* tools above. Capable hosts expose:

ToolParametersBehavior
ct_archive_threadthread_idArchives the exact discovered thread ID, awaiting wakeup cancellation and persistence. Running threads and orchestrators require a host confirmation dialog; the last remaining thread is protected. Reports cancellation separately from success.
ct_mark_reviewedthread_idMarks an idle thread reviewed and saves it without changing the active tab. Repeated calls are safe; running or missing targets fail.

Say “Archive [thread name]” or “Mark [thread name] reviewed.” Orchestrator resolves the ID and clarifies ambiguous matches. Both calls and their results appear in its transcript. Older hosts omit these tools; start a new voice session after updating or reloading Agent Threads. Archived conversations are saved as vault notes only with saveThreadsToVault enabled. See Peer Plugin API v1 for the trusted-plugin boundary and result contracts. Internal self-archive rules are unchanged.

Vault Bridges integration

If you have the Vault Bridges plugin installed, Claude agents can inspect and configure bridges directly via MCP — no config-file editing or Obsidian restarts required.

ToolParametersDescription
vault_list_bridges—Returns all currently configured bridges. Agents should call this first to check what already exists before adding a new one.
vault_add_bridgename, repoPath, vaultPath, sourcePath?, branch?, autoSync?, syncNow?Adds a new bridge live via the Vault Bridges API. The bridge is registered immediately — the status bar updates, per-bridge push/pull commands are wired up, and settings are saved. If a bridge with the same repoPath + vaultPath already exists, the existing record is returned without creating a duplicate.

Both tools return a clear error if the vault-bridges plugin is not installed or not enabled.

Bridge-aware edits

When an agent edits files inside a bridged repo (rather than the synced vault copy), Agent Threads detects it automatically at the end of the turn:

  • Auto-pull — each affected bridge is synced once per turn, so the vault copies update immediately (a notice confirms success or failure).
  • Vault-relative links — edited-file chips, the focus button, and absolute repo paths in Claude’s messages all resolve to the synced vault note: chips show the vault path and open the note in Obsidian, and message paths become clickable internal links (only when the vault copy exists).

Edits made directly to vault files are unaffected — they don’t match any bridge root and behave as before. Note that edits made inside a temporary coding-task worktree only reach the vault after merge plus a normal bridge pull.

Skills Manager tools

Everything the Skills Manager panel can do — browse the skills.sh registry, inspect installed skills and configured sources, check for updates, install, uninstall — is also available to agents via MCP, so a thread can manage its own skill packages without a human clicking through the UI.

ToolParametersDescription
skills_list_installed—Lists skills currently installed in ~/.claude/skills/: name, description, install path, and which configured skill source (if any) each came from.
skills_searchquery, limit?Searches the skills.sh marketplace registry. Returns each match’s name, slug, GitHub source, install count, and whether it’s already installed. Default limit: 15.
skills_getidentifierReturns full detail for one skill, whether installed or not. Pass an installed skill’s name, or a marketplace slug in owner/repo/skill-id form (as returned by skills_search). Installed skills include their full SKILL.md content.
skills_list_sources—Lists configured skill sources (GitHub-cloned or local-path plugin sources) plus the built-in skills.sh registry, with id, name, type, and (for GitHub sources) staleness info.
skills_check_updates—Checks every configured GitHub-type skill source for upstream commits it’s behind (git fetch + count). Returns each source’s id, name, and either its refreshed behindCount/lastFetched or an error if the check failed (e.g. offline).
skills_installslug, skillId, source, nameInstalls a marketplace package in the vault’s plugin-managed skills/ folder. Pass the four fields from skills_search.
skills_uninstallnamePermanently deletes an installed or authored vault package. Use a qualified identifier from skills_list_installed when names overlap. Home skills are read-only.
skills_create_localskillId, skillMd, files?Creates a complete authored package in the configured vault folder, default Skills/. Available in new sessions.
skills_update_localskillId, files?, deleteFiles?Patches an authored package, preserves omitted files, and protects SKILL.md from deletion.
skills_updatesourceIdPulls the latest commits for a configured GitHub-type skill source (git pull on its local clone), refreshing every skill it provides. Use the source id from skills_list_sources — not "registry", which has no single-source update (reinstall individual skills instead).