# claude-obsidian: a source-cited second brain for Obsidian and Claude Code

> claude-obsidian turns local sources into linked, provenance-tracked Markdown pages inside a vault you own. The transaction model is careful to the point of friction, and that trade-off decides who should use it.

**AgriciDaniel/claude-obsidian** — Self-organizing AI second brain for Obsidian + Claude Code. Drop any source and Claude reads, links, and files it into one connected knowledge graph of plain Markdown you own. AI note-taking, personal knowledge management (PKM), and an open-source Notion alternative. Based on Karpathy's LLM Wiki pattern.

- Repository: https://github.com/AgriciDaniel/claude-obsidian
- Website: https://agricidaniel.com/blog/claude-obsidian-ai-second-brain
- Stars: 15,311 · Forks: 1,522
- Language: Python
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/agricidaniel-claude-obsidian

## The problem claude-obsidian is built around

Most AI note workflows end at the point where text has been saved. The transcript exists, the summary reads well, and six weeks later nobody can say which sentence came from which source. claude-obsidian is aimed at that gap. The README frames the project as a repeatable loop: retain the source, ground the claims, connect the knowledge, then put it back to work. That is a narrower promise than an AI note-taker, and a more demanding one.

The intended user is someone who already keeps an Obsidian vault and already runs Claude Code, or another host that supports Agent Skills. The repository describes it as a local-first knowledge system for Claude Code and compatible Agent Skills hosts. The vault stays a normal directory of Markdown, JSON, and source files. According to the README, it is not hidden in a plugin cache, not locked in a cloud database, and not silently uploaded to a model. Network egress is described as a separate, explicit decision.

The README is equally clear about what it is not: not an automatic transcript recorder, not a cloud sync service, not a factual oracle, and not a substitute for backups and source control. That list matters more than the feature list, because it tells you where the project expects you to bring your own discipline.

## How the capture, ledger, and transaction model actually works

Ingestion starts from a visible inbox. Local sources arrive there, and the README states that immutable, content-addressed copies are preserved before synthesis. Synthesis produces linked Obsidian pages, and those pages point back to the durable source evidence rather than to a paraphrase. Source and claim ledgers carry authority, freshness, support, contradiction, confidence, and review state. Unsupported and contradictory claims stay visible instead of being smoothed away.

The mutation model is the part that separates this project from a folder of scripts. The README states that parallel agents cannot race the vault: workers return drafts, and one orchestrator inspects and applies one recoverable transaction. Every mutating setup command previews its exact operation before it can apply, and the apply step requires the approved plan hash. The Makefile exposes clean-test-state, which removes .vault-meta/mutation.lock, .vault-meta/transactions, .vault-meta/capture, and .vault, so the lock and transaction directories are real artefacts on disk rather than abstractions.

The capability surface is fifteen skills, grouped into wiki work (wiki, save, wiki-ingest, wiki-query, wiki-lint), workflow extensions (autoresearch, canvas, defuddle, wiki-fold, wiki-mode, wiki-retrieve, wiki-cli), and reference skills (obsidian-markdown, obsidian-bases, think). wiki-retrieve is described as combining contextual prefixes, BM25, and optional cosine reranking. autoresearch is bounded web research with explicit egress and a separate canonical merge, which is the only place the README admits network access into the loop.

## Installing claude-obsidian and running a first ingest

Installation is a source checkout, not a package manager. The README's quick start clones the repository and treats that checkout as the product, not as your knowledge vault. Clone it somewhere stable first, because the plugin directory path is passed explicitly later.

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

Initialization runs against a separate vault directory. The first invocation is a preview: it prints a JSON plan and does not write. The README sets two environment variables and passes them to the script, then asks you to copy the approved_plan_sha256 out of the plan output.

```bash
export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"
```

The second invocation repeats the same arguments and adds the hash plus --apply. This is the operation that actually creates the vault.

```bash
python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply
```

With the vault created, open that directory in Obsidian and start Claude Code from inside it, pointing at the checkout as a plugin directory. The README then suggests starting with the wiki skill, placing a source in inbox/, and invoking wiki-ingest. Answers are only kept when you run save explicitly.

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

/claude-obsidian:wiki
/claude-obsidian:wiki-ingest
/claude-obsidian:save
/claude-obsidian:wiki-query
```

For hosts other than Claude Code, the README points at a setup script that previews and then applies portable skill links. Codex is shown as the example host, and the same script takes --apply to make the change real. Cursor and Windsurf use workspace-local skill discovery instead, and the README defers marketplace setup, vault adoption, upgrades, and uninstall to docs/install-guide.md.

```bash
bash bin/setup-multi-agent.sh --host codex
bash bin/setup-multi-agent.sh --host codex --apply
```

## Where claude-obsidian gets in your way

The hash-gated write is the honest answer to a real problem, and it is also the largest cost. A two-step init with a copied SHA-256 is fine once. Applied to every ingest, it is a manual confirmation step that a fast capture workflow will feel. The README does not document rollback for an applied transaction, so the recovery story for a bad apply is not described there. Treat the transaction directory as the thing to inspect, not as a documented undo.

Scope is the second constraint. The README states plainly that this is not an automatic transcript recorder. If your habit is to let a tool record meetings and summarise them, this is the wrong shape: save is described as saving one scoped answer or insight, never an automatic transcript. It is also not a factual oracle, so the ledgers record confidence and contradiction rather than resolving them for you.

Host support is uneven by design. Claude Code gets namespaced invocations such as /claude-obsidian:wiki-lint. Other hosts use their native Agent Skills invocation, and the README says trigger phrases and exact contracts live in each skill directory. Cursor and Windsurf are limited to workspace-local skill discovery. The README also notes that optional tools are detected and missing adapters degrade clearly rather than being simulated, which is a reasonable stance but means a capability can simply be absent on your machine.

Finally, there is no cloud sync and no packaged release channel described in the README. Your vault is a directory, and keeping it consistent across machines is your problem, handled with the backups and source control the README says it does not replace.

## claude-obsidian against a RAG pipeline and against Notion

The nearest technical alternative is a retrieval-augmented generation pipeline over your notes: chunk the files, embed them, and let a model answer from the retrieved passages. claude-obsidian overlaps with that at query time, since wiki-query answers read-only from relevant vault evidence and wiki-retrieve combines contextual prefixes, BM25, and optional cosine reranking. The difference is what persists. A typical RAG pipeline leaves the index as the artefact and the answer as the output. claude-obsidian writes linked pages and provenance records back into the vault, so the ingest itself is the product and the query is one consumer of it. If you only ever ask questions and never want new files, a plain index is less work.

The other comparison people reach for is Notion. Notion stores pages in a hosted workspace with its own database and sharing model. claude-obsidian stores Markdown, JSON, and source files in a directory you control, and the README's claim is that the vault remains useful with or without an agent. The trade is real in both directions: you give up hosted sync, collaborative editing, and a managed database, and you take on file layout, backups, and the transaction workflow. For a single engineer who already lives in Obsidian, that is usually a good trade. For a team that needs shared editing, it is not.

## Maintenance, releases, and the MIT licence

The repository is not archived, and the last push was on 2026-08-25, which is recent enough that the project is being worked on. The release history is short and specific: v2.1.1 (Legacy Migration Safety) on 2026-08-25, v2.1.0 (Native Windows Compatibility) on 2026-07-31, and v2.0.0 (Reliability and Evidence Refoundation) on 2026-07-29. Two of the three most recent releases are about safety and reliability rather than new features, and the legacy migration release in particular suggests the on-disk format has moved enough to need a migration path.

That has an upgrade consequence worth naming. Because the vault holds .vault-meta state alongside your notes, an upgrade is not only a code change; the release names imply schema and migration work on existing vaults. The README points upgrades at docs/install-guide.md, and the adopt workflow there is the documented route for an existing Obsidian vault. Anyone running v1-era data should read the v2.1.1 notes before pulling.

The project is MIT licensed. That permits commercial and private use and modification, and it requires the licence and copyright notice to be preserved. This is a description of the licence text, not legal advice; if you redistribute the project inside a product, have your own counsel read LICENSE and ATTRIBUTION.md, which the repository carries as separate files.

## Conclusion

Adopt claude-obsidian if you already run Claude Code, keep notes as plain files, and want claims tied back to sources you can reopen. Skip it if you want automatic transcription, cloud sync, or a one-step install, and skip it if you are not willing to review a hash before a write is applied. Before committing a real vault, run the init preview against a scratch directory, confirm the JSON plan matches what you expect, and read docs/install-guide.md for the non-destructive adopt path.

## FAQ

### Can Claude work with Obsidian through claude-obsidian?

Yes. claude-obsidian is a local-first knowledge system for Claude Code and compatible Agent Skills hosts, and it works on a vault that stays a normal directory of Markdown, JSON, and source files. You run Claude Code from inside the vault directory with the plugin directory pointed at the checkout.

### How do I install claude-obsidian?

Clone the repository, then run scripts/claude-obsidian.py init against a separate vault directory. The first run prints a JSON plan and does not write; you copy its approved_plan_sha256 and repeat the command with --apply. The full installation guide is docs/install-guide.md.

### What is a claude-obsidian vault?

It is the directory you initialize with the init command and open in Obsidian. It holds plain Markdown, JSON, and source files plus .vault-meta state for locks and transactions, and the README states it is not hidden in a plugin cache or locked in a cloud database.

### What does claude-obsidian do?

It turns captured sources into linked, source-cited Obsidian pages, answers read-only from the evidence already in the vault, and provides workflows for research, retrieval, maintenance, and visual mapping. The README describes the loop as retain the source, ground the claims, connect the knowledge, then put it back to work.

### Is claude-obsidian free?

The repository is MIT licensed, which permits commercial and private use with the licence and copyright notice preserved. That covers the project itself; it says nothing about what you pay for Claude Code or any other host you run it under.

### How is claude-obsidian different from a RAG setup?

wiki-query answers read-only from vault evidence and wiki-retrieve combines contextual prefixes, BM25, and optional cosine reranking, so retrieval overlaps with a RAG pipeline. The difference is that ingestion writes linked pages and provenance records back into the vault, so the notes persist as the artefact rather than the index alone.

## Sources

- [Official documentation](https://agricidaniel.com/blog/claude-obsidian-ai-second-brain)
- [Official README](https://github.com/AgriciDaniel/claude-obsidian#readme)
- [Project repository](https://github.com/AgriciDaniel/claude-obsidian)
- [Release notes](https://github.com/AgriciDaniel/claude-obsidian/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agricidaniel-claude-obsidian