claude-obsidian Turns Your Vault into a Source-Cited Knowledge Base

Most AI note workflows stop at saving text. claude-obsidian, a 15k-star local-first knowledge system for Claude Code and compatible Agent Skills hosts, is built around a longer loop: capture the source, ground every claim, connect the notes, then put the vault back to work. Your knowledge stays a plain directory of Markdown, JSON, and source files — not a plugin cache or a cloud database.

Why This Skill Matters

The system ships 15 skills that share one evidence model. Five build and use the wiki: wiki (initialize or adopt a vault and route work), save (one scoped answer, never an automatic transcript), wiki-ingest (sources into linked pages with provenance records), wiki-query (read-only answers from vault evidence), and wiki-lint (dead links, orphans, stale indexes). Seven extend the workflow, including autoresearch for bounded web research with explicit egress, wiki-retrieve for BM25 search, and wiki-mode for filing conventions. Three are references: obsidian-markdown, obsidian-bases, and think.

Two design choices separate it from a chat wrapper. Every mutating setup command runs in two phases — it prints a JSON plan with an approved_plan_sha256, and only applies after you pass that exact hash back, so parallel workers return drafts while one orchestrator applies a single recoverable transaction. And the README is explicit about limits: PDF and EPUB capture stores metadata, hash, and size with no built-in semantic extraction, and URL or YouTube capture requires a configured external runner.

Installation

You need Python 3.11 or newer. Clone the product, then initialize a separate vault:

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "2026-09-22T00:00:00Z" --operation-id "init-reviewed"

The command prints a plan. Copy its approved_plan_sha256 and rerun with --approved-plan-sha256 <sha256-from-the-plan> --apply to create the vault. To use an existing Obsidian vault, the README points to the non-destructive adopt workflow in its installation guide.

Then open the vault in Obsidian and start Claude Code from that directory with the local plugin:

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

Real Workflow: Ingest a Source and Query It Back

1. Start from the vault with /claude-obsidian:wiki, then drop a source file into the vault's inbox/ directory.
2. Turn it into linked, source-cited pages:

/claude-obsidian:wiki-ingest

3. Ask a question answered only from vault evidence:

/claude-obsidian:wiki-query

4. Keep an answer worth keeping:

/claude-obsidian:save

Each saved item is scoped — the save skill exists precisely so conversations do not silently become notes.

Real Workflow: Wire Up a Non-Claude Agent Host

For Codex, OpenCode, Gemini, or ZCode, preview and then apply the portable skill links:

bash scripts/setup-multi-agent.sh --host codex
bash scripts/setup-multi-agent.sh --host codex --apply

Cursor and Windsurf use workspace-local skill discovery instead.

Tips

• Run /claude-obsidian:wiki-lint after heavy ingestion days — it reports dead links, orphans, metadata gaps, and empty sections.
• wiki-mode supports Generic (default), LYT, PARA, and Zettelkasten filing; switching modes changes how new notes are routed and never bulk-moves old ones.
• On native Windows, read-only and dry-run commands work but vault writes require WSL — otherwise the command fails closed with an UNSUPPORTED_PLATFORM error.
• The design follows Andrej Karpathy's LLM Wiki pattern and uses kepano/obsidian-skills as the reference substrate for Obsidian syntax.

When Not to Use This

The README draws its own boundaries: this is not an automatic transcript recorder, not a cloud sync service, not a factual oracle, and not a substitute for backups and source control. If your sources are mostly PDFs and EPUBs and you expect semantic extraction out of the box, the capability table is explicit — it stores metadata, hash, and size, with no built-in semantic extraction. And if you want zero ceremony, the plan-then-apply approval flow adds a step to every mutating operation — that friction is the safety model, so it does not switch off.

See the leaderboard for more skills.