obsidian-second-brain

Turn your Obsidian vault into a personal AI operating system.
20 commands · 4 thinking tools · 4 scheduled agents · 1 background agent

Install · Features · Commands · Agents · Contributing · Discussions

Who Is This For?

If you take notes in Obsidian and use Claude, this skill is the bridge between the two.

The Problem

Most people use AI as a search engine. Ask a question, get an answer, forget it. Every session starts from zero. Your best ideas, decisions, and lessons scatter across chats that disappear.

And note-taking doesn't help — you take notes but never connect them. Decisions get made and forgotten. Patterns repeat across projects because you can't see them. Ideas sit in daily notes and never become anything.

The Solution

This skill solves both problems at once. Your vault becomes Claude's memory, and Claude becomes your vault's brain.

You talk. Claude remembers. Every decision, person, task, and idea gets saved to the right place — automatically.

You write. Claude thinks. Your notes become fuel for insight. Claude red-teams your plans, finds unnamed patterns, and connects ideas across domains you'd never link yourself.

You sleep. Claude maintains. Scheduled agents run morning, night, and weekly — autonomously. A background agent fires after every compaction and silently updates your vault while you keep working.

How It Compares

The Three Layers

                    +-----------------------------------------+
                    |        obsidian-second-brain             |
                    +-----------------------------------------+
                    |                                         |
  LAYER 1           |   Vault Operations (14 commands)        |
  "Claude           |   save, daily, log, task, person,       |
   remembers"       |   decide, capture, find, recap,         |
                    |   review, board, project, health, init  |
                    +-----------------------------------------+
                    |                                         |
  LAYER 2           |   Thinking Tools (4 commands)           |
  "Claude           |   challenge  - red-team your ideas      |
   thinks           |   emerge     - surface hidden patterns  |
   with you"        |   connect    - bridge unrelated domains |
                    |   graduate   - idea -> full project     |
                    +-----------------------------------------+
                    |                                         |
  LAYER 3           |   Context Engine (1 command)            |
  "Claude           |   world - load identity + state         |
   knows you"       |          in one shot                    |
                    +-----------------------------------------+
                    |                                         |
  ALWAYS ON         |   Background Agent (PostCompact hook)   |
                    |   4 Scheduled Agents (cron)             |
                    +-----------------------------------------+

Commands at a Glance

Layer 1: Vault Operations

Claude remembers everything. You never think about where to save something.

Every command searches before creating (no duplicates), propagates to every linked note (no orphans), and handles typos with fuzzy matching.

Layer 2: Thinking Tools

This is what makes this skill different. These commands don't organize — they generate insight.

/obsidian-challenge

You say: "I want to rewrite the API in Rust."

Claude searches your vault, finds your 2025 post-mortem where you abandoned a Rust rewrite due to hiring constraints, and your decision log where you committed to TypeScript for 2 years. It presents the counter-evidence and asks: "Still want to proceed?"

This is your vault arguing with you — using your own words.

/obsidian-emerge

After a busy month, Claude scans 30 daily notes and finds you mentioned "onboarding friction" in 4 different client projects without ever naming it as a problem.

It surfaces: "You have an unnamed pattern — onboarding is your bottleneck across projects, not a one-off issue."

These are conclusions your notes already contain but you never stated.

/obsidian-connect "distributed systems" "cooking"

Claude traces both clusters in your link graph and finds shared concepts around preparation and load distribution. It generates 3 concrete ideas at the intersection — not vague analogies, but actionable concepts grounded in your own notes.

/obsidian-graduate

An idea you captured 3 weeks ago is ready to become real. Claude reads the idea note, researches your vault for related projects and people, and generates a full project spec with goals, phases, tasks, and board entries.

The idea note gets tagged graduated and linked to the new project. Nothing dies in your inbox.

Layer 3: Context Engine

Every session picks up where you left off.

Run /obsidian-world at the start of any session. Claude reads your SOUL.md, checks your last 3 daily notes, scans your boards, and reports:

"You're focused on the API launch (due Friday), you left off debugging the auth middleware last night, and you have 2 overdue tasks on the Marketing board."

No re-explaining. No context loss.

Background Agent

The most hands-off feature. Fires automatically after every context compaction — no user action needed.

PostCompact -> obsidian-bg-agent.sh -> claude -p (headless) -> vault updated

A headless Claude subprocess wakes up, reads _CLAUDE.md, scans the session summary, and writes updates everywhere they belong. You keep working. The vault updates itself.

Scheduled Agents — Claude works while you sleep

Set up once: /schedule

Parallel Subagents

Complex commands spawn parallel subagents — one per task group — and merge results when all finish.

How _CLAUDE.md Works

The entire system runs on one file at your vault root.

Your Mac
|
+-- Claude Desktop / Claude Code / VS Code
|   +-- reads _CLAUDE.md on every session start
|
+-- Your Vault/
    +-- _CLAUDE.md          <-- Claude's operating manual
    +-- Home.md
    +-- Daily/
    +-- Projects/
    +-- Boards/
    +-- ...

Every Claude surface reads this file first. It contains your folder structure, naming conventions, frontmatter schemas, propagation rules, and active context. No memory required. Every session starts with full context.

Install

Two commands. That's it.

# 1. Clone the skill
git clone https://github.com/eugeniughelbur/obsidian-second-brain ~/.claude/skills/obsidian-second-brain

# 2. Run setup (wires the hook, sets vault path, optionally configures MCP)
bash ~/.claude/skills/obsidian-second-brain/scripts/setup.sh "/path/to/your/vault"

Then run:

/obsidian-init

Claude scans your vault and generates a _CLAUDE.md — its operating manual for your specific vault.

python ~/.claude/skills/obsidian-second-brain/scripts/bootstrap_vault.py \
  --path ~/my-vault \
  --name "Your Name" \
  --jobs "Company Name"

Creates a complete vault with folders, templates, kanban boards, a Home dashboard, and a pre-filled _CLAUDE.md. Then run setup.sh pointing at the new path.

Recommended Obsidian Plugins

Skill Structure

obsidian-second-brain/
+-- SKILL.md                        # Core instructions for Claude
+-- commands/                       # 19 slash commands
+-- hooks/                          # Background agent hook
+-- references/
|   +-- vault-schema.md             # Folder structure + frontmatter specs
|   +-- write-rules.md              # Writing, linking, and propagation rules
|   +-- claude-md-template.md       # Template for generating _CLAUDE.md
+-- scripts/
|   +-- setup.sh                    # One-command installer
|   +-- bootstrap_vault.py          # Bootstrap a vault from scratch
|   +-- vault_health.py             # Audit a vault for structural issues

Philosophy

Most second brain tools make you the janitor. You spend more time organizing than thinking.

This skill inverts that. You think, work, and talk. Claude handles the memory. And then it uses that memory to make you think better — surfacing what you'd miss, challenging what you'd assume, and connecting what you'd never link.

The vault gets smarter every day you use it. Not because of AI magic, but because your own writing compounds. The more you write, the more context Claude has, the more it can do for you.

Your notes are the moat.

Contributing

PRs welcome. Especially interested in:

• New thinking tools (novel ways to use vault data for insight)
• Note type schemas (habits, books, investments)
• MCP integrations (Calendar, Linear, Slack context in daily rituals)
• Alternative vault structures (GTD, PARA, Zettelkasten variants)
• VS Code / Cursor setup guides

Author

Built by Eugeniu Ghelbur

License

MIT