Plugin Bridges

Plugin Bridges

Many tools reach Obsidian plugins through the companion plugin, which extends the Local REST API plugin with /obsidian-tc/v1/* routes. Direct file ops (read_note, write_note, search over the cache, …) work through the Local REST API plugin alone; bridge tools additionally need the companion plugin plus the specific third-party plugin.

Dependency chain

Obsidian app                 (always required)
  Local REST API plugin       (always required - HTTP entry to the vault)
    Companion plugin          (required for command palette + ANY bridge tool)
      Dataview                -> search_dql, validate_dql, eval_dataview_field
      Tasks                   -> tasks_filter
      Templater               -> list_templates, execute_template
      QuickAdd                -> list_quickadd_actions, trigger_quickadd
      Text Extractor          -> ocr_attachment, ocr_bulk
      Smart Connections       -> embeddings via the SC bridge (optional)
      Smart Context           -> bundle_folder, bundle_files
      Excalidraw              -> excalidraw tools
      Periodic Notes          -> periodic_note tools
      Workspaces (core)       -> workspace tools
      Bookmarks (core)        -> bookmark tools
      make-md                 -> makemd_list_spaces, makemd_query

A tool that fails any link in the chain returns plugin_missing with the specific plugin in details.plugin (or plugin_unreachable if the plugin is present but its endpoint times out).

Companion plugin

A standard Obsidian plugin (obsidian-tc) that owns command-palette dispatch, active-file access, and the per-plugin bridge endpoints. It declares obsidianTcApiVersion: "1"; the server reads this from the probe and refuses to dispatch on a major mismatch. Routes are path-versioned (/v1/) so a future /v2/ can ship alongside.

Discovery probe

At server start (and on reload_vault) the server fires GET /obsidian-tc/v1/probe (500ms timeout). The companion plugin answers with installed plugins + versions, read straight from Obsidian's app.plugins.enabledPlugins / manifests — no per-plugin probing. The server validates that the reported vault_path matches config and caches the result in memory for the vault's lifetime. get_server_config exposes plugins_detected per vault for debugging.

Probe failure	Behavior
404 (companion not installed)	Bridge tools return plugin_missing; direct file ops still work
Timeout	Retry once at 200ms, then mark bridges_unavailable
Malformed JSON	Treated as 404
API major mismatch	Warn, continue in forward-compat mode

Config overrides

"plugins": {
  "forceEnabled": ["dataview", "tasks"],
  "forceDisabled": ["excalidraw"],
  "probeSkip": false
}

forceEnabled + probeSkip: true lets CI assert on tool behavior without booting Obsidian. forceDisabled exercises the plugin_missing path or operationally disables an expensive bridge.

Bridge timeouts

Default 5s per route (vault.bridges.timeoutMs); OCR and Templater routes default to 30s. A timeout returns plugin_unreachable.