# obsidian-claude-code A native Obsidian plugin that embeds Claude as an AI assistant directly within your vault. Built on the Claude Agent SDK, the plugin provides a persistent chat sidebar with full access to vault operations through built-in tools, skill loading, and custom Obsidian-specific actions. ## Overview obsidian-claude-code transforms Obsidian into an AI-augmented knowledge environment. Claude can read, search, and modify your notes while maintaining conversation context across sessions. The implementation uses the Claude Agent SDK with streaming responses, built-in tool presets, and automatic skill loading from your vault's `.claude/skills/` directory. ![Chat interface showing Claude searching vault for saxophone practice notes](docs/images/chat-interface.png) This is a desktop-only plugin. The Claude Agent SDK requires Node.js runtime, which is available in Obsidian's Electron environment but not on mobile platforms. ## Installation Clone the repository into your vault's plugin directory: ```bash cd /path/to/vault/.obsidian/plugins git clone https://github.com/yourname/obsidian-claude-code cd obsidian-claude-code bun install bun run build ``` Enable the plugin in Obsidian: Settings → Community Plugins → obsidian-claude-code. For development with hot-reload, symlink the repository: ```bash ln -s /path/to/obsidian-claude-code /path/to/vault/.obsidian/plugins/obsidian-claude-code bun run dev # watches for changes ``` ## Configuration Open Settings → Claude Code to configure: ### Authentication The plugin supports three authentication methods: 1. **API Key in Settings**: Enter your Anthropic API key directly. Stored in Obsidian's plugin data directory, not synced across devices. 2. **Environment Variable**: Set `ANTHROPIC_API_KEY` in your shell environment. 3. **Claude Max Subscription**: Run `claude setup-token` in your terminal to authenticate with your Claude Pro/Max subscription. This creates a `CLAUDE_CODE_OAUTH_TOKEN` environment variable. The settings page will show which authentication method is active. ### Model Selection Choose between: - `claude-sonnet-4-20250514` for faster responses - `claude-opus-4-5-20250501` for complex reasoning tasks ### Auto-Approve Settings By default, read operations are auto-approved while writes require confirmation. Toggle `autoApproveVaultWrites` to skip write confirmations for trusted workflows. ## Usage Click the chat icon in the ribbon or use `Cmd+Shift+C` to toggle the sidebar. The interface supports: **Direct Questions**: Ask about vault contents, request summaries, or get help with writing. **File References**: Use `@[[filename]]` syntax to include specific files in context. The `@mention` button provides autocomplete for vault files. **Slash Commands**: Type `/` for command autocomplete: - `/new` starts a fresh conversation - `/clear` clears history - `/file` adds the active file to context - `/search` initiates vault search **Tool Execution**: Claude can execute tools to interact with your vault. Tool calls appear as collapsible blocks showing the operation and result. Write operations display a permission modal unless auto-approve is enabled. ![Permission modal for tool approval](docs/images/permission-modal.png) ## Architecture The plugin uses the Claude Agent SDK's `query()` function with three layers of tool access: ```mermaid flowchart TB subgraph plugin["Obsidian Plugin"] AC["AgentController.ts"] query["query({
prompt: userMessage,
options: {
settingSources: ['project'],
tools: { preset: 'claude_code' },
mcpServers: { obsidian: ... }
}})"] AC --> query end subgraph sdk["Claude Agent SDK"] tools["Built-in Tools
Read, Write, Edit, Bash,
Grep, Glob, WebFetch, etc."] skills["Skill Loading
vault/.claude/skills/
vault-search → semantic search + SQL"] mcp["Obsidian MCP Server
open_file, execute_command,
sh

vault-search

Installation

SKILL.md