Set up Obsidian with Claude Code

Verified with Obsidian 1.13.7 · Claude Code 2.1.283 · macOS 27.0

1. 01Step 1: Install ObsidianThe desktop app, which also ships the command line tool used later.

   Install Obsidian with Homebrew. It keeps itself up to date after that.

   brew install --cask obsidian

   Open it once, so macOS can confirm the app:

   open -a Obsidian

2. 02Step 2: Create a vaultA plain folder of Markdown notes that both Obsidian and Claude Code can open.

   Create the folder for your notes:

   mkdir -p ~/Notes

   Then open it in Obsidian:

   1. On the first screen, next to Open folder as vault, click Open. If a vault is already open, click the vault name at the bottom left, choose Manage vaults..., and find Open folder as vault there.
   2. Select the Notes folder in your home folder, then click Open.

   Obsidian names the vault after the folder, so this vault is called Notes.

   Already have a vault? Use its folder instead of ~/Notes in every command in this guide.

3. 03Step 3: Turn on the Obsidian command line toolThe obsidian command lets Claude search and read your vault through Obsidian's own index.

   Obsidian includes a command line tool called obsidian. It is off until you turn it on:

   1. In Obsidian, open Settings with Cmd+, and select General.
   2. Turn on Command line interface.
   3. Next to Set up CLI to work in the terminal, click Register, and enter your Mac password if asked.

   Open a new terminal window with Cmd+N, then check that it works. The first command prints the version, and the second prints the vault's name, path and file count.

   obsidian version
   cd ~/Notes
   obsidian vault

   A few things to know:

   • The tool only works while the Obsidian app is running, and the first command opens it if it is closed.
   • Inside a vault folder it uses that vault. Anywhere else it uses the vault that is active in Obsidian, and vault=Notes as the first option picks one by name.
   • obsidian help lists every command, and obsidian help search explains one.
4. 04Step 4: Track the vault with GitA local history of every note, so you can see what Claude changed and undo it.

   Before Claude edits any notes, put the vault under Git. Every change then shows up in git diff, and anything you do not like can be undone.

   If you have never made a Git commit on this Mac, tell Git your name and email first, replacing the examples:

   git config --global user.name "Your Name"
   git config --global user.email "you@example.com"

   This creates a .gitignore that skips Obsidian's window layout, its trash folder, the backups this guide makes and macOS clutter, only if the vault does not have one yet, then saves the first snapshot:

   cd ~/Notes
   git init
   [ -f .gitignore ] || cat > .gitignore <<'EOF'
   .obsidian/workspace.json
   .obsidian/workspace-mobile.json
   .trash/
   *.bak-*
   .DS_Store
   EOF
   git add -A
   git commit -m "Start my notes"

   The history stays on your Mac. If you add a remote later to back it up, keep that repository private, because it holds everything you write.

5. 05Step 5: Tell Claude how your vault worksA CLAUDE.md inside the vault with your note style, how to search, and what Claude must never do.

   Claude Code reads a project's CLAUDE.md at the start of every session. Saving it as .claude/CLAUDE.md keeps it out of sight, because Obsidian hides folders whose names start with a dot.

   This command backs up any file with the same name first, then writes one you can adjust later:

   mkdir -p ~/Notes/.claude
   [ -f ~/Notes/.claude/CLAUDE.md ] && cp ~/Notes/.claude/CLAUDE.md ~/Notes/.claude/CLAUDE.md.bak-$(date +%Y%m%d-%H%M%S)
   cat > ~/Notes/.claude/CLAUDE.md <<'EOF'
   # My Obsidian vault
   
   This folder is an Obsidian vault: plain Markdown notes that I also read and edit in the Obsidian app.
   
   ## Writing notes
   - Write Obsidian Flavored Markdown.
   - Link to other notes with wikilinks by note name, such as [[Project Alpha]], not by file path.
   - Start every new note with properties (YAML frontmatter) that include `created` (YYYY-MM-DD) and `tags`.
   - Save new notes in the vault root unless I name a folder.
   - When you edit one of my notes, keep my wording and add to it instead of rewriting it.
   
   ## Finding notes
   - Prefer the `obsidian` command for searching, links, tags and tasks, because it uses Obsidian's own index.
     Examples: `obsidian search query="term"`, `obsidian backlinks file="Note name"`, `obsidian tasks todo`.
   - If an `obsidian` command fails or hangs, search the files directly instead.
   
   ## Safety
   - Never delete, move or rename a note without asking me first.
   - Never change anything inside `.obsidian/`, which holds Obsidian's own settings.
   - Never write passwords, API keys or tokens into a note.
   - After a batch of changes, show me `git status` so I can review them.
   EOF

   To change the rules later, edit ~/Notes/.claude/CLAUDE.md in any text editor.

6. 06Step 6: Add the Obsidian skillsSkills from Obsidian's CEO that teach Claude Obsidian's Markdown, Bases, Canvas and command line tool.

   Steph Ango, the CEO of Obsidian, publishes a set of skills for coding agents. They teach Claude the parts of Obsidian that plain Markdown does not cover:

   • obsidian-markdown: wikilinks, embeds, callouts and properties.
   • obsidian-bases: .base files, Obsidian's database-like views of your notes.
   • json-canvas: .canvas files, Obsidian's whiteboards.
   • obsidian-cli: the obsidian command from the previous steps.
   • defuddle and knap: turning web pages into clean Markdown, and filling Markdown templates from data.

   Review before installing. A plugin can run code on your machine, so read the repository first.

   Install the plugin from the terminal:

   claude plugin marketplace add kepano/obsidian-skills && claude plugin install obsidian@obsidian-skills

   Or send these as two separate prompts inside Claude Code:

   /plugin marketplace add kepano/obsidian-skills

   /plugin install obsidian@obsidian-skills

   Check which skills it added:

   claude plugin details obsidian

   The defuddle skill also needs the defuddle tool, which runs on Node.js. Install both only if you want Claude to save web pages as notes:

   brew install node
   npm install -g defuddle

7. 07Step 7: Let Claude search without askingPre-approve the obsidian commands that only read, and keep a prompt for everything else.

   Claude Code asks before it runs any command. For the obsidian commands that only read your vault, that gets old fast, so this step approves them in the vault's .claude/settings.json.

   Commands that change or send notes still ask first. That includes create, move and delete, the sync and publish commands that upload to Obsidian's services, and eval, which runs code inside Obsidian.

   This installs jq, backs up the settings file if you have one, and merges the rules into it:

   brew install jq
   mkdir -p ~/Notes/.claude
   f=~/Notes/.claude/settings.json
   [ -f "$f" ] && cp "$f" "$f.bak-$(date +%Y%m%d-%H%M%S)"
   [ -f "$f" ] || echo '{}' > "$f"
   jq '.permissions.allow = ((.permissions.allow // []) + [
     "Bash(obsidian search *)",
     "Bash(obsidian search:context *)",
     "Bash(obsidian read *)",
     "Bash(obsidian backlinks *)",
     "Bash(obsidian links *)",
     "Bash(obsidian tags *)",
     "Bash(obsidian tasks *)",
     "Bash(obsidian unresolved *)",
     "Bash(obsidian files *)"
   ] | unique)' "$f" > "$f.tmp" && mv "$f.tmp" "$f"

   Rules in a project's .claude/settings.json take effect after you trust that folder, which the next step does. Inside Claude Code, /permissions lists every rule in effect.

8. 08Step 8: Work with your notesStart Claude in the vault, ask it to find, write and link notes, then review every change in Obsidian and Git.

   Keep Obsidian open, then start Claude Code in the vault:

   cd ~/Notes
   claude

   The first time, Claude Code asks whether you trust the folder. Accept, so it can use the rules from the previous step.

   Ask in plain English, for example:

   Find my notes about the kitchen renovation and summarize them, with a link to each note.

   Create a note for today's call with Sam about the budget, and link it to [[Kitchen renovation]].

   List my open tasks across the vault, grouped by note.

   Which notes link to [[Kitchen renovation]], and which links in my vault point to notes that do not exist?

   Make a Base that lists every note tagged meeting, newest first.

   New and changed notes appear in Obsidian right away. Review them in the terminal too:

   cd ~/Notes
   git status
   git diff

   Keep the changes by saving a snapshot:

   git add -A
   git commit -m "Notes from today"

   Or undo Claude's edits to one note, replacing the path with a note from git status:

   git restore "Kitchen renovation.md"

   git restore . undoes the edits to every note since your last snapshot, so commit anything you wrote yourself first.

9. 09Step 9: Reach your notes from any projectGive a coding session access to your vault and its CLAUDE.md, so Claude can read your notes while it works.

   A session normally sees only the folder you start it in. --add-dir gives it your vault as well, and the variable in front makes Claude also read the vault's .claude/CLAUDE.md, so it follows your note rules there:

   cd ~/path/to/your/project
   CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/Notes

   To save typing, add a claude-notes shortcut to ~/.zshrc, only if it is not there yet. It works in new terminal windows.

   grep -q 'alias claude-notes=' ~/.zshrc || echo "alias claude-notes='CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/Notes'" >> ~/.zshrc

   Then, inside any project:

   Read my notes in ~/Notes about this project and turn the open questions into a plan.

   Write a note in ~/Notes that explains how we fixed this bug, and link it to [[Kitchen renovation]].

   In a session that is already open, /add-dir ~/Notes adds the vault without restarting. The permission rules from the permissions step apply only when you start Claude inside ~/Notes, so from other projects it asks before each obsidian command.

10. 10Step 10: Keep Claude's memory in your vaultoptionalPoint a project's auto memory into the vault, so you can read, link and edit what Claude remembers in Obsidian.

    Claude Code keeps notes for itself about each project, called auto memory, in a hidden folder under ~/.claude/projects/. They are Markdown files too, so you can move them into your vault and browse them in Obsidian. Each project keeps its own folder, here ~/Notes/Claude/<project name>.

    Run this from the top folder of a project. It copies the memory Claude already has for that project, without overwriting anything, then sets autoMemoryDirectory in the project's personal settings file:

    cd ~/path/to/your/project
    root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
    dir="$HOME/Notes/Claude/$(basename "$root")"
    old="$HOME/.claude/projects/$(echo "$root" | sed 's/[^A-Za-z0-9]/-/g')/memory"
    mkdir -p "$dir"
    [ -d "$old" ] && cp -Rn "$old"/. "$dir"/
    mkdir -p "$root/.claude"
    f="$root/.claude/settings.local.json"
    [ -f "$f" ] && cp "$f" "$f.bak-$(date +%Y%m%d-%H%M%S)"
    [ -f "$f" ] || echo '{}' > "$f"
    jq --arg dir "$dir" '.autoMemoryDirectory = $dir' "$f" > "$f.tmp" && mv "$f.tmp" "$f"

    settings.local.json is only for you, so keep it out of the project's Git history. This adds it to the repository's local ignore list, which is never committed, and does nothing outside a Git repository:

    cd ~/path/to/your/project
    if git rev-parse --git-dir >/dev/null 2>&1; then
      ex=$(git rev-parse --git-path info/exclude)
      mkdir -p "$(dirname "$ex")"
      grep -qxF '.claude/settings.local.json*' "$ex" 2>/dev/null || echo '.claude/settings.local.json*' >> "$ex"
    fi

    Restart any Claude Code session that is open in the project, because a running session keeps using the old folder. Then check the new location:

    What is the full path of your auto memory folder?

    Claude reads MEMORY.md in that folder at the start of every session: the first 200 lines or 25 KB, whichever comes first. Ask it to remember something, such as "remember that the staging database resets every Sunday", and the note appears in Obsidian under Claude/.

    To go back, delete the autoMemoryDirectory line from .claude/settings.local.json and restart Claude Code.