claude-obsidian
claude-obsidian
Your AI second brain for Obsidian, built for Claude Code.
Drop in sources. Get a connected wiki that grows every time you use it.
Install · See the vault · Skills · Agents · Safety · Modes · FAQ
claude-obsidian turns the things you read into a knowledge base that keeps getting more useful. Drop a paper, an article, a transcript or your own notes into the vault, and Claude reads them, writes linked notes with sources, and files everything into one connected knowledge graph you can explore in Obsidian.
- Capture. Put sources in
inbox/. The originals are kept, untouched, so every summary can point back to where it came from. - Connect. Claude writes linked pages, indexes and maps of content, so new ideas join the graph instead of piling up.
- Ask. Get answers from what your vault already knows, with citations, without changing a single file.
- Save. Keep the answers worth keeping as notes, one at a time, when you ask.
- Check. A health check finds dead links, orphan pages and gaps before they spread.
Everything stays as plain Markdown files on your computer. No cloud database, no lock-in, no telemetry. Apart from the AI tool you chat with, nothing leaves your machine unless you say so.
The result is a normal Obsidian vault that stays useful with or without an AI: browse it in Graph view, or lay it out as a map in Obsidian Canvas.
Linked notes in Graph view · A knowledge map in Obsidian Canvas
Install
You need Claude Code, Python 3.11 or newer and, for the visual side, Obsidian. Install the plugin with two commands:
claude plugin marketplace add AgriciDaniel/claude-obsidian
claude plugin install claude-obsidian@agricidaniel-claude-obsidian
Then open the folder you want as your vault and start Claude Code there:
claude # start Claude Code in your vault folder
/claude-obsidian:wiki # set up the vault (shows you a preview first)
/claude-obsidian:wiki-ingest # turn what is in inbox/ into linked notes
/claude-obsidian:wiki-query # ask a question, answered from your notes
/claude-obsidian:save # keep a good answer as a note
/claude-obsidian:wiki-lint # health check: dead links, orphans, gaps
Open the same folder in Obsidian with Open folder as vault to browse your notes as they grow.
Already have an Obsidian vault? /claude-obsidian:wiki can adopt it without moving your notes. The installation guide walks through it.
Other AI tools: Codex, OpenCode, Gemini, ZCode, Cursor and Windsurf
claude-obsidian is a set of Agent Skills, so it also runs in other hosts. From a copy of this repo, preview the setup, then apply it:
git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian
bash scripts/setup-multi-agent.sh --host codex # preview, writes nothing
bash scripts/setup-multi-agent.sh --host codex --apply # link the skills
Use --host opencode, --host gemini or --host zcode the same way. Cursor and Windsurf need a workspace: --host cursor --host windsurf --workspace <folder> --apply. Every host is covered in the installation guide.
Windows
On Windows, use WSL for anything that writes to the vault. Native Windows can inspect and preview, and stops with a clear error instead of writing. The Windows and WSL guide has the details.
Upgrading from 2.x or 3.0.0
claude plugin marketplace update agricidaniel-claude-obsidian
claude plugin update claude-obsidian@agricidaniel-claude-obsidian
Version 3.0.0 alone used the plugin name agricidaniel-obsidian. If you installed that one, run the marketplace update, then claude plugin install claude-obsidian@agricidaniel-claude-obsidian, and restart Claude Code. See the namespace migration.
15 skills, one system
Talk to it in plain words, or call any skill by name with /claude-obsidian:<skill>. Open a group to see what is inside.
Build and use the wiki (5)
| Skill | What it does |
|---|---|
wiki |
Sets up a new vault or adopts yours, checks it is ready and routes your request |
wiki-ingest |
Turns captured sources into linked pages with their sources recorded |
wiki-query |
Answers from what is already in the vault, read-only |
save |
Keeps one answer or insight as a note, only when you ask |
wiki-lint |
Finds dead links, orphan pages, missing metadata and empty sections |
Extend the workflow (7)
| Skill | What it does |
|---|---|
autoresearch |
Bounded web research, only with your consent, merged after review |
canvas |
Creates and updates Obsidian Canvas boards |
defuddle |
Plans a clean Markdown capture of a web page; the cleaner itself is an optional external tool |
wiki-fold |
Rolls up the operation log into short, traceable summaries |
wiki-mode |
Sets how new notes are filed: Generic, LYT, PARA or Zettelkasten |
wiki-retrieve |
Local BM25 search with optional reranking |
wiki-cli |
Reads and searches through the official Obsidian command line |
Reference (3)
| Skill | What it does |
|---|---|
obsidian-markdown |
Correct Obsidian Markdown: links, embeds, callouts and properties |
obsidian-bases |
Native .base tables, cards, filters and formulas |
think |
A structured review loop for hard decisions |
Meet the crew
Behind the skills, three agents do the heavy reading and checking. All three are read-only: they hand back drafts and reports, and only one place, the transaction core, ever writes to your vault.
| Agent | What it does |
|---|---|
wiki-ingest |
Reads one captured source and hands back page drafts, with the hash it expects each target to have |
wiki-lint |
Runs the vault linter, double checks surprising findings and returns a health report |
verifier |
Runs safe tests on a proposed change or release and ranks what it finds |
Built for:
- Researchers and students who read a lot and want every note to point back to its source.
- Writers and creators who want ideas from videos, articles and books to connect instead of getting lost in folders.
- Builders and teams who keep project knowledge in Markdown and want an AI that can search it, cite it and keep it tidy.
Nothing gets lost
Your notes matter, so every change to the vault works like a careful save:
- Read first. Claude reads every note it will touch and records a fingerprint (a SHA-256 hash) of each one.
- One plan, one apply. Helpers can work in parallel, but they only hand back drafts. Claude merges them into one plan, checks it, and applies it as a single transaction.
- Undo if anything breaks. A journal keeps backups during the write. If the power cuts out halfway,
transaction recoverrolls the unfinished change back from the journal. - Your edits win. If you change a note in Obsidian while Claude is planning, the fingerprint no longer matches and the write stops with a conflict instead of overwriting you.
Web research, Git checkpoints and anything that sends data off your machine are separate steps that ask you first.
For the curious: how the vault is chosen and protected
The plugin never treats its own folder or cache as your vault. A vault is picked explicitly: through CLAUDE_OBSIDIAN_VAULT, the nearest .claude-obsidian.json, or one clear initialized parent folder. If it is not sure, it exits without writing.
The lock coordinates local writers that cooperate with it. Other devices and external editors do not share it, so keep backups, especially when you sync Canvas or Base files. Read the transaction contract, the provenance contract and the Compound Vault guide for the full detail.
Shape the vault to the way you think
wiki-mode sets how new notes are filed, the way you already like to work. Switching modes changes where new notes go and never moves your old ones.
| Mode | How notes are filed |
|---|---|
| Generic (default) | Sources, concepts, entities and sessions |
| LYT | Maps of Content and linked atomic notes |
| PARA | Projects, Areas, Resources and Archives |
| Zettelkasten | Stable IDs, atomic notes and dense links |
More in the methodology modes guide.
How it works
- Capture. Sources go into
inbox/. claude-obsidian keeps an untouched copy of each one, named by its content, before anything is summarized. - Ground. Each important claim in a note is linked to the source that supports it. Weak or conflicting evidence stays visible instead of being smoothed over.
- Compound. Ask, research, search and lint use what the vault already knows, so every session starts from your notes instead of from zero.
The idea follows Andrej Karpathy's LLM Wiki pattern: let the AI maintain a wiki you can read, instead of a black box you cannot.
What it can and cannot read today
| Input or feature | Support today |
|---|---|
| Local files | Captured and kept as content-addressed copies |
| Images | Metadata, hash, size and dimensions when available |
| PDF and EPUB | Metadata, hash and size; no built-in text extraction yet |
| Web pages and YouTube | Prepared as a plan you approve; fetching needs a separate runner that enforces it |
| OCR | Needs an external tool you configure |
| Search (BM25) | Local and deterministic |
| Reranking or remote models | Optional, and only with your explicit consent |
| Obsidian CLI | Optional for reading and search |
Command line reference
From a clone of this repo, the same core is available as a portable command line: python3 scripts/claude-obsidian.py. Commands that change files show a plan first and only apply with the plan's hash.
| Command | What it does |
|---|---|
doctor --vault PATH |
Shows which vault is selected and whether it is ready |
init PATH |
Plans, then creates, a new vault |
adopt PATH |
Plans, then adopts, an existing Obsidian vault |
lint --vault PATH |
Runs the health check |
capture plan / capture apply |
Checks, then keeps, copies of local sources |
transaction recover --vault PATH |
Restores the vault after an interrupted write |
bench --queries FILE --vault PATH |
Measures search quality on your own questions |
Run python3 scripts/claude-obsidian.py --help, or add --help to any command, to see every option.
FAQ
What is claude-obsidian?
A free, open-source AI second brain for Obsidian: a personal knowledge management (PKM) and AI note-taking system that builds a knowledge graph of plain Markdown. It is a Claude Code plugin (and a set of Agent Skills for other AI tools) that turns your sources into linked, cited notes, answers questions from them, and keeps the vault healthy over time.
Is it free?
Yes. It is MIT licensed with no subscription and no tracking. You use it with your own Claude Code plan, or with another AI tool you already have.
Do I need Obsidian?
No, but it is the nicest way to see the result. The vault is plain Markdown, so any editor works. Obsidian adds Graph view, Canvas maps and Bases tables on top.
Is this an Obsidian community plugin?
No. You don't install it from Obsidian's community plugin list. It is a Claude Code plugin (and a set of Agent Skills for other AI tools) that works on your vault folder. Obsidian opens the result as a normal vault, and no Obsidian plugin is required.
Does my data leave my computer?
Your vault stays on your computer as ordinary files. When you work with it in Claude Code, the notes Claude reads are sent to Claude, Anthropic's model, the same as anything else you open in Claude Code. Web research and remote models are off until you allow them for a task.
Will it mess up my existing notes?
It is built not to. Adopting a vault does not move your notes, every change is shown as a plan before it is applied, and an interrupted write can be rolled back. If you edit a note while Claude is working on it, the write stops instead of overwriting you. Keep normal backups anyway.
How is it different from a chat that saves notes?
Most AI note tools save text and stop. claude-obsidian keeps the original sources, links every claim back to them, connects new notes to old ones, and checks the vault for broken links and gaps. The knowledge compounds instead of piling up.
Does it work with Codex, Gemini or Cursor?
Yes. The skills follow the open Agent Skills format. Claude Code gets the full plugin; Codex, OpenCode, Gemini, ZCode, Cursor and Windsurf link the same skills with one setup script. See Install.
Good to know: requirements, limits and uninstall
Requirements. Python 3.11 or newer, a current Claude Code release for the plugin (or another Agent Skills host), Obsidian for the visual side, and Bash for the setup scripts. Git is only needed for development or checkpoints.
Limits. It is not an automatic transcript recorder, a cloud sync service or a fact checker, and it does not replace backups. PDFs and web pages need extra tools for full text.
Uninstall. Removing the plugin never removes your vault. Your notes, sources and Obsidian settings stay yours: claude plugin uninstall claude-obsidian@agricidaniel-claude-obsidian.
License and contributing
MIT License, see LICENSE. The design follows Andrej Karpathy's LLM Wiki pattern and uses kepano/obsidian-skills as the reference for Obsidian Markdown, Bases and Canvas syntax. See ATTRIBUTION.md and CITATION.cff.
Contributions are welcome: read CONTRIBUTING.md first and run make test before you open a pull request. Report security problems as described in SECURITY.md, and read PRIVACY.md for what stays on your machine. Release notes live in the changelog, and the code of conduct applies everywhere. AI coding agents working on this repo start at AGENTS.md.
Thank you to everyone who has helped. Pull requests: @Ychris12138, @Marcos64s, @hphsu, @vinsocci, @miraclemanza, @maartengoet, @Lion-1209, @HectorBernstorff, @Packetslave, @CooperSheroy, @yotamleo, @ketpatil77, @tilusnet, @GPezzuti, @STiFLeR7. Issue reports: @RoelKluin, @threnard, @szrenwei, @ppuri2, @cosmos75, @simonc.
Star history
If claude-obsidian helps you, a star helps other people find it.
Author
Built by Agrici Daniel, AI Workflow Architect, with help from the AI Marketing Hub Pro community.
