Building a second brain with Obsidian and Claude Code

Everyone talks about building a "second brain." Most people mean color-coded folders in Notion. I mean something different: a knowledge base that an AI agent can read, search, cross-reference, and update on its own. Your projects, diary entries, ideas, meeting notes, voice memos, all living in one place. The AI knows your context. It remembers what you forgot. It connects dots you didn't know existed.

I've been running this setup for about two months now. Obsidian vault on my Mac, synced through iCloud and backed up to GitHub. Claude Code as the agent that lives inside it. The whole thing cost me $20/month for Claude Pro (now $100 for Max, but Pro works fine for this). No fancy apps, no SaaS subscriptions, no vendor lock-in. Just markdown files and a really good AI.

Here's how it works and why I think most people get this wrong.

What "second brain" actually means

Let me be blunt: if your second brain is a note-taking app where you dump stuff and never look at it again, you don't have a second brain. You have a digital graveyard.

A real second brain needs three things:

1. Structure that an agent can navigate. Not structure for you to browse. Structure for an AI to programmatically find what it needs.
2. Instructions that define behavior. The AI needs to know what to do with new information, where to put it, what not to touch.
3. An input pipeline. You need a way to feed it information without friction. If adding a thought requires opening a laptop and typing in a specific file, you won't do it.

The magic moment was when I realized the vault isn't for me to read. It's for the AI to read. I still browse it sometimes in Obsidian, follow links, review my diary. But the primary consumer of this knowledge base is Claude Code. I'm the writer. It's the reader.

The folder structure

I kept this simple on purpose. Every time I wanted to add complexity, I asked myself: will Claude Code understand this? If the answer required a paragraph of explanation, I simplified.

vault/
  CLAUDE.md              # Instructions for the agent
  tasks.md               # Central task list
  projects/
    swanrate/
      overview.md
      tasks.md
      ideas.md
    second-brain/
      overview.md
      tasks.md
      reading-list.md
    digital-twin/
      overview.md
      dania-zip-spec.md
    [other projects...]
  personal/
    diary/
      2026-01-25 [topic summary].md
      2026-01-30 [topic summary].md
  work/
    ton_foundation/
      readme.md

Every project follows the same pattern: overview.md (what is this project), tasks.md (what needs to be done), ideas.md (backlog of half-baked thoughts). That's it. When Claude Code lands in any project folder, it immediately knows where to look.

Diary entries use the format YYYY-MM-DD [summary].md. The summary in the filename matters because Claude Code can scan filenames with glob patterns before deciding which files to actually read. If I name a file 2026-01-30 Always-on Obsidian Agent on server.md, the agent can find it without reading every single diary entry.

The work/ folder is for my day job at TON Foundation. Separate from personal projects. Clean boundaries.

CLAUDE.md: the file that makes it all work

This is the secret. Not the folder structure, not the vault, not the sync setup. It's one file in the root of your vault called CLAUDE.md. Claude Code reads it automatically when you open a session in that directory. It's your instruction manual for the agent.

Here are real excerpts from mine:

# Voice messages and long inputs

When you receive a voice note or long text:
1. Save raw text to personal/diary/YYYY-MM-DD [summary].md
2. Add tags and project links below the raw text
3. Extract TODOs to tasks.md or project-specific tasks
4. Facts about projects go to projects/X/overview.md

Why save raw text: you can return to raw data later
and extract more information.

And the project structure rules:

# Project structure (projects/)
Each project contains:
- overview.md - project description (required)
- tasks.md - project tasks
- ideas.md - idea backlog
- ai-docs/ - AI-generated documents

And the critical one:

# Diaries (personal/diary/)
Format: YYYY-MM-DD [summary].md
- Raw transcriptions: DO NOT EDIT
- Tags and links are added below

That last rule is important. When I record a rambling voice note about five different topics, the raw transcription goes in untouched. It's messy, it has filler words, half-finished sentences, random tangents. I don't care. That raw data is a gold mine. Six months from now I might ask Claude to analyze my thinking patterns, and those raw notes will be more valuable than any cleaned-up summary.

The agent adds tags, project links, and extracted TODOs below the raw text. The original stays pristine. I learned this the hard way after an early version of my setup "helpfully" cleaned up a diary entry and I lost the context of what I was actually thinking.

My CLAUDE.md also lists environment variables (API tokens for Telegram, X/Twitter, Coolify), social media accounts for crossposting, and pointers to project-specific instructions. When the agent needs to deploy something, it knows where the Coolify token is. When it needs to post to Twitter, it has the API keys. All documented in one place.

If you take nothing else from this article: write a CLAUDE.md. Even a bad one. You'll iterate on it every day as you discover what the agent gets wrong. Mine has been rewritten probably fifteen times in two months. It gets better each time because I see exactly where the agent misunderstands my intent.

Voice to knowledge: the input pipeline

The most valuable ideas come when you're not at your desk. Walking, showering, commuting. The problem: by the time you open a laptop, the thought is already half-gone.

My pipeline: I record a voice message in Telegram. Takopi (a Telegram bridge for Claude Code) picks it up, transcribes it via OpenAI's Whisper, and passes the text to Claude Code. Claude Code follows the CLAUDE.md instructions: saves the raw transcription to personal/diary/, extracts TODOs, updates relevant project files.

Real example: I was walking and realized my Obsidian agent stops working when my laptop is asleep. I recorded a rambling 3-minute voice note about wanting to deploy the agent on a server. By the time I got home, the vault had:

• A diary entry with the full raw transcription (all the "ums" and half-sentences intact)
• A new section in tasks.md under "Always-on Obsidian Agent" with specific steps: deploy Takopi + Claude Code in Docker on Coolify, set up git sync, write a server-specific CLAUDE.local.md
• A new config file at projects/second-brain/server-takopi-config.md with the Docker image, environment variables, and deployment plan

From a messy voice note to structured, actionable knowledge. No manual filing. No copy-pasting between apps.

The pipeline isn't perfect. Sometimes the transcription butchers technical terms. Sometimes Claude files something in the wrong project. But it's 80% right, and fixing the 20% takes seconds. Compare that to doing 100% of the organization manually.

I'm now working on deploying this to a server so it works even when my laptop is off. The plan: a Docker container on Hetzner via Coolify, running Takopi in polling mode. The vault lives in a GitHub repo, and the server pulls changes before each session, commits and pushes after. I described this whole architecture in more detail in my Claude Code workflow article.

Daily use cases

Morning priorities. I open Claude Code in the vault directory and ask: "What are my priorities today?" It reads tasks.md, checks project-specific task files, looks at recent diary entries for context. It doesn't just list tasks; it tells me which ones are urgent based on deadlines and dependencies I've mentioned in previous notes. Last week it reminded me about a client who'd been waiting for a data export for three days because I'd mentioned it in a voice note and promptly forgot.

Research queries. "What do I know about programmatic SEO?" Claude searches the vault, finds my SwanRate research notes, a diary entry about keyword tools, links I'd bookmarked, and a half-finished analysis of Yandex Wordstat data. It synthesizes everything into a summary. Without this, I'd spend 20 minutes clicking through Obsidian links trying to remember where I put things.

Cross-referencing. This is where it gets interesting. I have a project called dania.zip where I'm building a portable personality file, basically packaging myself for AI agents. When I was writing the spec, I asked Claude to pull in my tone-of-voice notes, examples from my Telegram posts, and personality traits from diary entries. It connected files I'd written weeks apart into a coherent specification. I genuinely forgot I'd written some of those notes.

Pattern analysis. I asked Claude to analyze a month of diary entries and tell me what I spend most of my time thinking about. Turns out: 40% infrastructure and deployment problems, 30% content and audience building, 20% product features, 10% random ideas. Useful to know when you think you're focused on product but you're actually obsessing over Docker configs.

Content generation. Every article I write (including this one) starts with Claude reading the relevant project files, diary entries, and previous posts. It knows my writing style because I have a tone-of-voice.md file and examples of published posts in the vault. It doesn't write the final text, but it gives me a draft that sounds like me, not like generic AI slop. I then rewrite the parts that feel off.

Why local matters

I could use Notion AI, or ChatGPT with file uploads, or any number of cloud-based "second brain" tools. I chose Obsidian + local Claude Code for specific reasons:

Your data stays on your machine. My vault has diary entries, client information, API tokens, half-formed business ideas, and raw voice transcriptions where I sometimes say things I wouldn't publish. None of this goes to a third-party server (beyond the Claude API calls, which are ephemeral and governed by Anthropic's data policy). The files live on my Mac, synced through iCloud, backed up to a private GitHub repo.

No vendor lock-in. It's markdown files in folders. If Obsidian disappears tomorrow, I open the files in VS Code, or Typora, or literally any text editor. If Claude Code disappears, the vault still works as a regular Obsidian knowledge base. If I switch to a different AI agent, I just point it at the same folder and write a new instruction file.

It works offline. Obsidian works without internet. I can browse my vault, add notes, review tasks on a plane. The AI features need a connection, but the knowledge base itself is always available.

Claude Code runs locally. The agent executes on my machine. It can read files, run bash commands, make API calls. There's no upload step, no "attach your files" workflow. It just reads the directory. This makes the feedback loop incredibly fast. I described my full tool setup in the AI tools article.

The tradeoff is obvious: you need to set things up yourself. There's no onboarding wizard, no templates gallery, no "click here to enable AI." You write a CLAUDE.md file and iterate. For me that's a feature, not a bug. I'm building exactly the system I need, not adapting to someone else's idea of what a second brain should be.

What I got wrong

Transparency time. Not everything worked on the first try.

Over-structuring. My first vault version had nested folders four levels deep, with separate files for "sources," "conclusions," "action items," and "open questions" in every project. Claude Code didn't care about my beautiful taxonomy. It just needed to find stuff. I flattened everything to two levels max and the agent got noticeably better at navigation.

Editing raw notes. I mentioned this already, but it burned me enough to repeat: never let the AI rewrite your raw transcriptions. Summaries are lossy. The original rambling contains nuance that you might need later. Add structure below the original, never replace it.

Missing instructions for edge cases. My first CLAUDE.md was five lines long. "You're my AI assistant. Help me organize my vault." Useless. The agent made random decisions about where to file things, how to format entries, when to create new files vs. update existing ones. Every time it did something wrong, I added a rule. Now my CLAUDE.md is about 80 lines and covers most situations. It's still growing.

Not committing to git often enough. I'd work with Claude Code for an hour, make twenty changes across the vault, and then realize I couldn't undo a specific bad edit because there was no commit history. Now I'm working on auto-committing after every agent session. Version control isn't optional for a vault that AI can write to.

Reading list and tools

Stuff I found useful while building this:

• Personal AI Infrastructure by Daniel Miessler. Great README that frames the whole concept of personal AI. Read this first if you're starting from zero.
• Claudesidian. An Obsidian plugin that integrates Claude directly into the app. I didn't use it (I prefer Claude Code in terminal), but it's worth checking if you want a GUI-first approach.
• Takopi. The Telegram bridge I use for voice-to-vault. Minimal, does one thing well. Supports voice transcription through OpenAI.
• Obsidian. Free, local-first, markdown-based. The vault is just a folder of .md files. That simplicity is the whole point.
• Claudia by @evgeth_. A similar setup by a developer at Zerion: Obsidian + Claude Agent SDK + Telegram + Git. He uses a PR workflow where the agent creates pull requests instead of writing directly to the vault. Smart approach if you want human-in-the-loop review on every change.

Getting started in 30 minutes

If you want to try this:

1. Install Obsidian. Create a new vault. Doesn't matter where.
2. Create the folder structure. projects/, personal/diary/, and a root tasks.md.
3. Write a CLAUDE.md. Start with three rules: where to save diary entries, where to save tasks, and what not to edit. You'll add more rules as you go.
4. Install Claude Code. npm install -g @anthropic-ai/claude-code. Open your terminal in the vault directory and type claude.
5. Talk to it. "Read my CLAUDE.md and tell me what you understand about this vault." Then start adding notes, asking questions, giving it tasks. Correct it when it does something wrong. Add that correction to CLAUDE.md.

That's the whole setup. No Docker, no servers, no Telegram bots. Those come later when you realize you want voice input and always-on access. Start simple. Let the complexity grow from actual needs, not hypothetical ones.

You've essentially made a pathetic copy of your brain, except it has perfect memory and doesn't get distracted by Twitter. That's a pretty good deal for $20 a month.

This is part of a series about my AI workflow. Previously: Claude Code workflow in 2026. Up next: dania.zip: packaging yourself for AI and my full AI tools setup.

Questions? I'm most responsive on Telegram where I post shorter updates about this stuff regularly.

Find me elsewhere: X (Twitter) · Telegram · GitHub