# claude-obsidian

> A free, MIT-licensed Claude Code plugin that turns Obsidian into a self-organizing AI second brain, automatically ingesting sources into linked plain-Markdown notes you own.

claude-obsidian is a local-first knowledge system built by Agrici Daniel that runs as a Claude Code plugin and compatible Agent Skills host. It implements Andrej Karpathy's LLM Wiki pattern—keeping notes as plain Markdown an LLM can read and write directly, with no vector database or embeddings server required. The project is MIT-licensed, free to use, and actively maintained on GitHub with over 10,000 stars.

## What It Is

claude-obsidian is a personal knowledge management (PKM) tool that automates the filing, linking, and maintenance work that causes most note vaults to stagnate. Instead of asking users to tag, link, and organize manually, it uses Claude to read source material, extract named entities and concepts, write linked wiki pages, and cross-reference everything against what is already in the vault. The output is a normal directory of Markdown files that opens in Obsidian, a text editor, or any plain-text tool—now and in the future.

The design follows Karpathy's LLM Wiki pattern, which skips traditional vector search in favor of plain Markdown that a language model can read directly. Three core files anchor the system: a hot cache of recent context, an index, and the wiki pages themselves.

## How the Workflow Operates

The core loop has two active steps and one passive one:

- **Drop a source.** Drag a PDF, paste a URL, or dump a transcript into the `inbox/` folder. Originals are never modified—they remain as immutable records.
- **Run `/wiki-ingest`.** The skill reads the source, extracts entities (people, tools, companies), identifies concepts and frameworks, creates or updates wiki pages, adds cross-references, and flags contradictions with existing knowledge.
- **Query and reuse.** `/wiki-query` answers read-only from vault evidence. `/autoresearch` runs bounded web research and grows the graph up to 12 pages hands-free. `/save` files a conversation as one clean linked note.

The project claims that a 20-page PDF becomes 8–15 connected wiki pages in a single command, with no manual folders, tags, or links.

## 15 Skills Across the Full Lifecycle

As of v2.1.0, claude-obsidian ships 15 skills organized into three groups:

**Build and use the wiki:** `wiki`, `save`, `wiki-ingest`, `wiki-query`, `wiki-lint`

**Extend the workflow:** `autoresearch`, `canvas`, `defuddle`, `wiki-fold`, `wiki-mode`, `wiki-retrieve`, `wiki-cli`

**Reference skills:** `obsidian-markdown`, `obsidian-bases`, `think`

The `wiki-mode` skill supports four methodology conventions—Generic, LYT, PARA, and Zettelkasten—routing new notes accordingly without reorganizing existing ones. The `/think` skill adds a 10-principle structured reasoning loop for audits and ambiguous decisions.

## Architecture and Trust Model

The product enforces a strict boundary between the source checkout and the user vault. A vault is selected explicitly via environment variable, a `.claude-obsidian.json` config, or an unambiguous initialized ancestor—never inferred. Every mutating operation follows a plan-then-apply transaction model: the system reads targets, records SHA-256 hashes, lets parallel workers return drafts only, merges changes into one operation bundle, and applies it once with atomic replacement and backup journaling. A changed target is a conflict, never a silent overwrite.

Multi-writer safety uses per-file advisory locking so several agents can ingest concurrently without corrupting the vault. The hot cache—roughly 500 words of recent context—restores working memory at the start of each new conversation, avoiding the token cost of re-establishing context from scratch.

## Update: v2.1.0 — Native Windows Compatibility

The latest release, v2.1.0 (published July 31, 2026), adds native Windows compatibility to the portable surface. CI exercises Linux, macOS, and a native-Windows smoke job. On native Windows (including Git Bash), read-only inspection and dry-run commands work; vault writes require WSL and fail closed with an `UNSUPPORTED_PLATFORM` error. The v1.9 "Compound Vault" arc, which preceded v2.x, introduced hybrid retrieval (contextual prefix + BM25 + cosine rerank), methodology modes, multi-writer safety, and the `/think` skill. The project's GitHub repository shows active development with the last push on August 1, 2026.

## Why It Matters for Local-First PKM

Unlike cloud-based knowledge tools, claude-obsidian stores everything as plain Markdown on the user's disk. There is no proprietary export format, no background worker, no embeddings server to host, and no subscription for the plugin itself. Users pay only for Claude API token usage. The vault remains fully browsable in Obsidian—graph view, canvas, full-text search—even when no AI is running. This local-first, data-ownership model positions it as an open-source alternative to cloud-locked knowledge apps for developers, researchers, and knowledge workers who want to own their second brain.

## Features
- 15 skills covering the full knowledge lifecycle
- Automated source ingestion with entity and concept extraction
- Linked wiki page creation and cross-referencing
- Hot cache for session context restoration
- Hybrid retrieval: contextual prefix, BM25, and cosine reranking
- Methodology modes: Generic, LYT, PARA, Zettelkasten
- Multi-writer safety with per-file advisory locking
- Autonomous research up to 12 pages hands-free
- Obsidian Canvas creation and maintenance
- Structured /think reasoning loop
- Transaction-safe vault writes with SHA-256 verification
- Plain Markdown output with no vendor lock-in
- Obsidian graph view and full-text search compatibility
- Portable CLI for vault init, adopt, migrate, lint, and recover
- MIT licensed and fully open source

## Integrations
Obsidian, Claude Code, Claude API, Agent Skills, Codex, OpenCode, Gemini, Cursor, Windsurf, Obsidian CLI, Ollama, defuddle, BM25, n8n

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v2.1.0

## Links
- Website: https://agricidaniel.com/blog/claude-obsidian-ai-second-brain
- Documentation: https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md
- Repository: https://github.com/AgriciDaniel/claude-obsidian
- EveryDev.ai: https://www.everydev.ai/tools/claude-obsidian