Every write is bound to a reviewed hash
claude-obsidian treats an Obsidian vault as a small knowledge database made from ordinary files. Sources enter through an inbox, immutable copies are retained, and the agent creates linked notes plus ledgers for claims and provenance. Queries read the existing evidence instead of answering from an untracked chat context. The vault remains Markdown, JSON, and source files that still make sense without the agent or a proprietary storage service.
The unusual part is its write discipline. A mutating command first emits a JSON plan with an approval SHA-256. The user reviews it and supplies that exact hash on the apply run. Targets are checked again, writes are journaled, and conflicts stop rather than overwrite changed data. Parallel workers return drafts to one orchestrator instead of racing the vault. This is slower than letting an agent edit freely, but notes often outlive the session that produced them.
Fifteen skills cover much more than saving chat
The package includes 15 skills for ingestion, querying, linting, retrieval, research, Canvas views, Obsidian formatting, filing methods, and explicit saving. wiki-mode can route new notes using generic, LYT, PARA, or Zettelkasten conventions without moving existing material. BM25 retrieval works locally, while model-based reranking is optional and subject to an egress decision. Claude Code gets namespaced commands, and setup scripts can link skills for Codex, OpenCode, or Gemini.
Capability limits are stated with useful precision. Local files receive bounded content-addressed capture. Images get metadata and dimensions when available. PDF and EPUB files get metadata, hashes, and sizes, but no built-in semantic extraction. URL, YouTube, and OCR operations need an external runner. Anyone shopping for a universal drop-box that understands every format should stop there. This project is an evidence and mutation framework, not a bundled parser for all media.
What happened when we ran it
Our sandbox installed 35 Python packages in 12 seconds and used 37 MB on disk. The build succeeded in 4 seconds. Pytest then ran for 579 seconds and reported 458 passed, 5 failed, and 5 skipped out of 463. There were also 55 passing subtests. Pip-audit found 0 known vulnerabilities in the installed packages. We tested commit 1c1bc49 with Python 3.12, 3 CPUs, and 8 GB of RAM.
Four failures came from tests/test_setup_wrappers.py. Their log tails showed VAULT_SENTINEL_MISSING for /work/repo, with expected and actual exit codes disagreeing. The fifth, test_ten_concurrent_address_transactions_remain_consistent, recorded a TransactionConflict saying the vault mutation lock was held. The log does not prove why those conditions arose. It does prove that the complete suite at this commit did not pass in our fresh unprivileged container.
The repository contained 201 files and about 41,534 lines of source, with one CI workflow and a tests directory. It had no Dockerfile. The 37 MB installed size is modest, but the 573.23-second pytest summary makes full verification a real wait. Release 2.1.1 was published after the measured commit and describes additional migration safety; our numbers must not be read as a test of that later release artifact.
Windows writes require WSL, and iCloud needs caution
The portable core requires Python 3.11 or newer. Obsidian supplies the visual experience but is not required to read the Markdown. Native Windows supports inspection and dry runs, while vault writes require WSL and fail with UNSUPPORTED_PLATFORM otherwise. Approval hashes bind to the reviewing environment, so a Windows user must review and apply inside WSL rather than copy a hash from another context. Bash remains necessary for setup and shell tests.
Open issue 168 reports frequent 5-second SessionStart and Stop hook timeouts across 48 Windows sessions on one machine. The reporter observed the problem under real Claude Code startup load and offered possible causes, but did not isolate one. Issue 157 describes an iCloud-backed vault where recovery reported changing journals even when no process modified the runtime directory. The same report found normal behavior after Obsidian closed and iCloud settled. These are concrete reasons to trial a copied vault on the intended filesystem.
Broken relative references can leave agents without contracts
Issue 170 identifies 18 links across 13 skill files that point to shared contracts using paths relative to the skill file. The documented working directory is the user's vault, where those paths do not exist. The report says one agent continued without the contracts and produced an incorrect address plus an invented source ID format. That is exactly the kind of silent degradation the project's trust model tries to prevent.
The issue was filed against version 2.1.0 and commit 1c1bc49. Users should verify whether their installed release resolves those documents before relying on ingestion. A missing reference is more serious here than a broken help link because the contracts define provenance and transaction behavior. Release upgrades are separate from vault migration, so check both the product version and the copied or linked integration files.
Active maintenance has not removed the backup requirement
GitHub showed 13,338 stars, 136 combined issues and pull requests, and a last push on August 26, 2026. Release 2.1.1 arrived on August 25 with legacy migration hardening and clearer Windows guidance. Current work includes citation-link fixes and checkpoint behavior. The dated push and issue activity show active maintenance, while the open platform reports show a product still discovering difficult filesystem cases.
The README plainly says this is not a substitute for backups or source control. Take that literally. Initialize a separate test vault, inspect the first plan, exercise recovery, and only then adopt existing notes. The 458 passing tests show considerable engineering around safety; the 5 failures prevent a clean recommendation. For a careful Claude Code user, that trade can be acceptable. For a casual note taker, it is more machinery than the job needs.