Second Brain With Obsidian + Claude Code: The Complete Setup Guide

A second brain is a place outside your head where you capture what you know, so you can find it and use it later instead of losing it in a scroll of old notes. Obsidian is the storage layer — plain markdown files that live on your own computer, outside anyone else’s app. Claude Code is the agent layer — a terminal tool from Anthropic that opens that same folder, reads your actual notes, and writes back into it. Neither one does much alone. Obsidian without an agent is a filing cabinet. Claude Code without a vault is a smart assistant with nothing to work from. Together: you capture in Obsidian, Claude Code reads it, and it hands back summaries, drafts, and connections you’d have missed on your own. Setup is five steps: install Claude Code, open a terminal in your vault, write a CLAUDE.md, run a few starter commands, and back the whole thing up with git before you let it write anything.

I’m a former Senior Mentor in the Building a Second Brain course — I’ve watched hundreds of people build these systems, and the honest pattern is that most vaults die of a capture-organize loop with no output on the other end. This guide is about closing that loop. It isn’t another folder scheme.

What You Need

Nothing exotic. If you already keep notes, you’re most of the way there.

• Obsidian — free, runs locally, stores everything as plain .md files. If you’ve never used it, the Obsidian guide walks first note to working system.
• Claude Code — the terminal app from Anthropic. Requires a Claude Pro or Max plan; there’s no free tier for it.
• A vault folder — a folder on your computer with your notes in it. It can be empty. It can be five years of half-finished thinking. Both work.
• No coding. You type plain English at a prompt. The terminal is the only unfamiliar part, and it’s one command to open.

You don’t need a plugin, a database, or a subscription stack. The folder and the two apps are the whole system.

Why this works better than Notion, Evernote, or a wiki tool with an AI feature bolted on: Claude Code needs a real folder it can open on your filesystem. Notion and most cloud note apps store your notes behind an API and a database. An agent can only get at them through whatever access that API allows, on their schedule, in their format. Obsidian notes are just .md text files sitting in a folder you own. Claude Code opens that folder the same way it would open a code project, which is the entire reason this combination works as directly as it does. A Notion-plus-AI setup ends up needing an extra integration layer that a plain folder never requires.

The Setup

Step-by-Step: Connect Claude Code to Your Obsidian Vault

1. 01
   Install Claude Code. It needs Node.js first. Then npm install -g @anthropic-ai/claude-code from any terminal. The full install walkthrough, including troubleshooting, is in the Claude Code guide.
2. 02
   Open a terminal inside your vault folder. This is the part people skip and then wonder why nothing works. Claude Code only sees the folder it's opened in — `cd` into your Obsidian vault, then type `claude`. Now every command you run has your actual notes in reach.
3. 03
   Write a CLAUDE.md. This is a plain markdown file at the root of your vault. Claude reads it automatically at the start of every session — no re-explaining who you are, what you're building, or how you write. Run `/init` and Claude Code will draft a starting one from what it finds in your folder; you edit it from there.
4. 04
   Run your first commands. Start with read-only asks — summarize a folder, find every note that mentions a topic, list what's undated. Nothing gets written yet. You're checking that it actually understands your vault before you hand it a pen.
5. 05
   Set permissions, then back up with git. Claude Code asks before it edits or deletes a file by default — leave that on until you trust it. Run `/permissions` to see and restrict what it can touch. Then `git init` in the vault folder and commit before your first real write session. If an edit ever goes wrong, you want a version to go back to, not a memory of what the note used to say.

Read every note in my +Inbox/ folder and give me three things for each one: (1) the single most interesting idea in it, in one sentence, (2) which existing folder it probably belongs in and why, (3) whether it's ready to develop further or still too raw. Don't move or edit anything — just report back.

The vault is the memory. Claude Code is the hands. CLAUDE.md is what tells the hands what the memory is for.

What This Costs

Claude Code needs a paid Claude plan — there’s no free tier for it. Pro is $20/month and it’s enough for everything in this guide: reading a vault, drafting from notes, running a weekly review. The Max plans ($100 and up) add a stronger model and higher usage limits, worth it once you’re running Claude Code most days rather than a few times a week. Obsidian itself stays free for personal use. So the real cost of this whole setup is $20/month, and you can cancel it the same day you decide it’s not for you — nothing about your vault depends on the subscription staying active.

How I Run Mine

The Vault Layout Behind This System

You don’t need a fancy folder structure on day one. Start with an Inbox and four folders — Projects, Areas, Resources, Archive, the classic PARA split from Tiago Forte — and let Claude Code work inside that. It’s covered in full in the PKM guide and the second brain guide.

Here’s what mine actually looks like, for scale, once a vault has been running for years and has more than notes in it. I layer four things on top of PARA. Atlas/ holds the maps: the rules, the plans, the “how does this all fit together” documents, so a fresh Claude Code session can read one file and understand the whole system instead of guessing from scattered notes. Calendar/ holds anything time-based, daily notes and weekly reviews and meeting logs. X/ holds the system itself, scripts and workspace configs and the mechanics that keep the vault running. And the four PARA folders (01-Projects, 02-Areas, 03-Resources, 04-Archive) hold the actual content, numbered so they sort in the order I use them, active work first.

The reason this matters for Claude Code specifically: an agent that opens a folder cold has to figure out what’s current and what’s dead weight. A vault with a clear map — one file that says “read this first, here’s where everything lives” — turns a five-minute orientation into a five-second one. I keep that map at the root as a single markdown file. Every session starts there.

None of this is a rule you have to copy. It’s ACE stacked on PARA: Atlas for the maps, Calendar for the time-based notes, Efforts (the PARA “Projects” folder, renamed) for whatever has a deadline. The naming is mine — yours can be anything, as long as a fresh Claude Code session can read one file and know where to look instead of guessing.

Don’t build this on day one. Build it when your vault outgrows four folders and you notice yourself asking Claude Code the same “where does this go” question every week. That friction is the signal. No calendar date required.

In Practice

5 Real Workflows

These are the ones I run.

Capture → Daily Note

A voice memo, a screenshot, a half-formed thought — it lands in an Inbox folder as raw text, no processing. At the start of the day I ask Claude Code to fold anything new into that day’s note: add today's captures to my daily note, one line each, no editing. No decisions get made at capture time. You’re preserving. Organizing comes later.

The Weekly Review Agent

Once a week: read everything I touched this week across Projects and the daily notes, tell me what moved, what stalled, and what I should look at Monday. This is the one prompt in the whole system that pays off the most, because it’s the one thing most people know they should do and never do. Claude Code doesn’t get tired of it.

Notes Into a Draft, in Your Voice

Pick three or four notes on the same topic and ask Claude Code to find the argument buried across them, then draft a post or a script from it. If you’ve given it writing samples in your CLAUDE.md, the draft already sounds like you instead of like generic AI copy — that’s the difference a briefing file makes. The full prompt library for this is in the agentic PKM guide.

Research Folder Distill

Dump ten articles or PDFs into a Research/ folder and ask: read everything in this folder and give me the three claims that contradict each other, then the one question I still can't answer. This is where an agent earns its keep — reading fast across volume is exactly what it’s good at, and exactly what makes humans stop reading halfway through.

”What Did I Decide About X?”

Months later, you don’t remember which note has the answer. You don’t have to. Ask: search my vault for anything about the pricing decision and tell me what I decided and when. Claude Code greps and reads faster than you can scroll, and it doesn’t care that the note is buried three folders deep in something you archived in March.

What Goes Wrong

Mistakes That Slow This Down

Letting it write everywhere from day one. Turn on full edit access before you’ve watched it read your vault correctly, and the first mistake happens in a note you cared about. Read-only first. Writes once you trust it.

No git. A vault with no version history means an edit you don’t like is just gone. There’s no undo. git init takes ten seconds and it’s the difference between “that’s annoying” and “that’s a real loss.”

A giant CLAUDE.md. People try to cram their whole life story into the briefing file. Claude Code re-reads it every session — keep it to what actually changes an output: your voice, your audience, your current focus, what to avoid. Keep it to a page.

Treating it like a chatbot. Pasting a note into Claude Code and asking it to “make this better” ignores the entire point. It has your whole vault open. Ask it to find the pattern across twenty notes instead of polishing one.

Skipping the CLAUDE.md rewrite. The one Claude Code drafts for you from /init is a starting point. It won’t know your voice, your audience, or what you’re avoiding this quarter until you tell it. Ten minutes of editing changes every output that follows.

FAQ

How do I connect Claude Code to Obsidian?

Open a terminal, cd into your Obsidian vault folder, and run claude. That’s the connection: Claude Code works on whatever folder it’s opened in, and an Obsidian vault is just a folder of markdown files. No plugin required for the basic version. For deeper integration (reading tags, backlinks, and Obsidian’s own search) there’s an MCP plugin covered in the Obsidian CLI guide, but most of the workflows in this guide don’t need it.

Do I need to code?

No. You type requests in plain English — “summarize this folder,” “find every note about X,” “draft a post from these three notes” — and Claude Code does the reading and writing. The only new skill is opening a terminal and typing a folder name, which takes about a minute to get comfortable with.

Claude Desktop vs. Claude Code with Obsidian — which one?

Claude Desktop is a chat app. You can connect it to your vault through an MCP server and it will read files when asked, but each request is closer to a conversation than a hands-on session. Claude Code is a terminal agent built to open a working directory and act on it directly — read files, edit them, run multi-step tasks — with a permission prompt before anything changes. For vault-wide work (weekly reviews, drafting from a folder of notes, bulk reads) Claude Code is the better fit. For a quick question about one note, either works.

Is my vault private?

Your files stay on your computer. Claude Code reads and writes locally in the folder you open it in; nothing leaves your machine unless you explicitly connect an outside service through MCP. The prompts and file contents you send to Claude go to Anthropic to generate a response, same as any AI tool — if you’re working with something genuinely sensitive, keep it out of the folder you point Claude Code at, or restrict access with /permissions.

What is a second brain?

A second brain is an external system — usually notes on a computer — where you capture, organize, and later retrieve what you know, instead of relying on memory. The point isn’t storage for its own sake. It’s being able to find and use what you already thought, wrote, or learned, months or years after you first captured it. The second brain guide covers the full method.

Can Claude Code replace Obsidian plugins?

Some of them. Anything a plugin does by transforming or summarizing text — tag cleanup, note linking, a custom dashboard, format conversion — Claude Code can do on request, without installing anything. What it doesn’t replace: Obsidian’s graph view, its rendering (Excalidraw, Canvas, live preview), or anything that needs to run inside the app itself. Think of Claude Code as covering the plugins that process your notes. The ones that display them still need Obsidian.