Skip to content
Get packs

Guide · Open source

How to use claude-obsidian: install, ingest notes and query your vault

Updated · written with AI from the project's own documentation and checked against our catalogue data

claude-obsidian is a free, MIT-licensed plugin for Claude Code that works with Obsidian. You drop articles, papers or notes into an inbox folder, and Claude reads them, writes linked notes with source references, and files them into one connected graph of plain Markdown files on your computer. This guide shows you how to install it, set up a vault, ingest sources, ask questions and keep useful answers.

claude-obsidianAgriciDaniel/claude-obsidian · ★ 16.1k · MIT

Quick start

  1. 1Check prerequisites. Make sure Claude Code and Python 3.11 or newer are installed. Install Obsidian if you want to browse the graph visually.
  2. 2Add the marketplace. Run the marketplace add command from the README to register AgriciDaniel/claude-obsidian.
  3. 3Install the plugin. Run the plugin install command to install claude-obsidian from the marketplace.
  4. 4Set up the vault. Start Claude Code in your vault folder and run /claude-obsidian:wiki, then approve the preview.
  5. 5Ingest sources. Drop files into inbox/ and run /claude-obsidian:wiki-ingest to create linked notes with sources.
  6. 6Query and save. Ask questions with /claude-obsidian:wiki-query and keep useful answers with /claude-obsidian:save.

What you need before you install

claude-obsidian runs inside Claude Code, so you need Claude Code installed. The README also lists Python 3.11 or newer as a prerequisite, and Obsidian if you want the visual side of the vault.

Windows users should note that the README says WSL is needed for anything that writes to the vault. Native Windows can inspect and preview, but stops with a clear error instead of writing.

  • Claude Code
  • Python 3.11 or newer
  • Obsidian (for browsing the graph and canvases)
  • WSL on Windows if you want to write to the vault

Install the claude-obsidian plugin

Install the plugin with two commands from the README: first add the plugin marketplace, then install the plugin from it.

claude plugin marketplace add AgriciDaniel/claude-obsidian claude plugin install claude-obsidian@agricidaniel-claude-obsidian

Set up your vault and run the core skills

Open the folder you want as your vault, start Claude Code there, and run the setup skill. The README says it shows a preview first, so you can see what will be created before approving it. Existing Obsidian vaults can be adopted without moving your notes.

The five core skills cover the main loop: set up, ingest, query, save and health-check.

  • /claude-obsidian:wiki sets up the vault and shows a preview first
  • /claude-obsidian:wiki-ingest turns what is in inbox/ into linked notes
  • /claude-obsidian:wiki-query asks a question, answered from your notes
  • /claude-obsidian:save keeps a good answer as a note
  • /claude-obsidian:wiki-lint runs a health check for dead links, orphans and gaps
claude /claude-obsidian:wiki /claude-obsidian:wiki-ingest /claude-obsidian:wiki-query /claude-obsidian:save /claude-obsidian:wiki-lint

Ingest sources and check the results in Obsidian

Put articles, papers, transcripts or your own notes into inbox/. The README says the originals are kept untouched, so every summary can point back to its source. Run wiki-ingest to have Claude write linked pages with sources recorded.

Then open the same folder in Obsidian using Open folder as vault. You can browse the result in Graph view or lay it out on an Obsidian Canvas.

  • Originals in inbox/ are kept untouched
  • Claude writes linked pages, indexes and maps of content
  • Everything stays as plain Markdown files on your computer

Ask questions and save the good answers

wiki-query answers from what the vault already contains, with citations, and does not change any files. Nothing is written to your notes unless you ask for it.

The save skill keeps a single answer or insight as a note, only when you request it.

  • Use wiki-query for read-only answers with citations
  • Use save to keep one answer as a note

Use claude-obsidian in other AI tools

The README says claude-obsidian is a set of Agent Skills and also works in Codex, OpenCode, Gemini, ZCode, Cursor and Windsurf. Those hosts need extra setup, which the README handles with a multi-agent script that previews first and applies only with a flag. Cursor and Windsurf need a workspace folder.

bash scripts/setup-multi-agent.sh --host codex # preview, writes nothing bash scripts/setup-multi-agent.sh --host codex --apply # link the skills

What people use it for

  • Organizing research papers and articles into linked notes with source references
  • Asking questions of your own notes and getting answers with citations
  • Running a health check to find dead links and orphan pages in a growing vault
  • Turning meeting transcripts or personal notes into a connected Obsidian graph

Frequently asked questions

Is claude-obsidian free?

The README says claude-obsidian is free, open source and MIT licensed. Your notes are plain Markdown files on your own computer, with no cloud database. Claude Code itself is a separate tool you need to have set up.

What do I need to install claude-obsidian?

You need Claude Code, Python 3.11 or newer, and Obsidian if you want the visual side. Install the plugin with the marketplace add and plugin install commands in the README.

Does claude-obsidian work on Windows?

The README says WSL is needed for writing to the vault. Native Windows can inspect and preview, but stops with a clear error instead of writing.

Can I use claude-obsidian with an existing Obsidian vault?

Yes. The README says the wiki setup skill can adopt an existing vault without moving your notes. The installation guide in the repository walks through the steps.

How does claude-obsidian compare to Obsidian Smart Connections, Logseq or Khoj?

Smart Connections, Logseq and Khoj are comparable projects. claude-obsidian is built around Claude Code and an ingest-and-link workflow over plain Markdown files. Choose it if you already use Claude Code; choose another tool if you do not.

Do I need Claude Code to use it?

Yes. The plugin is built for Claude Code. Other hosts are listed in the README, but they need extra setup.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

claude-obsidian suits people who already use Obsidian, are comfortable running Claude Code in a terminal, and want their notes kept as plain Markdown they own. It is a poor fit if you do not use Claude Code, want to write to the vault natively on Windows, or want a hosted, cloud-synced note app.

Install options & downloads