Most AI note tools stop at "save a summary." AgriciDaniel/claude-obsidian — roughly 13k GitHub stars, 1.4k forks, MIT license, release v2.1.1 — is built for a compounding loop: capture sources, ground claims, connect knowledge, query the vault again. It implements the Karpathy LLM Wiki pattern as a local-first Obsidian vault wired to Claude Code Agent Skills, not as another cloud Notion alternative that owns your files.
Drop material in inbox/, run /claude-obsidian:wiki-ingest, and Claude reads, links, and files pages into a connected Markdown knowledge graph you can open in Obsidian Graph view or query read-only with /claude-obsidian:wiki-query.
TL;DR — what builders ask first
| Question | Direct answer |
|---|---|
| Repo? | github.com/AgriciDaniel/claude-obsidian |
| Stars / license? | ~13k stars · MIT · Agent Skills compatible |
| Pattern? | Karpathy LLM Wiki + kepano obsidian-skills substrate |
| Vault vs product checkout? | Clone is the product; your vault is a separate directory |
| First commands? | init vault → claude --plugin-dir … → /claude-obsidian:wiki |
| vs RAG chat? | Pre-compiled linked wiki + provenance ledgers, not chunk retrieval every ask |
| Honest gaps? | No PDF semantic extraction; URL/YouTube need external runner; Windows writes need WSL |
Why it feels different from chat-with-PDF
The README states the design plainly: your vault remains ordinary files. Network egress is explicit. Parallel agents return drafts; one orchestrator applies one recoverable transaction. High-risk claims need two independent sources; contradictions stay visible.
That aligns with explainx.ai's read on local-first agent memory: the durable artifact is Markdown on disk, not a hidden vector index. Compared to OpenKnowledge's WYSIWYG editor, claude-obsidian leans Obsidian-native — Graph, Canvas, Bases, callouts — and Claude Code-first for mutations.
Quick start: clone product, initialize vault
Every mutating command previews before apply. Pin --generated-at and --operation-id, review the JSON plan hash, then pass --approved-plan-sha256 with --apply.
1. Get the product (not your vault)
git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian
The checkout contains skills, hooks, and scripts/claude-obsidian.py. It is not where your notes live.
2. Initialize a separate vault
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"
Review the emitted JSON plan, copy approved_plan_sha256, then apply:
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
For an existing Obsidian vault, use the non-destructive adopt workflow in the installation guide.
3. Open vault in Obsidian, run Claude Code from it
cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian
Inside Claude Code:
/claude-obsidian:wiki
Place a source in inbox/, then:
/claude-obsidian:wiki-ingest
Save a scoped insight (never an automatic transcript):
/claude-obsidian:save
Ask the vault read-only:
/claude-obsidian:wiki-query
Multi-agent hosts (Codex, OpenCode, Gemini)
bash bin/setup-multi-agent.sh --host codex
bash bin/setup-multi-agent.sh --host codex --apply
Cursor and Windsurf pick up workspace-local skill discovery from .cursor/rules and .windsurf/rules in the product checkout.
The compounding knowledge loop
| Phase | Skill / action | What happens |
|---|---|---|
| Capture | inbox/ + capture apply | Content-addressed immutable copies in .raw/ |
| Ground | wiki-ingest | Source and claim ledgers track authority, freshness, contradictions |
| Connect | wiki-ingest, canvas | Linked pages, MOCs, Obsidian Canvas maps |
| Reuse | wiki-query, wiki-retrieve | BM25 (+ optional rerank) over vault evidence |
| Maintain | wiki-lint | Dead links, orphans, stale indexes, empty sections |
Fifteen skills, one provenance model
Build and use the wiki
| Skill | What it does |
|---|---|
wiki | Initialize or adopt vault, diagnose readiness, route work |
save | Save one scoped answer — not a full session transcript |
wiki-ingest | Turn captured sources into linked pages + provenance |
wiki-query | Read-only answers from vault evidence |
wiki-lint | Dead links, orphans, metadata gaps, stale indexes |
Extend the workflow
| Skill | What it adds |
|---|---|
autoresearch | Bounded web research with explicit egress consent |
canvas | Obsidian Canvas creation and maintenance |
defuddle | Clean web HTML before ingestion |
wiki-fold | Extractive rollups of the operation log |
wiki-mode | Generic, LYT, PARA, or Zettelkasten filing |
wiki-retrieve | Contextual prefixes, BM25, optional cosine rerank |
wiki-cli | Obsidian CLI reads/search; filesystem transport fallback |
Reference skills
| Skill | Role |
|---|---|
obsidian-markdown | Obsidian Flavored Markdown, callouts, embeds |
obsidian-bases | Native .base tables and formulas |
think | Structured observe → connect → create review loop |
Trigger phrases and contracts live in each skills/<name>/SKILL.md. For slash-command ergonomics across hosts, see Claude Code commands reference.
Shape the vault: PARA, Zettelkasten, LYT
wiki-mode routes new notes without bulk-moving legacy data:
| Mode | Filing principle |
|---|---|
| Generic | Sources, concepts, entities, sessions |
| LYT | Maps of Content + atomic linked notes |
| PARA | Projects, Areas, Resources, Archives |
| Zettelkasten | Stable IDs, atomic notes, dense links |
Switching modes changes routing for new work only — not silent reorganization of old notes.
Operator CLI reference
Wrapper: python3 scripts/claude-obsidian.py
| Command | Effect |
|---|---|
doctor --vault PATH | Vault selection and readiness |
init / adopt | Plan or create / adopt vault |
migrate --vault PATH | Add v1 ledgers without rewriting legacy raw data |
transaction inspect/apply/recover | Inspect bundles, apply once, recover interrupted ops |
lint --vault PATH | Deterministic findings for a UTC date |
capture plan/apply | Preflight and immutable capture |
checkpoint OPERATION_ID | Explicit git checkpoint after an operation |
High-level mutators emit approved_plan_sha256. Drift between plan and filesystem fails before any vault write.
Honest capability boundaries
| Input / capability | Current support |
|---|---|
| Local filesystem | Implemented bounded byte capture |
| Images | Metadata, hash, bounded dimensions |
| PDF / EPUB | Metadata and hash only — no semantic extraction |
| URL / YouTube | Consent plan + external runner required |
| OCR | Local consent plan + external runner |
| BM25 | Local, deterministic |
| Embeddings / remote models | Optional, egress-gated |
| Obsidian CLI | Optional reads; filesystem always available |
This is not a factual oracle, cloud sync service, or substitute for backups and source control. Treat it like loop-engineering a PKM pipeline: explicit phases, inspectable artifacts, recoverable failures.
Comparison anchors on explainx.ai
| Alternative | When claude-obsidian wins | When something else wins |
|---|---|---|
| Karpathy gist only | You want Obsidian UX + 15 packaged skills + transaction CLI | You need a 50-line starter with zero dependencies |
| Obsidian vault as agent memory | You want provenance ledgers and ingest/query/lint as first-class ops | You only need search + hooks in an existing vault |
| OpenKnowledge editor | Obsidian power user, CLI transaction model | WYSIWYG editor + no-code GitHub sync for teams |
| files.md local notes | Multi-source research wiki with claim ledgers | Single-folder private notes without agent orchestration |
What people are asking (issues and maturity)
- 66 open issues / 70 open PRs (August 2026) — active but not finished product polish; read issue titles before betting a team wiki on edge cases.
- Windows writes — plan on WSL for apply paths; native Windows is inspection-only.
- PDF research — ingest stores hash/metadata; you still need your own extraction pipeline for dense PDF corpora.
- Web sources —
autoresearchand URL capture require explicit egress consent; not "paste any URL silently." - Plugin vs vault upgrades — upgrade product checkout independently; run
migrateon older vaults before new ledger features.
Requirements
- Python 3.11+ for portable core
- Obsidian (recommended) for Graph/Canvas
- Bash for setup scripts and shell tests
- Git optional — for explicit checkpoints only
- Optional: Obsidian CLI, Ollama, defuddle (capability-detected)
Run health check:
python3 scripts/claude-obsidian.py doctor --vault "$HOME/Documents/MyKnowledgeVault"
The bottom line
claude-obsidian is the most complete open-source packaging of Obsidian + Claude Code + Karpathy LLM Wiki available in August 2026: fifteen coordinated skills, transaction-safe vault writes, and honest provenance instead of chat-summary amnesia.
Clone github.com/AgriciDaniel/claude-obsidian, initialize a separate vault, invest one real source through wiki-ingest, then query with wiki-query before you bulk-import a library. Pair it with agent skills literacy if you plan to customize wiki-mode or add hooks.
Start with a source whose claims you can check
For the first ingest, use a short public document you understand. Identify two claims you expect the resulting note to preserve and one qualification it must not drop. After ingestion, open the note and follow its provenance back to the source. A connected graph is useful only if its links and summaries remain meaningful.
Then query a fact that the source contains and a fact it does not contain. The unsupported question should expose the evidence gap rather than encourage a plausible completion. Keep these examples as a small regression set when you change prompts, skills, or the product revision.
The upstream project describes the supported workflow and its current boundaries. Test the installed revision before bulk-importing a personal archive; a historical feature table is not a guarantee that every extraction path behaves the same way today.
Preserve contradictions instead of merging them away
Suppose two sources give different dates for an event. The useful note identifies each date and source, then states what remains unresolved. Choosing the more fluent summary can erase the distinction and make later answers sound more certain than the underlying evidence.
When a source is updated, distinguish a changed claim from a newly captured copy. Keep the earlier evidence identifiable so a reader can understand why an older note reached a different conclusion. This is especially useful for technical documentation and evolving product policies.
Rehearse recovery on a disposable vault
Make a small backup, apply an ordinary note update, and inspect the changed files before trusting the workflow with important material. Review an interrupted-operation recovery path using the project's documented tooling. Keep product updates separate from vault mutations so you can identify which step introduced a problem.
Ownership of plain Markdown gives you portability and inspectability. It does not remove the need for backups, source checking, and a clear policy for which documents the agent is allowed to read or send to external services.
Related on explainx.ai
- Karpathy LLM Wiki Pattern — Complete Guide · lineage and ingest/query/lint ops
- What Is an Obsidian Vault for AI Agent Memory? · graph-native agent memory
- OpenKnowledge — Local LLM Wiki Editor · WYSIWYG alternative
- What Are Agent Skills? · SKILL.md contract claude-obsidian extends
- Claude Code Commands Reference · slash commands and plugins
- Loop Engineering with Claude Code · phased agent workflows
- files.md — Private Local-First Notes · lighter-weight PKM
- Google Open Knowledge Format (OKF) · interoperable bundle spec
Source: AgriciDaniel/claude-obsidian on GitHub (MIT; README and docs as of August 26, 2026).
Star counts, skill names, and platform matrix reflect the public repository at publication time. Run doctor and read docs/installation.md before production vault adoption.