claude-obsidian: A Local-First, Source-Cited Knowledge Graph for Claude Code
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.
At a glance
- What is it?
- claude-obsidian turns Obsidian vaults into a provenance-aware knowledge graph using Claude Code and Agent Skills. It keeps files as plain Markdown, grounds claims in immutable source copies, and lets you query the vault without sending data anywhere by default.
- Who is it for?
- Adopt claude-obsidian if you already live in Obsidian, want AI-assisted note-taking without losing file ownership, and can tolerate a setup that requires reading JSON plans and approving SHA-256 hashes. Skip it if you need a zero-config plug-and-play tool, if you expect automatic transcript recording (it explicitly is not that), or if you cannot run Python scripts and Claude Code.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Problem It Solves and Who It Is For
Most AI note-taking tools save text and stop. claude-obsidian attacks that gap by making the knowledge base more useful on every use. It is aimed at people who use Obsidian for personal knowledge management and want Claude Code (or compatible Agent Skills hosts) to read, link, and file sources into a connected graph of plain Markdown. The target user is someone who is tired of losing the source behind a summary, who wants to query their own notes instead of starting from zero, and who refuses to hand their files to a cloud database. The README is explicit: this is not an automatic transcript recorder, not a cloud sync service, and not a factual oracle. It is for users who care about provenance and local ownership, and who are willing to run a few commands and review JSON plans.
The Core Loop: Capture, Ground, Connect, Reuse
The system is built around a repeatable loop, not a single save button. First, capture with context: local sources go through a visible inbox, and immutable, content-addressed copies are preserved before any synthesis. Second, ground every important claim: source and claim ledgers track authority, freshness, support, contradiction, confidence, and review state. Third, connect what you learn: the system builds linked pages, indexes, Maps of Content, methodology-aware structures, and Obsidian Canvas views. Fourth, reuse the vault: you can query, research, retrieve, lint, and fold what is already known. The key design choice is that the vault stays a normal directory of Markdown, JSON, and source files. Nothing is hidden in a plugin cache or silently uploaded to a model. Network egress is a separate, explicit decision, which is rare among AI tools.
How It Works: Provenance and Transaction-Safe Writes
The architecture has two layers that keep the vault honest. First, provenance is baked into every step. Sources survive the summary because notes point back to durable source evidence. Unsupported and contradictory claims remain visible, not swept under the rug. Second, writes are transaction-safe. The README states that parallel agents cannot race the vault: workers return drafts, and one orchestrator inspects and applies a single recoverable transaction. This is a deliberate answer to the common failure mode where multiple AI agents write to the same vault and corrupt it. Every mutating setup command previews its exact operation before it can apply. You get a JSON plan with an `approved_plan_sha256`, and you must copy that hash and pass it with `--apply` to execute. That is a real safety mechanism, but it also means every setup step is a two-phase commit. It is a trade-off: safety over speed.
Getting It Running: Commands and Config Keys
The quick start is concrete and copy-paste friendly. Clone the repository, then initialize a separate vault. You need two environment variables: `GENERATED_AT` set to the current UTC timestamp and `OPERATION_ID` set to a string like `init-reviewed`. The init command is `python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"`. This prints a JSON plan. You review it, copy the `approved_plan_sha256`, and rerun the same command with `--approved-plan-sha256 "<sha256-from-the-plan>" --apply`. For an existing vault, you use a non-destructive `adopt` workflow instead of `init`. Then you open the vault in Obsidian and run Claude Code from that directory with `claude --plugin-dir /absolute/path/to/claude-obsidian`. Start with `/claude-obsidian:wiki`, place a source in `inbox/`, and invoke `/claude-obsidian:wiki-ingest`. Save answers with `/claude-obsidian:save` and query with `/claude-obsidian:wiki-query`. For other hosts like Codex, OpenCode, or Gemini, you run `bash bin/setup-multi-agent.sh --host codex` and then with `--apply`.
The 15 Skills: One System, Not a Grab Bag
The skills are small enough to invoke directly but share the same evidence, vault-selection, and mutation rules. That is the unifying idea. `wiki` initializes or adopts a vault and diagnoses readiness. `save` saves one scoped answer, never an automatic transcript. `wiki-ingest` turns captured sources into linked pages and provenance records. `wiki-query` answers read-only from relevant vault evidence. `wiki-lint` reports dead links, orphans, metadata gaps, stale indexes, and empty sections. There are also extension skills: `autoresearch` does bounded web research with explicit egress, `canvas` maintains Obsidian Canvas views, `defuddle` cleans web content, `wiki-fold` creates extractive rollups of the operation log, `wiki-mode` supports Generic, LYT, PARA, or Zettelkasten filing conventions, and `wiki-retrieve` uses contextual prefixes, BM25, and optional cosine reranking. Reference skills cover correct Obsidian Flavored Markdown and native `.base` tables. The naming is consistent, and the README makes clear that capabilities are stated honestly: optional tools are detected, maturity is declared, and missing adapters degrade clearly instead of being simulated.
Limitations and Failure Modes
The most obvious limitation is the setup friction. The two-phase approval for every mutating command is safe but tedious. If you lose the `approved_plan_sha256` or the plan changes between runs, you have to redo the review. Second, the system depends on a supported host. Claude Code is the primary target; other hosts like Codex, OpenCode, and Gemini are supported via a setup script, but the README does not promise equal maturity. Third, it is not an automatic recorder. If you expect every chat to be saved, this will disappoint you. Fourth, it is not a factual oracle. The system can preserve contradictions, but it cannot resolve them for you. Fifth, the README explicitly says it is not a substitute for backups and source control. If your vault is not under git, a bad transaction could be costly, even with the safety mechanisms. Finally, the `wiki-lint` skill exists because the vault can accumulate dead links and stale indexes; that is a maintenance burden you must accept.
Alternatives and How They Differ
The README frames claude-obsidian as an open-source Notion alternative, but the more precise comparison is with other AI note-taking tools that store in proprietary formats or cloud databases. Notion AI, for example, keeps your data in a cloud database, locks you into its editor, and does not give you a plain Markdown vault you can migrate. claude-obsidian is the opposite: local-first, file-based, and source-cited. Another alternative is a plain Obsidian plugin like Smart Connections, which uses embeddings to link notes but does not preserve immutable source copies or claim ledgers. Smart Connections is easier to install but does not offer a provenance model or transaction-safe writes. The real difference is the evidence layer. claude-obsidian is not just about linking; it is about grounding every claim in a source that survives the summary. If you do not need that evidence trail, a simpler plugin will save you setup pain.
Maintenance, Upgrades, and License
The project is MIT-licensed, which means you can use, modify, and redistribute it freely, with attribution. The repository has a CHANGELOG.md, and recent releases show active maintenance: v2.0.0 focused on reliability and evidence refoundation, v2.1.0 added native Windows compatibility, and v2.1.1 addressed legacy migration safety. The last push was in August 2026, so the project is alive. Upgrades are a real cost. The README mentions an installation guide that covers upgrades and uninstall steps, but it does not promise automatic migration. The v2.1.1 release name, 'Legacy Migration Safety', suggests that moving from older versions requires care. You should read the CHANGELOG before upgrading, and the two-phase approval applies to upgrades as well. The maintenance burden is not zero: you need to run `wiki-lint` regularly to keep the vault healthy, and you must keep your own backups. The license is permissive, but the project's own docs do not provide legal advice, so check the LICENSE file yourself if you plan to redistribute.
Editorial conclusion
Adopt claude-obsidian if you already live in Obsidian, want AI-assisted note-taking without losing file ownership, and can tolerate a setup that requires reading JSON plans and approving SHA-256 hashes. Skip it if you need a zero-config plug-and-play tool, if you expect automatic transcript recording (it explicitly is not that), or if you cannot run Python scripts and Claude Code. Before adopting an existing vault, run the non-destructive `adopt` workflow and review the plan; always back up your vault and keep it under source control, because the system does not replace backups. Verify that your host is supported (Claude Code, Codex, OpenCode, Gemini, Cursor, Windsurf) and that optional tools like BM25 or cosine reranking are detected, not simulated. The core judgement: this is a serious, evidence-first system for users who value provenance over convenience, but its safety mechanisms add friction that casual note-takers will find heavy.
Community notes