Claude Code for Obsidian

Use Claude Code seamlessly inside Obsidian — chat sidebar and inline editor commands, backed by your existing Claude subscription. Skills, slash commands, MCP servers, and CLAUDE.md files from your ~/.claude config are inherited automatically.

Status: early development. Desktop-only.

Requirements

• Obsidian 1.5+ (desktop — macOS, Linux, or Windows)
• Claude Code CLI installed and logged in. The plugin reuses your existing OAuth token — no API key required.
• Node.js 20+ (only for building from source)

The plugin auto-detects the claude executable. It walks PATH first, then falls back to the standard install locations on each platform:

Platform	Where the plugin looks
macOS / Linux	$PATH, ~/.local/bin/claude, ~/.claude/local/claude, ~/.bun/bin/claude, Homebrew (/opt/homebrew/bin, /usr/local/bin)
Windows	%PATH%, %APPDATA%\npm\claude.{cmd,exe,ps1}, %LOCALAPPDATA%\Programs\claude\, %USERPROFILE%\.bun\bin\, Scoop shims

Auth tokens are read from ~/.claude/ (macOS/Linux) or %USERPROFILE%\.claude\ (Windows). Run claude login in any terminal once and the plugin picks it up.

Install

Option A — From a GitHub release (recommended)

1. Go to the latest release and download manifest.json, main.js, and styles.css.
2. Drop all three files into your vault's plugin folder (create it if it doesn't exist):
   • macOS / Linux: <your-vault>/.obsidian/plugins/cc-obsidian/
   • Windows: <your-vault>\.obsidian\plugins\cc-obsidian\
3. Restart Obsidian (or run Reload app without saving from the command palette).
4. Enable Claude Code under Settings → Community plugins → Installed plugins.
5. Open the chat with the bot icon in the left ribbon, or run Open Claude Code chat from the command palette.

Option B — Via BRAT (auto-update)

With the BRAT plugin installed:

1. BRAT → Add Beta plugin.
2. Paste ParadauxIO/cc-obsidian and pick the latest version.
3. Enable Claude Code under Community plugins.

BRAT will pull future releases automatically.

Option C — Build from source

git clone https://github.com/ParadauxIO/cc-obsidian.git
cd cc-obsidian
npm install
npm run build

Then copy manifest.json, main.js, and styles.css into <your-vault>/.obsidian/plugins/cc-obsidian/ and enable the plugin.

Features

Chat sidebar

A persistent session per vault, anchored in the right sidebar. The active note's content plus its wikilinks and backlinks are attached to each message as context — Claude reads linked notes on demand. New session clears history; Stop cancels in-flight responses. Tool calls render as collapsible cards.

The note Claude wrote in the screenshot above:

Type / in the chat input to see slash commands discovered from ~/.claude/commands and the vault's .claude/commands. Project-scoped commands are tagged so you know where they came from:

Inline editor commands

Available in the command palette and as a Claude submenu in the editor right-click menu:

Command	What it does
Rewrite	Replaces the selection with a rewritten version (you provide an instruction)
Continue writing	Appends Claude's continuation at the cursor
Summarize	Inserts a > [!summary] callout above the selection
Expand	Replaces the selection with a fuller version
Ask	Asks a question about the selection in a modal (no edits)
Custom prompt	Free-form prompt over the selection, replaces

Inline command turns appear in the chat panel labeled with the command and source note, so you can follow up in the chat.

Vault-aware file tools

Claude's built-in Read/Edit/Write are disabled. Replacements go through Obsidian's Vault API, so edits compose cleanly with open editor buffers and metadata stays in sync.

Approval mode (opt-in)

Toggle Require approval for edits in settings. Each vault_write/vault_edit shows a before/after diff with Approve / Reject before being applied. Bash is always gated when enabled.

Inherits your Claude Code config

The plugin runs the SDK with settingSources: ['user', 'project', 'local'] by default, so it picks up:

• ~/.claude/settings.json and <vault>/.claude/settings.json
• ~/.claude/CLAUDE.md and <vault>/CLAUDE.md
• Skills in ~/.claude/skills/* and <vault>/.claude/skills/*
• Slash commands in ~/.claude/commands/* and <vault>/.claude/commands/*
• MCP servers and hooks from those settings files

Each scope (user / project / local) can be toggled off in plugin settings.

External MCP server (opt-in)

Optionally expose the vault tools over HTTP/SSE on a configurable port (default 127.0.0.1:22360) so the standalone claude CLI, Claude Desktop, Cursor, etc. can read/write vault notes too. No authentication — only enable on a trusted machine.

vault_open is intentionally not exposed externally (would let remote callers force focus changes in your Obsidian window).

Settings

Section	What it controls
Auth	Detection status for ~/.claude credentials, with re-check button
Context	Smart-context on/off, include backlinks (max link hops reserved for future)
Tools	Toggle Bash, WebFetch, WebSearch, Task (subagents)
Config inheritance	Toggle inheriting user / project / local ~/.claude settings
Approval	Require approval for edits
External MCP server	Enable, port, bind address
Session	Reset session

Development

npm install
npm run dev       # esbuild watch mode
npm test          # vitest — 68 tests across 8 files
npm run coverage  # vitest with v8 coverage; HTML report in coverage/
npm run lint

Tests cover every node-testable module: context-builder, gather-context, vault-tools, obsidian-vault-adapter, in-process-mcp, external-mcp-server (real HTTP/SSE round-trip), slash-commands, claude-executable (mocked unix + windows lookups). UI views, modals, the Agent SDK session manager, and the settings tab depend on Obsidian's runtime and are exercised manually.

For live testing, link the build into your dev vault.

macOS / Linux:

mkdir -p ~/Vault/.obsidian/plugins/cc-obsidian
ln -sf "$(pwd)/main.js"      ~/Vault/.obsidian/plugins/cc-obsidian/main.js
ln -sf "$(pwd)/styles.css"   ~/Vault/.obsidian/plugins/cc-obsidian/styles.css
ln -sf "$(pwd)/manifest.json" ~/Vault/.obsidian/plugins/cc-obsidian/manifest.json

Windows (PowerShell, run as Administrator or with Developer Mode enabled):

$dst = "$HOME\Vault\.obsidian\plugins\cc-obsidian"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
foreach ($f in "main.js","styles.css","manifest.json") {
  New-Item -ItemType SymbolicLink -Force -Path "$dst\$f" -Target "$PWD\$f" | Out-Null
}

If symlinks aren't an option on Windows, just Copy-Item the three files after each npm run build.

Architecture

• src/main.ts — plugin lifecycle, view registration, ribbon icon, external MCP wiring
• src/session/session-manager.ts — Agent SDK query lifecycle, message history, session persistence, canUseTool builder
• src/context/ — pure context block builder + Obsidian gather adapter
• src/tools/ — VaultTools (pure), Obsidian adapter, in-process MCP wrapper, optional external MCP server
• src/ui/ — ChatView (right-sidebar ItemView), prompt/answer/diff modals, message rendering
• src/inline/ — inline command registry + editor-menu submenu
• src/settings.ts, src/settings-tab.ts

Pure modules (context-builder, vault-tools) are unit-tested via vitest with no Obsidian dependency.

Releasing

Releases are cut by pushing a semver tag matching manifest.json's version field. The release workflow builds main.js and uploads manifest.json, main.js, and styles.css as release assets — the layout the Obsidian community-plugin loader and BRAT both expect.

npm version patch        # or minor / major
# updates package.json, runs version-bump.mjs to sync manifest.json + versions.json,
# then commits + tags
git push origin main --follow-tags

The workflow verifies the pushed tag matches manifest.json before publishing, then creates a GitHub release with auto-generated notes.

Contributing

Issues and PRs welcome at ParadauxIO/cc-obsidian. CI runs npm run lint, npm test, and npm run build on every push and PR.

License

MIT