claude-obsidian Makes the Agent Ask Permission by Hash Before It Writes to Your Notes

The MIT-licensed Obsidian vault system for Claude Code is trending as an AI second brain. The interesting part is the write gate: nothing lands in your notes until you paste a SHA-256 back into the terminal.

Setting up claude-obsidian means running the same command twice. The first run does not create your vault. It prints a JSON plan describing exactly what it intends to do and hands you a field called approved_plan_sha256. You read the plan. Then you run the command again with that hash and --apply, and only then does anything hit disk. If the filesystem drifted between the two runs, the apply fails rather than proceeding.

That is the setup command. The same shape governs every mutating operation in the system.

Most repositories in the "AI second brain" category work the opposite way. You point a coding agent at a folder of notes, it writes, and you find out what happened by reading a diff later, if you read it at all. claude-obsidian is being passed around this week as note-taking software, and it does that job. The part worth stealing is the write gate.

Why a write gate is the whole story here

Handing an agent your knowledge base is a strange thing to be casual about. Code has git, a test suite, and a reviewer. Your notes have none of that. Most people's vaults are the least backed-up, least version-controlled directory on the machine, and they are also the one place where a silent overwrite destroys something you cannot regenerate. You will notice a broken build in ninety seconds. You will notice that a note got flattened in March, sometime in November.

So the question that decides whether an agent belongs anywhere near a vault is not how good its summaries are. It is what happens on the write.

claude-obsidian's answer, from the README, is that one logical knowledge operation is one recoverable transaction. Read every target and record its expected SHA-256. Let parallel workers return drafts and evidence only. Merge the complete change into a single operation bundle. Inspect the bundle. Apply it once. Report the operation ID and the exact changed paths.

Read the second step again, because it is the one that separates this from a prompt telling an agent to be careful. Workers cannot write. Subagents doing ingestion or research return drafts, and exactly one orchestrator inspects and applies. The project's phrasing for the result is that parallel agents cannot race the vault. If you have ever watched two subagents both decide to rewrite the same index file, you know why that sentence matters.

Underneath, the core holds a single process-lifetime vault lock, journals backups, uses atomic replacement, and restores the prior state if an apply cannot finish. A target that changed since the plan was built counts as a conflict and stops the operation. It is never a silent overwrite.

Vault selection is fail-closed too. The product refuses to treat its own checkout, a plugin cache, or contributor state as your vault. It resolves through the CLAUDE_OBSIDIAN_VAULT variable, the nearest .claude-obsidian.json, or one unambiguous initialized ancestor, and if selection is uncertain the command exits without writing. That single behavior would have saved a lot of people a lot of grief in this category.

The grounding layer, and where it stops

The knowledge side is built around source and claim ledgers. Captured sources are stored as immutable content-addressed copies before anything gets synthesized, so the summary never becomes the only surviving artifact. Between them the two ledgers retain authority, freshness, support, contradiction, confidence, and review state. Accepting a high-risk claim requires two independent sources, and the URL identity check collapses equivalent spellings (IPv6 forms, internationalized domains, default ports, percent-encoding) before it will count two sources as independent, which is a detail you only write if someone has already fooled your citation counter.

Unsupported and contradictory evidence stays visible rather than being smoothed away, and the documented preference is a grounded refusal over an invented citation.

Retrieval is deterministic BM25 by default. Optional contextual prefixes and semantic reranking exist, they require explicit egress consent, and when the embedding or reranking stage cannot be trusted the system falls back to deterministic BM25 rather than serving a degraded ranking silently.

Fifteen skills sit on top. The core five are wiki to initialize or adopt a vault and route work, save to persist one scoped answer (never an automatic transcript), wiki-ingest to turn captured sources into linked pages with provenance records, wiki-query for read-only answers from vault evidence, and wiki-lint for dead links, orphans, metadata gaps, and stale indexes. Around them sit autoresearch for bounded web research with a separate canonical merge, defuddle for cleaning web content before ingestion, canvas, wiki-fold, wiki-mode, wiki-retrieve, and wiki-cli, plus three reference skills: obsidian-markdown, obsidian-bases, and think. Query and lint are read-only by design; repairs are separate reviewed operations. wiki-mode routes new notes by Generic, LYT, PARA, or Zettelkasten conventions and does not reorganize existing notes when you switch.

Lineage is stated openly: the design follows Andrej Karpathy's LLM Wiki pattern, and kepano/obsidian-skills is the reference substrate for Obsidian syntax. MIT licensed.

Put this into practice

Lowest-friction path, on a throwaway vault first.

Clone the repo and keep it separate from your notes. The checkout is the product, not the vault, and the tool will refuse to confuse the two.

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

Initialize a new vault somewhere that is not your real one. Pin the timestamp and operation ID, read the plan it prints, copy the hash, run it again with --apply.

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"
python3 scripts/claude-obsidian.py init "$HOME/Documents/TestVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

Then start Claude Code from inside the vault directory with the local plugin, run /claude-obsidian:wiki to check readiness, drop a file into inbox/, and run /claude-obsidian:wiki-ingest. Ask it something with /claude-obsidian:wiki-query, then keep the answer with /claude-obsidian:save, which is the only way anything from a conversation persists. Run /claude-obsidian:wiki-lint and see what it says about the mess you just made.

If you already have a vault you care about, there is a non-destructive adopt workflow with the same plan-and-apply two-step. I would still take a copy first. The transaction core is careful, and adopting a real vault is exactly the operation where careful software meets a directory nobody has ever tested against.

For Codex, OpenCode, or Gemini, bin/setup-multi-agent.sh --host codex previews the skill links and takes --apply to write them. Cursor and Windsurf pick up workspace-local skills.

And the transferable move, if you do not want a new note system at all: put a plan-and-apply gate on whatever agent already writes to files you would miss. Print the intended operation, hash it, require the hash back, verify the targets have not changed, apply once, report the changed paths. That is maybe an afternoon of work around an existing tool, and it converts "the agent edited something" into "I approved this exact edit."

Honest limitations

The capability table in the README is unusually frank, and it costs the project some of its own pitch.

PDF and EPUB are metadata, hash, and size only. There is no built-in semantic extraction. Images give you metadata, hash, size, and bounded dimensions. URL and YouTube capture produce validated consent plans but need a configured external runner, and so does OCR. For a system marketed on dropping any source into an inbox, a large share of the sources knowledge workers actually have require you to wire up something else first. Local text and Markdown are the well-supported path.

Native Windows cannot write to a vault. Read-only inspection and dry runs work; mutation refuses before any side effect with an UNSUPPORTED_PLATFORM error, and you need WSL. Approval hashes bind to the reviewing environment, so you have to review inside WSL if that is where the apply happens. Shell setup scripts and shell test suites are POSIX only.

Version signals disagree, and they disagree badly enough that I could not resolve them. Two separate reads of the same repository within the same hour returned different states. One pass showed a README badge reading v2.1.1 and a changelog whose newest entry was dated August 26, 2026, describing legacy migration safety fixes and Windows guidance. Another pass showed a badge reading v2.1.0 and a changelog topping out at v1.9.2 from late May. Live release queries came back v2.0.0 and v2.1.1 on different attempts, while GitHub's own releases page lists v1.9.2 as the latest tagged release. Some of that is caching, some of it is a repository being pushed to hard during a trending week. Check what version you actually have with the changelog inside your own checkout, and do not trust a badge.

Star counts disagree too. A live shields.io query returned 14k the morning I wrote this; GitHub's repository page read 10k the same day; the trending board that surfaced it said roughly 11k; third-party skill directories still list 11.1k. These are momentum figures, not measurements, and none of them tell you whether the code is good.

The ceremony is real friction. Every mutating command is a two-step with a hash you paste by hand. That is the design working as intended, and it is also the kind of thing people route around at 11pm when they just want the note saved. Whether the discipline survives contact with your actual habits is the honest open question, and it is the one I cannot answer for you.

One caution before you clone. A search for this project surfaces more than one repository carrying the same description under different accounts, which is normal for anything trending and also exactly the situation where people install the wrong thing. Read the account name before you hand a checkout write access to your entire knowledge base.

What to take from it

What earns my attention here is a project that ships a capability table listing what it cannot do, in the same README that pitches the product. PDF extraction missing, OCR missing, Windows writes refused. Most repos in this category put that information nowhere, and you find it out on a Tuesday when the ingest silently produced a note containing a filename and a hash.

Try it on a vault you would not miss. Watch the two-step apply once or twice and decide whether that friction is worth what it protects. If you decide the note-taking is not for you, take the write gate anyway. The pattern is small, it is not specific to Obsidian, and it belongs in front of every agent you have given a filesystem.

Sources: AgriciDaniel/claude-obsidian README; claude-obsidian CHANGELOG; kepano/obsidian-skills; live shields.io star and release queries, August 27, 2026.