Obsidian + Claude Code: Building Your Second Brain

How to use Obsidian vaults and Claude Code together as a thinking partner, context engine, and idea generator.

Version 1.0.0 • Updated 03/01/2026, 12:00 PM EST

Part 0: Intro

Already using Claude or ChatGPT but feel like you're repeating yourself every session? This is for you.

What this tutorial will show you is:

✅ Understand what Obsidian is and why Markdown vaults matter for AI workflows
✅ Set up an Obsidian vault structured for use with Claude Code
✅ Create custom slash commands that load deep personal/project context into Claude Code
✅ Use Claude Code as a thinking partner, not just a code generator
✅ Surface patterns, ideas, and connections you can't see on your own

The Big Idea: Your AI is only as good as the context you feed it. Obsidian gives you a structured, interlinked knowledge base that Claude Code can read, traverse, and reason over. The result is responses that are deeply personalized and contextually rich, not generic.

What to expect: This is not a coding tutorial. This is about building a personal knowledge system that makes every AI interaction dramatically better. If you take notes, manage projects, or want better ideas on tap, this will change how you work with LLMs.

Tutorial Path

Part 1: Why Context Is the Bottleneck (10 min)
Part 2: What Is Obsidian? (10 min)
Part 3: What Is Claude Code? (5 min)
Part 4: The Obsidian CLI, the Bridge (10 min)
Part 5: Setting Up Your Vault (15 min)
Part 6: Writing Context Files (15 min)
Part 7: Building Custom Slash Commands (20 min)
Part 8: Thinking Tools, Beyond Code Generation (15 min)
Part 9: From Reflection to Action, Generating Ideas (10 min)
Part 10: Privacy, Boundaries, and Vault Hygiene (10 min)
Part 11: What to Do Next (5 min)

Requirements

A computer (Mac, Windows, or Linux)
Obsidian installed (free): https://obsidian.md
Claude Code installed (requires Anthropic API key or Claude subscription): https://docs.anthropic.com/en/docs/claude-code
Obsidian CLI plugin installed: https://help.obsidian.md/cli
Basic comfort with a terminal (you don't need to be a developer)

Part 1: Why Context Is the Bottleneck (10 min)

The Problem Everyone Hits

You start a new Claude or ChatGPT session. You describe your project. You explain your preferences. You give background. 20 minutes in, the AI finally has enough context to be useful.

Next day, new session. You do it all again.

This is the #1 friction point in working with LLMs. It's not model quality. It's not prompt engineering. It's context delivery.

The core issue:

LLMs have no persistent memory across sessions (or limited, uncontrollable memory)
You can't see or manage what the AI "remembers"
Every session starts cold
The better the context, the better the output, but re-explaining is exhausting

What you actually need:

A place to store structured context about your projects, preferences, and thinking
A way to pass that context into an AI agent instantly
Files you control, not a black-box memory system

That's what Obsidian + Claude Code solves.

The File Is the Memory

Here is the mental model:

Human memory is unreliable. Studies show we reconstruct memories, not replay them.
A Markdown file is a perfect snapshot. It captures exactly what you thought at that moment.
An AI agent that reads your files has a more accurate picture of your projects than your own recall.

When you write something down in a file and pass it to Claude Code, the agent doesn't need to guess. It doesn't need to ask 15 clarifying questions. It just reads and goes.

The equation:

Better files = Better context = Better AI output = Less wasted time
Click to copy

Part 2: What Is Obsidian? (10 min)

The Basics

Obsidian is a note-taking app that sits on top of a folder of Markdown files. That folder is called a vault.

Key facts:

Free and local-first. Your files live on your machine, not in someone's cloud.
Markdown-based. Every note is a .md file. No proprietary format.
Bidirectional linking. You can link notes to each other using [[double brackets]].
Graph view. Visualizes how your notes connect to each other.
Plugin ecosystem. Hundreds of community plugins, including the CLI we'll use.

What Makes It Different from a Folder

A regular folder on your computer stores files. Obsidian does that too, but adds one critical feature: interrelationships.

When you write [[Project Alpha]] inside a note, Obsidian creates a link to the "Project Alpha" note. Now those two notes are connected. Over time, a web of connections forms across your vault.

Why this matters for AI:

A folder gives Claude Code a list of files. An Obsidian vault (via the CLI) gives Claude Code files plus the relationship graph between them. Claude Code can see that your note on "distributed systems" links to "home lab setup" which links to "GPU inference" which links to "cost analysis." It can traverse these connections to build a richer understanding of how your ideas relate.

The Graph Visualization

Obsidian has a built-in graph view that shows every note as a node and every link as an edge. Over months of note-taking, you build a map of your thinking.

Some people maintain vaults for years. The graph becomes a literal map of their intellectual life: projects, people, ideas, hypotheses, all interconnected.

Part 3: What Is Claude Code? (5 min)

Claude Code is an agent you run from the command line. It can:

Read and write files on your computer
Execute terminal commands
Navigate your file system
Create, edit, and manage projects

The key difference from web-based Claude: it has access to your local file system. That means it can read your Obsidian vault directly.

Example interaction:

You: Read the file at ~/vault/projects/lab-setup.md and summarize my current hardware
Claude Code: [reads file] You have 3 nodes: TrueNAS SCALE for storage, Ubuntu for services, and a Windows GPU box running inference. Your primary constraint is VRAM...
Click to copy

No copy-pasting. No re-explaining. It just reads the file.

Slash Commands

Claude Code supports custom slash commands. These are shortcuts you define that trigger specific behaviors. For example:

/context could load all your project context files
/today could read your daily notes and calendar to plan your day
/ideas could scan your vault and generate ideas based on patterns

You define what each command does. Claude Code executes it.

Part 4: The Obsidian CLI, the Bridge (10 min)

What It Does

The Obsidian CLI is a plugin that lets Claude Code interact with your Obsidian vault programmatically. Without it, Claude Code can read your .md files (they're just text). With it, Claude Code can also:

See which files are linked to which (the backlink graph)
Identify orphan notes (files with no connections)
Read tags and metadata
Understand the structure of your vault, not just the content

Why the Graph Matters

Consider this scenario. You have 200 notes in your vault. Without the CLI, Claude Code sees 200 disconnected files. With the CLI, it sees:

"Lab Setup" links to "GPU Inference" links to "Cost Analysis"
"Project Alpha" links to "Team Roster" links to "Q3 Goals"
"Daily Note Feb 15" mentions "Lab Setup" and "Project Alpha"

Now Claude Code can answer questions like: "What are the common themes across everything I've been working on this month?" It can trace idea evolution. It can find contradictions in your thinking. It can surface patterns you haven't named yet.

Installation

Open Obsidian
Go to Settings > Community Plugins > Browse
Search for "Obsidian CLI"
Install and enable it
Follow the plugin's setup instructions to register the CLI command

Verify it works by running in your terminal:

obsidian-cli vault list
Click to copy

You should see your vault(s) listed.

Part 5: Setting Up Your Vault (15 min)

Vault Structure

There is no single "right" structure. But here is a practical starting point:

vault/
├── daily/              # Daily notes (one per day)
│   ├── 2026-03-01.md
│   └── ...
├── projects/           # One file per active project
│   ├── project-alpha.md
│   ├── home-lab.md
│   └── ...
├── context/            # Context files for AI consumption
│   ├── personal-workflow.md
│   ├── work-context.md
│   └── preferences.md
├── people/             # Notes on people you work with or learn from
│   ├── colleague-name.md
│   └── ...
├── ideas/              # Standalone idea notes
│   └── ...
└── commands/           # Claude Code slash command definitions
    └── ...
Click to copy

Key Principles

1. You write the files, not the AI.

This is critical. If Claude Code writes notes into your vault, you lose the guarantee that vault contents represent YOUR thinking. When the agent finds patterns later, you want those patterns to come from your notes, not from its own prior output.

Keep a strict separation: you write vault content, the agent reads it.

2. Link liberally.

Every time you mention a project, person, or concept that has its own note, use [[double brackets]] to link it. This builds the graph over time.

3. Daily notes are the input stream.

Write a daily note every day (even just a few sentences). What you're working on. What you're thinking about. What's stuck. This becomes the raw material the agent can process.

4. Context files are the cheat codes.

These are structured files specifically designed for the AI to consume. They contain your current state: what projects you're on, what your preferences are, how you like to work. More on this next.

Part 6: Writing Context Files (15 min)

What Is a Context File?

A context file is a Markdown document that captures your current state in a way that's optimized for AI consumption. It's like an onboarding doc for a new team member, except the team member is Claude Code and it reads perfectly every time.

Example: `work-context.md`

# Work Context

## Current Role
VP of Operations, Lab Integration Team at Kipu Health / Kipu Labs

## Primary Responsibilities
- Own and scale ~1,400 lab HL7 interfaces
- Design and enforce SOPs for lab onboarding, interface builds, testing, go-live
- Build automation across n8n, Postgres, AWS, Jira, Zendesk, Salesforce
- Produce executive-ready dashboards, revenue analysis, risk summaries

## Current Priorities (Updated March 2026)
- Scaling interface build capacity without adding headcount
- RAG system for Zendesk knowledge base (Bedrock + pgvector)
- Revenue falloff tracking and alerting
- Jira workflow automation for lab onboarding pipeline

## Technical Stack
- PostgreSQL (advanced), pgvector
- n8n orchestration
- AWS (Bedrock, Aurora)
- HL7 v2.x (OBX/OBR/ORC/PID)
- Django / Streamlit for internal tools

## Communication Style
- Direct, factual, no fluff
- Structured outputs (tables, code blocks, SQL)
- Executive summaries + technical detail when relevant
Click to copy

Example: `personal-workflow.md`

# Personal Workflow

## Schedule
- Monday: Operations + team standups
- Tuesday: Deep work (automation, builds)
- Wednesday: Stakeholder meetings, cross-functional
- Thursday: Deep work (data analysis, dashboards)
- Friday: Reviews, planning, documentation

## How I Work Best
- Give me structured options, not open-ended brainstorming
- I want deterministic outputs I can deploy immediately
- If you're unsure, say so. Don't guess.
- Think like an operator, not a tutor.

## Tools I Use Daily
- VS Code, n8n, Postgres, Jira, Zendesk, Slack
- Claude (web + API), Claude Code
- Obsidian for notes and context management
Click to copy

Example: `preferences.md`

# Preferences

## Output Format
- Markdown, code blocks, or tables
- No emojis in informational responses
- No em dashes
- No filler language
- Clear headers and bullet points

## When I Ask for Help
- Assume high technical literacy
- Skip the basics unless I ask
- Provide copy-paste-ready artifacts
- SQL, Python, Markdown, SOPs preferred formats
Click to copy

The Payoff

Once these files exist, a single /context command loads all of them into Claude Code. The agent immediately knows your role, your stack, your priorities, and how you like to communicate. No re-explaining. No warm-up. You go straight to productive work.

Part 7: Building Custom Slash Commands (20 min)

What Are Slash Commands?

Slash commands are custom shortcuts you create for Claude Code. When you type /commandname, Claude Code executes a predefined set of instructions.

You create them by asking Claude Code to build them. They live as configuration in your environment.

Essential Commands to Build

1. /context - Load Full Context

Purpose: Read all context files and daily notes to build a complete picture of your current state.

Tell Claude Code:
"Create a slash command called /context that reads all files in my
vault's context/ directory, reads the last 7 daily notes, and follows
any backlinks found in those files. After reading, confirm what you
now know about my current projects and priorities."
Click to copy

2. /today - Morning Planning

Purpose: Read your calendar, recent daily notes, and current priorities to generate a prioritized plan for the day.

Tell Claude Code:
"Create a slash command called /today that reads my last 5 daily
notes, checks my calendar for today, and cross-references with my
context files. Generate a prioritized plan for today. Flag anything
that conflicts with my stated priorities."
Click to copy

3. /ideas - Vault-Wide Idea Generation

Purpose: Scan the entire vault, identify patterns, and generate actionable ideas across all domains.

Tell Claude Code:
"Create a slash command called /ideas that scans all files in my
vault, identifies orphan notes, finds recurring themes across daily
notes, and generates a report with: tools to build, systems to
implement, subjects to investigate, things to write, and top 5
high-impact actions."
Click to copy

4. /trace [topic] - Idea Evolution Tracking

Purpose: Track how a specific idea or concept has evolved across your vault over time.

Tell Claude Code:
"Create a slash command called /trace that takes a topic as an
argument, searches the entire vault for mentions and related
backlinks, then produces a chronological timeline showing how my
thinking on this topic has evolved. Include direct quotes from
my notes with dates."
Click to copy

5. /connect [domain1] [domain2] - Cross-Domain Connection

Purpose: Find unexpected connections between two seemingly unrelated topics in your vault.

Tell Claude Code:
"Create a slash command called /connect that takes two topics as
arguments, finds all vault notes related to each topic (including
backlinked neighbors), then identifies bridges and connections
between the two domains."
Click to copy

6. /challenge [topic] - Pressure Test Beliefs

Purpose: Use your vault's own history to find contradictions, counter-evidence, and shifts in your thinking.

Tell Claude Code:
"Create a slash command called /challenge that takes a topic,
searches the vault for all my stated positions on that topic,
identifies contradictions or shifts in my thinking over time,
and pressure-tests my current beliefs with counter-arguments
drawn from my own notes."
Click to copy

7. /drift - Intention vs. Behavior Audit

Purpose: Compare your stated goals against your actual behavior over the last 30-60 days.

Tell Claude Code:
"Create a slash command called /drift that reads my context files
for stated intentions and priorities, then reads the last 30-60
days of daily notes to see what I actually spent time on. Surface
gaps, things I'm avoiding, and areas where behavior doesn't match
stated goals."
Click to copy

Tips for Building Commands

Start with Claude Code building it for you. Say what you want the command to do in plain English.
Once a command exists, ask Claude Code to suggest improvements based on what it knows about your vault.
Commands that read more files take longer. A full vault scan on 500+ files can take 5+ minutes. That's normal.
You can create domain-specific commands: /work for work context, /lab for home lab context, /jeep for vehicle project context.

Part 8: Thinking Tools, Beyond Code Generation (15 min)

The Real Power Move

Most people use LLMs to generate code or write text. That's useful. But the highest-leverage use of Obsidian + Claude Code is as a thinking partner.

When Claude Code has access to months or years of your notes, it can do things no human assistant can:

1. Pattern Recognition at Scale

You cannot read 500 of your own notes and identify recurring themes in 5 minutes. Claude Code can. It will find ideas you've been circling around for months without naming them.

2. The "Emerge" Function

Surface ideas your vault implies but never states. These are conclusions from scattered premises, unnamed patterns, and unarticulated directions. You wrote the pieces. The agent assembles the picture.

3. Ghost Mode

Ask Claude Code to answer a question the way you would. It builds a voice profile from your vault, writes in your voice, then evaluates how closely it matches. This is useful for delegation: "Would I approve this email if someone else wrote it?"

4. Contradiction Detection

Over time, your opinions shift. That's healthy. But unexamined contradictions can lead to bad decisions. The /challenge command finds these.

5. Therapeutic Reflection (Not Therapy)

The combination of daily notes + an agent that can trace your thinking over time creates something that looks like a coaching session. It can say: "You've mentioned this concern 12 times in 2 months but haven't taken action on it." That's powerful self-awareness.

A Note on Boundaries

This is not a replacement for therapy, coaching, or human connection. It's a tool. A very good tool for self-reflection and intellectual development. But it reads text. It does not understand you the way another human does. Use it as a supplement, not a substitute.

Part 9: From Reflection to Action, Generating Ideas (10 min)

Moving Beyond Journaling

The criticism of note-taking systems is that they become write-only storage. You write notes but never do anything with them.

Obsidian + Claude Code closes that loop. Here's how:

1. Ideas Command Generates Actionable Output

The /ideas command doesn't just list themes. It produces:

Tools to build - specific software or automation based on your vault patterns
Systems to implement - workflow changes backed by evidence from your notes
Subjects to investigate - research directions aligned with your actual interests
Things to write and publish - content ideas drawn from your expertise
Conversations to have - specific people to reach out to and why
Top 5 high-impact actions - prioritized next steps

2. Inline Delegation

Write a note like: "Schedule a call with [person] about [topic] this week." With the right agent setup (using OpenClaw or similar autonomous agents), that note becomes a task that gets executed without you prompting anything.

3. Command Chaining

The /ideas command suggests building a new /graduate command. You tell Claude Code to build it. Now your daily notes automatically get scanned for ideas worth promoting into standalone notes. Your system improves itself.

4. Vault as Team Knowledge Base

Everything described here works for personal vaults. But the same structure works for teams. Create a shared vault where team members contribute context files. Now Claude Code can answer questions about team projects, priorities, and decisions with full context.

Part 10: Privacy, Boundaries, and Vault Hygiene (10 min)

The Privacy Reality

Your vault is a detailed map of your thinking, projects, relationships, and beliefs. Giving an AI agent access to that is powerful. It's also worth thinking about carefully.

What to consider:

Claude Code runs locally. Your files are read on your machine. They're sent to Anthropic's API for processing, subject to Anthropic's data policies.
You control what's in the vault. Don't put anything in there you wouldn't want processed by an LLM.
Separate vaults for separate concerns. Consider a personal vault and a work vault. Or a vault you share with agents and one you keep private.
Demo versions of commands. If you're ever showing your setup publicly (a demo, a podcast, a stream), create demo versions of your commands that limit what the agent can access.

The Agent-Write Boundary

A strong recommendation from practitioners: do not let the agent write files into your vault.

Why:

If the agent creates notes, future vault scans will find patterns from the agent's writing, not yours
You lose the guarantee that the vault represents your authentic thinking
It becomes unclear what "you" wrote vs. what was generated

The agent can read your vault. It can generate output you review. But the actual vault content should be authored by you.

Vault Maintenance

Review orphan notes periodically (notes with no links). Either connect them or delete them.
Keep context files updated. Stale context is worse than no context.
Archive completed projects rather than deleting them. The historical record has value for /trace commands.
Tag notes with confidence levels if you're exploring uncertain ideas. The /challenge command can use these.

Part 11: What to Do Next (5 min)

Start Small

You don't need to build the entire system in one day.

Week 1:

Install Obsidian and create a vault
Write 3 context files (work, personal workflow, preferences)
Start writing daily notes (even 2-3 sentences)

Week 2:

Install Claude Code and the Obsidian CLI
Build the /context command
Test loading your context and asking Claude Code project questions

Week 3:

Build /today and /ideas commands
Start linking notes with [[double brackets]]
Experiment with /trace on a topic you've been thinking about

Week 4:

Build thinking tools: /challenge, /drift, /connect
Review your graph visualization
Refine your commands based on what's useful

The Compounding Effect

This system gets more valuable over time. A vault with 30 days of notes is interesting. A vault with 6 months is powerful. A vault with 2 years is a superpower.

Every note you write is an investment in the quality of every future AI interaction.

Resources

Obsidian: https://obsidian.md
Claude Code: https://docs.anthropic.com/en/docs/claude-code
Obsidian CLI: https://github.com/obsidianmd/obsidian-cli
Join the community on Discord: https://discord.gg/CHzuu9G9

Based on a conversation between Greg Eisenberg and Internet Vin about using Obsidian and Claude Code as a combined thinking and delegation system.

Obsidian + Claude Code: Building Your Second Brain

Obsidian + Claude Code: Building Your Second Brain

Part 0: Intro

Tutorial Path

Requirements

Part 1: Why Context Is the Bottleneck (10 min)

The Problem Everyone Hits

The File Is the Memory

Part 2: What Is Obsidian? (10 min)

The Basics

What Makes It Different from a Folder

The Graph Visualization

Part 3: What Is Claude Code? (5 min)

Slash Commands

Part 4: The Obsidian CLI, the Bridge (10 min)

What It Does

Why the Graph Matters

Installation

Part 5: Setting Up Your Vault (15 min)

Vault Structure

Key Principles

Part 6: Writing Context Files (15 min)

What Is a Context File?

Example: work-context.md

Example: personal-workflow.md

Example: preferences.md

The Payoff

Part 7: Building Custom Slash Commands (20 min)

What Are Slash Commands?

Essential Commands to Build

Tips for Building Commands

Part 8: Thinking Tools, Beyond Code Generation (15 min)

The Real Power Move

A Note on Boundaries

Part 9: From Reflection to Action, Generating Ideas (10 min)

Moving Beyond Journaling

Part 10: Privacy, Boundaries, and Vault Hygiene (10 min)

The Privacy Reality

The Agent-Write Boundary

Vault Maintenance

Part 11: What to Do Next (5 min)

Start Small

The Compounding Effect

Resources

Example: `work-context.md`

Example: `personal-workflow.md`

Example: `preferences.md`