Claude Vault Assistant

Run pre-defined claude prompts against your obsidian vault, within obsidan itself.

An Obsidian plugin that lets you define reusable prompt files (PROMPT-*.md) and run them against your vault or the currently active note. Both one-off prompts and the interactive chat (a multi-turn conversation with Claude inside an Obsidian pane) drive the Claude Code CLI through the Claude Agent SDK, with in-pane tool approvals.

⚠️ Security & Trust Model — Read This First

This plugin works by running the Claude Code CLI as a local process on your machine. Prompts you write — including ad-hoc prompts, PROMPT-*.md files, and your CLAUDE.md — are passed to the CLI, which then drives an agentic loop that can read, write, and edit files in your vault (and run other tools you explicitly allow). You are giving an LLM the ability to take actions on your system. Treat that seriously.

Things you should understand before using this plugin:

• The plugin runs the CLI as a local process. The Claude Agent SDK launches your configured CLI executable directly (not through a shell). On macOS/Linux the plugin first harvests your login-shell environment (PATH, API tokens, shell rc exports) and passes it to that process so it sees your normal env; on Windows it uses the process environment directly. Your prompt is delivered to the CLI as data, not as a shell argument, but the CLI itself still runs with your full user permissions.
• Whatever you put in Allowed tools is what Claude auto-approves. The default allowlist (Read, Grep, Glob, Write, Edit) is scoped to file I/O inside the vault. If you add Bash (or any other tool that executes code), Claude can run arbitrary commands on your machine during a run without prompting. Only do this if you understand the consequences.
• Tools outside the whitelist require your approval. Both one-off prompts and the interactive chat auto-approve the Allowed tools whitelist. When Claude wants a tool outside it, an approval card appears in the run's pane (the output pane for one-off prompts, the conversation for chat) offering Allow once, Allow for this run/chat, or Deny. For a one-off prompt an approval lasts only for that single run; in chat, "Allow for this chat" lasts until the chat closes. Neither ever changes the saved Allowed tools whitelist. Approving a code-executing tool (e.g. Bash) carries the same risks as adding it to the whitelist -- only approve what you understand.
• Prompt injection from note content is a real risk. Claude reads the notes you point it at. If your vault contains untrusted content — clipped web pages, pasted emails, shared notes, anything you didn't author — that content can contain instructions that the model may follow. With a permissive tool allowlist this becomes a path to unintended file edits or command execution. Audit what's in your vault before running broad prompts over it.
• The CLI path setting is not sandboxed. It's the executable the plugin runs. Don't point it at anything you wouldn't otherwise execute. Leave it as claude unless you have a specific reason to change it.
• CLAUDE.md is sent as a system prompt on every run. Anything in that file shapes the model's behavior across all prompts. Don't paste untrusted content into it.
• Runs are not sandboxed to the active note. "Note scope" adds an instruction asking the model to only edit the active note — it's a guideline, not an enforced boundary. With Write/Edit allowed, the model technically has access to the whole vault.
• Set a Max budget (USD) and Max turns. A prompt that loops or fans out can cost real money. The defaults cap turns at 50; there is no default budget cap.

In short: only run prompts you wrote (or have read), only enable tools you understand, and assume the model will occasionally do something you didn't intend. Review changes (git, file history, Obsidian's file recovery) after broad runs.

Prerequisites

• Obsidian v1.7.2+
• Claude Code CLI installed and authenticated

Installation

Now available thru the Obsidian Community site.

Usage

Create a CLAUDE.md note in the root of the vault

Create a note in the root of your vault and name it CLAUDE. Fill this out with vault conventions claude should know when working within your vault.

An example CLAUDE.md:

# Personal Assistant - Vault Convetions
You are a personal assistant helping organize and maintain notes in an obsidian vault.

## Vault Structure
- /daily-notes - One note per day (YYY-MM-DD format)
- /projects - Notes related to ongoing projects
- /templates - Obsidian templates for daily notes and other recurring note types
- /people - Notes related to specific individuals

## Conventions
- Always use [[wiki links]] when referencing other notes, projects, or people
- File names should be lowercase with hyphens (e.g., new-project-research.md)
- the `brain-dump.md` note in the root is used for raw brain dumps and unprocessed notes (Claude sorts this into the right folders)
  - when processing brain dumps, break it out into spearate notes in the appropriate folders or append to existing notes if appropriate
- If a note references a person make their name link to their note in `/people`, if they don't have a note, create one and link it.

## Preferences
- Keep notes concise - bullet points over paragraphs
- always include a `## Key Takeaways` section in research notes
- when creating people notes, include: name, role/channel, how they're relevant, and any links to related notes with a short description of their relevance in the note.

Creating prompt files

Create PROMPT-*.md files at the root of your vault. Each file defines a reusable prompt. The file name (minus the PROMPT- prefix and .md extension) becomes the display name in the picker.

Example: A prompt to summarize a note and provide bullet list of links at the top of a note, PROMPT-summarize.md:

You are an Obsidian note summarizer. Your job is to read the provided note and append a concise bulleted summary to the end of it.

## Instructions

1. **Read the full note** before summarizing.
2. **Identify the key points** — focus on facts, decisions, findings, action items, and conclusions.
3. **Write a `## Summary` section** with a bulleted list capturing the essence of the note. Each bullet should be one clear, concise statement.
    1. These should provide quick links to appropriate sections where possible.
4. **Append the Summary section to the end of the note.** Do not modify any existing content.
5. **Do not add information that isn't in the note.** Only distill what is already there.
6. **Use [[wiki links]]** for any referenced people, projects, or notes that aren't already linked.

Example: A prompt intended to be ran against specific notes, PROMPT-refine-note.md:

You are an Obsidian note editor. Your job is to refine and improve the provided note while preserving its meaning and intent.

## Instructions

1. **Improve clarity and conciseness** — Tighten language, remove redundancy, and favor bullet points over long paragraphs. Every sentence should earn its place.
2. **Professional tone** — Rewrite informal or rough language to read cleanly and professionally without losing the author's voice.
3. **Structure** — Ensure the note has clear headings, logical flow, and consistent formatting. Add a `## Key Takeaways` section at the end if one doesn't exist.
4. **Add missing [[wiki links]]** — Identify any references to people, projects, tools, concepts, or other notes that should be linked with `[[wiki links]]` but aren't. Add them.
5. **Fix formatting** — Correct any broken markdown, inconsistent list styles, or missing frontmatter.
6. **Do not fabricate content** — Only reorganize and refine what is already there. Do not add new facts, claims, or sections beyond links and Key Takeaways.

Running prompts

There are four ways to run a prompt:

1. Ribbon icon — Click the bot icon in the left sidebar to open the prompt picker (vault scope)
2. Command palette — Use Run Claude Prompt (Vault) to run against the entire vault
3. Command palette — Use Run Claude Prompt (Active Note) to run scoped to the currently open note
4. Command palette — Use Run ad-hoc Claude prompt to type a one-off prompt directly without creating a prompt file

After selecting a prompt, Claude's output streams in real time into a sidebar pane. Tool calls (file reads, edits, etc.) are shown as collapsible sections beneath the output, each with a status badge (✓ success, ✗ error) once the result returns. While the run is active, an animated "Claude is working" indicator sits at the bottom of the pane with a live counter of elapsed time and tokens generated so far. When the run finishes, the indicator is replaced by a one-line breakdown showing the cost, elapsed time, and total tokens used (e.g. $0.0123 - 4.5s - 12,345 tokens).

If Claude requests a tool that isn't on the Allowed tools whitelist, an approval card appears in the output pane with Allow once, Allow for this run, or Deny. An approval applies only to that single run and never changes your saved whitelist.

Stopping a run

• Click the Stop button in the output pane, or
• Use the Stop Claude command from the command palette

Output pane

Use Open Claude Output from the command palette to open the output pane at any time. It has two tabs:

• Output — Live-streamed markdown output from the current or most recent run, with status indicators (Idle / Running / Complete / Error / Stopped / Limit Reached)
• History — A log of past runs showing prompt name, scope, timestamp, duration, status, and cost. Click any entry to review its cached output. Ad-hoc runs include the full prompt text in a collapsible Prompt section above the replay; runs from PROMPT-*.md files show only the file name. Use the Clear History button to remove all entries.

Interactive chat

Open a multi-turn conversation with Claude inside Obsidian:

1. Ribbon icon — Click the chat (message) icon in the left sidebar, or
2. Command palette — Use Open Claude chat

Type a message and press Enter to send (Shift+Enter for a newline). Claude's replies render as markdown, and tool calls appear inline as collapsible sections, the same as the output pane. While Claude is working on a turn, an animated "Claude is working" indicator with a live elapsed-time and token counter sits at the bottom of the transcript; it disappears when the turn ends. After each turn, a one-line breakdown below the reply shows the cost, elapsed time, and tokens used (e.g. $0.0123 - 4.5s - 12,345 tokens). The conversation keeps its context across turns -- one Claude process stays alive for the life of the chat.

Tool approvals. The chat starts with the same Allowed tools whitelist as one-off prompts. When Claude wants a tool that isn't on the whitelist, an approval card appears in the conversation with three choices:

• Allow once — permit this single call; you'll be asked again next time.
• Allow for this chat — permit this tool for the rest of the current conversation; forgotten when the chat closes.
• Deny — refuse the call and tell Claude so.

These approvals never modify your saved Allowed tools whitelist. One-off prompts have the same approval flow, scoped to a single run.

Choosing the model. The chat header has a model dropdown showing the model that will be used for the next message. It defaults to your Model override setting (or "Default (CLI)" when that's empty, letting the CLI choose). Pick a different model (Opus, Sonnet, Haiku, or a custom value from your settings) to switch -- it applies live to the running conversation and is remembered for this chat only; it never changes your saved settings. The dropdown is locked while a turn is in progress.

Active-note context. A context bar sits just above the message box showing the note you currently have open in Obsidian, with a checkbox that is on by default. While it's checked, each message you send is prefixed with a short line naming that note as a [[wiki link]] and telling Claude to read it if it's relevant -- so a chat instantly knows what you're looking at without you pasting anything. The reference is cheap (it costs no extra tokens up front; Claude reads the note itself only when it needs to), and it always reflects the note's current on-disk contents. The bar updates as you switch notes, and a small Context: [[note]] caption is recorded under each message that included one -- its wiki link is clickable, so you can reopen the referenced note when reviewing the history. Uncheck the box to send a message with no note attached. When no note is open, the bar shows "No note open" and nothing is attached.

Stopping and resetting. Use Stop in the chat header to interrupt the current turn without ending the conversation. Use New chat to discard the conversation and start fresh.

One run at a time. A chat turn and a one-off prompt run cannot run simultaneously. An idle, open chat does not block one-off prompts -- the lock is only held while a turn is actively running. The Max turns and Max budget (USD) settings apply per chat turn.

CLAUDE.md support

If a CLAUDE.md file exists at the root of your vault, its contents are automatically passed as a system prompt to every run. Use this to set global instructions, conventions, or context that should apply to all prompts.

Frontmatter overrides

Add YAML frontmatter to any prompt file to override plugin settings on a per-prompt basis. Supported fields:

---
model: sonnet
maxTurns: 10
maxBudget: 0.50
allowedTools: [Read, Grep, Glob]
---
Your prompt content here...

Prompts with overrides display badges in the picker so you can see at a glance which settings differ from defaults.

Notifications

• An in-app notice appears when a run finishes
• A system notification is sent when Obsidian is not focused, so you can switch away during long runs

Vault refresh

After Claude edits files, the plugin automatically refreshes modified files in Obsidian so you see changes immediately without needing to reopen or reload.

Privacy & Network Usage

This plugin runs the Claude Code CLI as a local child process. Both one-off prompts and the interactive chat drive the CLI through the Claude Agent SDK, which launches your installed CLI (so it uses your existing authentication). When you run a prompt or send a chat message, the CLI sends your content and relevant vault files to Anthropic's API for processing. No data is sent by the plugin itself — all network communication is handled by the CLI.

• Account required: You need an authenticated Anthropic account with billing to use the Claude Code CLI.
• What is sent: Prompt file contents, chat messages, vault file contents read by Claude during a run, and any system prompt from your CLAUDE.md file.
• What is stored locally: Run history for one-off prompts (prompt name, scope, timestamps, cost, and output) is stored in the plugin's data file within your vault's .obsidian/plugins/ directory. Interactive chat conversations are held in memory only and are not written to the run history or to session files on disk.
• No telemetry: This plugin does not collect analytics or send any data independently of the CLI.

See Anthropic's Privacy Policy for details on how Anthropic handles data sent via the CLI.

Settings

Configure the plugin in Obsidian Settings > Claude Vault Assistant:

Architecture

• src/main.ts — Plugin entry point, registers commands and views
• src/settings.ts — Plugin settings interface and settings tab
• src/chat-session.ts — Claude Agent SDK driver shared by both one-off runs and the interactive chat: builds options, streams SDK messages, and bridges tool approvals
• src/prompt-runner.ts — Drives a single-turn one-off prompt run on top of chat-session (replaces the old child-process runner)
• src/output-view.ts — Sidebar output pane with markdown rendering, history tab, and tool-approval prompts
• src/run-history.ts — Run history storage, retrieval, and pruning logic
• src/prompt-scanner.ts — Scans vault root for PROMPT-*.md files
• src/frontmatter.ts — Parses YAML frontmatter overrides from prompt files
• src/prompt-picker.ts — Modal for selecting a prompt to run
• src/adhoc-prompt-modal.ts — Modal for typing ad-hoc prompts
• src/vault-refresher.ts — Refreshes modified files after a run
• src/chat-view.ts — Sidebar chat pane: transcript, input box, active-note context bar, and permission cards
• src/chat-context.ts — Pure helpers that turn the active note into a reference-only context preamble ([[wiki links]]) prepended to a chat turn
• src/permission-card.ts — Shared tool-approval card rendering used by both the output and chat views
• src/permission-types.ts — Shared permission contract (decision and request types)
• src/run-types.ts — Shared RunScope type (vault vs active note)
• src/system-prompt.ts — The Obsidian system prompt appended on every run
• src/env-resolver.ts — Harvests the login-shell environment so the SDK-launched CLI sees your normal PATH and API tokens
• src/electron-compat.ts — Electron renderer shim so the Agent SDK runs inside Obsidian
• src/activity-lock.ts — Shared gate so a one-off run and a chat turn never run at the same time
• src/tool-render.ts — Shared tool-call rendering used by both the output and chat views
• src/working-indicator.ts — Animated "Claude is working" indicator with a live elapsed-time/token counter, shown in both the output and chat views while a turn is in flight
• src/format.ts — Shared formatting for the cost/time/token breakdown and live token counts

Development

Setup

npm install

Build

# Development (watch mode)
npm run dev

# Production build
npm run build

Test

# Run tests
npm test

# Watch mode
npm run test:watch

License

MIT