obsidian-claude-code

An Obsidian plugin that embeds Claude as an AI assistant using the Claude Agent SDK. Claude gets full access to your vault through the same tools available in Claude Code—read, write, search, and execute commands—plus custom Obsidian-specific actions.

Screenshot

What It Does

Claude operates as a persistent assistant in your Obsidian sidebar. Ask questions about your notes, request summaries, or have Claude modify files directly. Conversations persist across sessions, and Claude can resume where you left off.

Built on the Claude Agent SDK, the plugin gives Claude access to built-in tools (Read, Write, Edit, Bash, Grep, Glob, WebFetch) plus Obsidian-specific tools for opening files, executing commands, and navigating the workspace. If you have skills defined in vault/.claude/skills/, those load automatically too.

This is a desktop-only plugin. The Claude Agent SDK requires Node.js, which is available in Obsidian's Electron environment but not on mobile.

Requirements

You need an Anthropic API key or a Claude Max subscription. Both work equally well—the subscription option is convenient if you're already paying for Claude.

Installation

cd /path/to/your/vault/.obsidian/plugins
git clone https://github.com/Roasbeef/obsidian-claude-code
cd obsidian-claude-code
npm install && npm run build

Then enable the plugin: Obsidian Settings → Community Plugins → obsidian-claude-code.

Authentication

The plugin supports three authentication methods.

API Key in Settings. The simplest option. Open Settings → Claude Code and enter your Anthropic API key. You can store the key in the OS keychain when supported.

Environment Variable. Set ANTHROPIC_API_KEY in your shell environment. The plugin reads it automatically.

Claude Max Subscription. If you have a Claude Pro or Max subscription, you can use that instead of an API key. Run claude setup-token in your terminal to authenticate. This creates a CLAUDE_CODE_OAUTH_TOKEN that the plugin detects.

For GUI apps like Obsidian to inherit the token on macOS, add this to your shell profile:

launchctl setenv CLAUDE_CODE_OAUTH_TOKEN "$(echo $CLAUDE_CODE_OAUTH_TOKEN)"

The settings page shows which authentication method is active.

Usage

Toggle the sidebar with the ribbon icon or Cmd+Shift+C. Type your message and press Enter.

Reference specific files using @[[filename]] syntax—the input field provides autocomplete when you type @.

Slash command workflow is CLI-style:

• Type / to open command suggestions.
• ArrowUp/ArrowDown navigates suggestions.
• Enter or Tab fills the selected command in the input.
• Press Enter again to execute local commands or send passthrough commands.
• Shift+Tab cycles permission mode: default -> acceptEdits -> plan -> default.

Key slash commands:

• /help shows a rich command catalog (grouped local commands, discovered SDK/project/personal/MCP commands, keyboard tips, and examples).
• /doctor runs local diagnostics with recommended remediation (auth/session/model/context/MCP/permission usage checks).
• /new, /clear, /rename [title], /resume [index|id|title] manage conversation state (/resume opens a keyboard-searchable session picker).
• /file [path], /pin-file, /pin-selection, /pin-backlinks [count], /pins, /clear-pins manage context.
• /status, /context, /usage, /cost, /permissions, /mcp, /model [name], /logs show operational diagnostics.
• /rewind restores the most recent backup and /checkpoint lists rewind checkpoints.
• /search [query] is passthrough to Claude.

When Claude uses tools, the operations appear as collapsible blocks showing what happened and the result. Bash calls include stdout, stderr, exit code, and a copy-output button. Write operations can show a unified diff preview and provide a one-click revert. During streaming, assistant text is kept in chronological order around tool calls so follow-up text appears after the tool card instead of above it.

The Project Controls panel (toggleable in settings) exposes model/budget/turn limits, auth status, active skills, MCP servers, and quick actions for pinning context like the active file or a text selection. The chat header also includes:

• a rolling 5-hour usage bar (local spend vs configured 5-hour budget, or plan utilization when available),
• a context usage bar (estimated tokens used vs model context window),
• a checkpoint/rewind menu for restoring recent edit backups.

Tools and Skills

Claude has access to all built-in Claude Code tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, and WebSearch. These handle file operations, code search, and shell commands.

The plugin also exposes Obsidian-specific tools through an MCP server:

• open_file — Open a file in the Obsidian editor
• execute_command — Run any Obsidian command
• show_notice — Display a notification
• get_active_file — Get info about the current file
• list_commands — Discover available commands
• create_note — Create new notes
• reveal_in_explorer — Show a file in the file explorer
• get_vault_stats — Query vault statistics
• get_recent_files — List recently modified files

Advanced users can add additional MCP servers in settings (stdio-based configs) and approve them per server.

Skills

Skills in vault/.claude/skills/ load automatically. The repository includes a vault-search skill you can copy to your vault:

cp -r skills/vault-search /path/to/vault/.claude/skills/

This skill provides semantic search via sqlite-vec embeddings and SQL queries over note frontmatter (a Dataview alternative). See skills/README.md for setup instructions.

See docs/architecture.md for full architectural details.

Data Storage

Conversations are stored in .obsidian-claude-code/ at your vault root:

.obsidian-claude-code/
├── conversations.json    # Metadata index
└── history/
    └── {id}.json         # Full message history per conversation

Add this directory to .gitignore if you don't want to sync conversation history.

Backups for diff-reviewed edits are stored under .obsidian-claude-code/backups/{conversationId}/ and are used by the Revert button in tool call blocks.

Development

npm run dev      # watch mode with rebuild
npm run build    # production build
make check       # typecheck + lint + test

Debug logs are written to ~/.obsidian-claude-code/debug.log.

New Settings (UX Parity)

• Streaming updates: real-time partial response rendering.
• Review edits with diff: show unified diffs and allow revert from backup.
• Project Controls panel: model/budget/turns/auth/skills + context pinning and rewind actions.
• Header telemetry bars: rolling 5-hour usage and estimated context-window usage.
• Permission mode: choose default, acceptEdits, plan, or bypassPermissions.
• 5-hour usage budget: configure the denominator used by the usage bar.
• Header usage bar source: optionally show plan utilization when available (experimental).
• Keychain storage: store API keys in the OS keychain when supported.
• Additional MCP servers: add/approve extra MCP server configs via JSON.

License

MIT