A knowledge system, not a chat window
claude-obsidian takes a more serious view of AI notes than tools that simply paste a model response into a folder. It keeps captured source bytes, source and claim ledgers, linked Markdown pages, indexes, operation history, and retrieval data in a normal Obsidian vault. Claude Code or another Agent Skills host supplies the reasoning and writing workflow, while Obsidian supplies browsing, links, graph views, Canvas, and long-term ownership of the files.
The system is organized around fifteen skills. Core actions initialize or adopt a vault, ingest material, answer from existing evidence, save a scoped insight, and lint the resulting wiki. Other skills add research, web cleanup, Canvas views, filing methodologies, log rollups, retrieval, and Obsidian-specific syntax. The idea is not to record every conversation. It is to preserve selected knowledge with enough source context that a later agent or human can inspect where a claim came from.
That distinction is valuable. AI-generated notes become less trustworthy as they accumulate if summaries lose their sources or quietly overwrite contradictions. claude-obsidian keeps unsupported and conflicting evidence visible, requires stronger support for high-risk claims, and prefers a grounded refusal to a fabricated citation. These are good defaults for a personal archive meant to last.
Safety adds real operational ceremony
The quick start is longer than the usual plugin install. Users clone a product repository, create or adopt a separate vault, generate a dated operation plan, inspect its JSON and approval hash, then rerun with that exact hash to apply. Claude Code starts from the vault with an explicit --plugin-dir. Codex, OpenCode, and Gemini use a preview-and-apply linking script, while Cursor and Windsurf depend on workspace-local skill discovery.
This separation protects the vault from a mistaken checkout or ambiguous working directory. Writes use expected file hashes, one process-lifetime lock, backups, atomic replacement, and a journal that can restore an interrupted operation. Parallel workers may produce drafts, but one orchestrator merges and applies one transaction. If a target changed after review, the operation conflicts instead of overwriting it.
For a careful user, those guarantees justify the extra steps. For someone who wants an assistant to watch every conversation and file notes silently, they will feel heavy. Approval hashes are tied to the environment where the plan was reviewed. Migrations, captures, repairs, checkpoints, and research merges remain explicit. This project asks the operator to understand when the vault changes rather than treating consent as a one-time settings toggle.
Local-first has precise boundaries
The vault remains ordinary Markdown, JSON, source files, and ignored runtime metadata. Deterministic BM25 retrieval works locally. Optional remote models, contextual prefixes, and research require explicit network permission. Ollama can provide local cosine reranking, and Obsidian itself is optional if plain files are enough. This is a credible ownership story, but it does not mean every workflow works offline or every source format is understood.
The capability table is admirably specific. Local files can be captured as bounded, content-addressed bytes. Images receive metadata, hashes, sizes, and dimensions when available. PDFs and EPUBs receive metadata, hashes, and sizes, but there is no built-in semantic extraction. URL, YouTube, and OCR operations require configured external runners. Users expecting a polished NotebookLM-style import experience will have assembly work ahead.
Sync and backup are outside scope. That matters because an accumulating vault becomes difficult to recreate. The README says the project is not a cloud sync service or backup substitute. Issue #157 reports that an iCloud-hosted vault on macOS produced repeated false CORRUPT_RUNTIME_STATE failures while the file provider was active, plus a read-speed cost. Even if that specific behavior is fixed, it illustrates why filesystem transaction checks and consumer sync engines can interact badly. Keep tested, independent backups and prove any multi-device workflow on a copy first.
Platform and release rough edges
Python 3.11 or newer is required, along with Bash for setup and optional shell features. Version 2.1.0 improved native Windows behavior after every vault command had crashed on an unavailable operating-system feature. Read-only inspection, dry runs, and retrieval now work natively with Windows-specific safety checks. Writes deliberately stop before side effects and direct the user to WSL. This is safe behavior, but it disqualifies the product for people who cannot or will not maintain a WSL environment.
A newer open report concerns the same 2.1.0 release on Claude Code 2.1.49. Its author found that lifecycle hooks declared a separate argument array that current Claude Code ignored, causing bare Python to read the hook's JSON input and fail. The skills remained usable, but session start and stop hooks did not run. This is a concrete integration regression in a young plugin, and prospective users should check its resolution or test hooks before trusting lifecycle behavior.
The repository was pushed on August 1, 2026, one day after the 2.1.0 release. Issues and pull requests were still being updated through August 10, and GitHub reports 128 open issues and PRs together. More than 10,000 stars since an April launch indicate intense interest, not years of proven stability. The project moves quickly and its reports are unusually detailed, but operating contracts are still meeting real platforms.
Worth it for deliberate knowledge work
claude-obsidian is one of the more credible attempts to make an agent maintain a human-owned knowledge base without giving it unchecked write access. The plain-file format, provenance model, explicit capability boundaries, and recoverable operations address problems that simpler AI note plugins ignore. Documentation is excellent and candid about missing extraction, sync, and backup.
The price is complexity. Users must manage a source checkout, host integration, approval flow, optional tools, and a separate backup strategy. Start with a disposable vault, ingest representative sources, inspect every generated page, and test recovery before adopting an important archive. For careful Claude Code users, that effort buys meaningful control. For everyone else, a smaller Obsidian skill set or an in-app assistant will be easier to live with.