← All docs
View on GitHub

VaultGuard AI Chat

VaultGuard ships an optional native Claude/GPT chat panel inside Obsidian. A fresh install shows one VaultGuard shield and keeps AI Chat off; enable AI Chat under the optional modules in VaultGuard settings, then open it through the control center or command palette. Existing installs keep their prior Chat availability during the one-time settings migration.

The point of difference from a general AI plugin: every file the assistant reads or writes runs through the same VaultGuard gates as a human user. Plaintext is decrypted on demand, writes are re-encrypted with your local key, your per-file permissions still apply, and every tool call is audit-logged. The model never touches the VG1\0 ciphertext on disk.

Four ways to connect

The panel makes no model call until you connect it. With no provider key or supported subscription login, it shows a connect screen and sends no vault content outbound.

  • Bring your own API key. Paste an Anthropic API key in the plugin settings. Requests go to the Anthropic Messages API under your key. By default, VaultGuard stores a method-tagged encrypted envelope using Electron safe storage when available, with the existing local at-rest cipher as the documented fallback.
  • Bring your own OpenAI API key. Paste an OpenAI API key in the plugin settings and select the OpenAI/GPT provider. Requests use the OpenAI Responses API with store:false; the same VaultGuard encrypted-envelope default applies and vault functions run in-process.
  • Drive your Claude subscription. If you use Claude Code, sign in to it once from your machine and select the subscription provider. VaultGuard drives the official Claude Code CLI against its own local tool surface only — never against your vault directory — so VaultGuard never sees a third-party token.
  • Drive your ChatGPT subscription. Install the official Codex CLI, sign in with ChatGPT, and select ChatGPT subscription (Codex CLI). VaultGuard runs an ephemeral Codex app-server thread in an empty temporary directory and gives it one lease-scoped localhost MCP server. It rejects API-key/access-token Codex modes, strips ambient OpenAI API credentials, and never reads the Codex credential store. This uses the limits and model access of the user's ChatGPT plan; VaultGuard does not make a metered OpenAI API-key request.

In every mode, nothing leaves the device until you send a turn, and only the content needed for that turn is sent.

On Obsidian 1.11.5 and newer, Anthropic and OpenAI API-key users may instead select a named secret from Obsidian Secret Storage. VaultGuard persists only the secret ID in plugin settings. Native mode is explicit and non-roaming from VaultGuard's perspective: an unavailable runtime, missing ID, or missing value fails closed as “no key,” with no silent fallback to the VaultGuard envelope. Clearing native mode forgets VaultGuard's reference and does not delete a global Obsidian secret that another plugin may use. Obsidian 1.8.7 remains the plugin minimum; the native secret control is simply unavailable there.

What it can do

The assistant works through a curated tool surface — the same one the Agent Bridge exposes:

  • Orient itself safely — call vaultguard_get_vault_orientation to identify the active vault, connector profile, protection state, write safety, and bounded Git metadata before ambiguous vault or edit tasks.
  • Ask about your notes — list, search, and read files you have permission to see.
  • Edit notes — proposed changes are shown as a reviewable diff. Depending on your permission mode you approve each write, or let trusted edits through.
  • Explain and adjust access — it can describe who can reach a note and change vault, folder, or file-level permissions, always behind the same confirmation prompt and audit trail as a manual change.

It cannot reach hidden directories (.obsidian, .trash, .git, …) or any configured VaultGuard exclusion, even if asked.

Settings

  • Provider and model — choose Anthropic/OpenAI API-key mode or a supported Claude/ChatGPT subscription transport, then select a compatible model.
  • Streaming (desktop only) — token-by-token replies; defaults on. With it off, behavior is identical but the reply appears all at once. Mobile always uses the non-streaming path.
  • Permission mode — confirm writes (review every edit before it lands) or skip (let edits through without a per-file prompt). Setting permissions always asks, regardless of mode.

Privacy

  • File reads and writes use the same at-rest decrypt and permission path as the rest of the plugin.
  • Orientation snapshots are metadata-only. They do not expose absolute local paths, raw Git remotes, API keys, bridge tokens, connector tokens, recovery keys, local access keys, or decrypted vault dumps.
  • Writes are shown as diffs you confirm; tool calls are audit-logged without the file content.
  • Conversation history is stored locally and encrypted with your local at-rest key.
  • Subscription subprocesses receive the MCP bearer only through their child environment. The bearer is revoked when the chat is cleared, cancelled, closed, or switched to another provider.
  • A remote model necessarily receives any note content you ask it to read or edit — keep that in mind for sensitive notes, and prefer narrow questions over whole-vault sweeps.

Built-in chat vs. bring-your-own-agent

The built-in chat and the Agent Bridge are two front ends over one permission and audit boundary:

  • Use the built-in chat to stay inside Obsidian with no setup beyond a key or an official CLI subscription login. It is one optional module.
  • Use the Agent Bridge to wire your own tools — Claude Code, Cursor, Claudian — into the same vault tool surface. External Agent Access is a separate opt-in module; enabling Chat does not expose an external bridge server.

Both are plugin features and work on every VaultGuard edition (Community, Pro, Enterprise).