Claude Code second brain: setup and review workflow

A Claude Code second brain is your notes folder with Claude Code running inside it. Claude Code is Anthropic's coding agent, but nothing about it is specific to code: it reads files, writes files, searches folders and runs commands. Point it at an Obsidian vault and it can file your inbox, turn meeting notes into project updates, answer questions from everything you've written, and keep links between notes up to date.

The difference from a chat app is that the notes are the memory. You don't paste context into each conversation. Claude reads what it needs from disk, and whatever it writes stays in plain markdown files you own. Andrej Karpathy's LLM wiki is the same idea taken further: the agent maintains a whole wiki from your sources.

There is a catch. An agent that can improve every note can also quietly change a note you rely on. So this guide covers the setup and, just as much, how to see and approve what Claude changes: with git, which works today, and with Knowtarium.

Knowtarium is a desktop app we're building for knowledge that people and agents write together. It opens your notes folder, puts every change Claude makes in a review queue as a diff, and shows who wrote and who checked each note. It's in pre-order and not released yet. Short notes along the way say how Knowtarium handles each part.

You need Claude Code installed (see Anthropic's docs) and a folder of markdown notes. Obsidian is optional: Claude only needs the folder.

1. Take a snapshot first

Before Claude touches anything, put the vault under git and commit. This is your undo button for everything that follows, and it takes a minute. Add a .gitignore so Obsidian's layout files don't clutter every diff:

# Obsidian rewrites these constantly; keep them out of your diffs
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
CLAUDE.local.md

2. Start Claude Code in the vault

$ cd ~/Notes                  # your vault
$ git init && git add -A
$ git commit -m "before Claude"
$ claude
> /init

/init looks at the folder and drafts a CLAUDE.md. It was designed for code, so treat the draft as a starting point and rewrite it with the rules below. Run /context to confirm the file loaded.

3. Decide how much Claude can do without asking

Claude Code has permission modes. In Manual mode it asks before each edit. Plan mode has it propose a plan without editing, which suits a first session in a vault you care about. You switch between them with Shift+Tab. The permission modes page lists which mode a session starts in, which depends on your version and account.

CLAUDE.md is a markdown file Claude Code reads at the start of every session. For a vault, it should answer three questions: how the vault is organised, how Claude should write, and what it must report back. Anthropic's memory docs give the rules that matter:

• Keep it under about 200 lines. Longer files use more context and are followed less reliably.
• Write instructions you could check ("journal/ is read-only", not "be careful with my notes").
• Pull in other files with @path imports, such as a note with your current priorities.
• A CLAUDE.md in a subfolder loads when Claude reads files there, so a big project can carry its own rules.
• Put personal notes you don't want in git in CLAUDE.local.md.

# This vault
 
Personal notes, managed in Obsidian. Plain markdown, wikilinks.
 
## Layout
- inbox/: raw captures. Process them, then move them out.
- projects/: one folder per active project, with a README.md.
- areas/: ongoing topics (health, money, work).
- journal/: my daily notes. Read them, never edit them.
- archive/: finished projects. Don't touch.
 
## How to write
- Keep my wording. Add, don't rewrite, unless I ask.
- New notes get frontmatter: type, created, source.
- When you state a fact, link the note or URL it came from.
- Link people as [[First Last]], projects as [[Project Name]].
 
## After every task
- List the files you created, changed or moved.
- Add a line to log.md: date, what you did, which files.
 
Current priorities: @context/now.md

"Keep my wording" and "list the files you changed" are the two lines people most often wish they had written on day one. The first stops Claude from polishing your voice out of your notes. The second makes review possible.

Make the important rules hard rules

The docs are explicit that CLAUDE.md is context, not enforced configuration. Claude tries to follow it, with no guarantee. For folders that must never change, add a deny rule to .claude/settings.json in the vault. Edit rules cover Claude's file tools and common shell commands, though not a script that opens files itself, so keep git as the backstop.

{
  "permissions": {
    "deny": ["Edit(/journal/**)", "Edit(/archive/**)"]
  }
}

Claude Code has two kinds of memory, and it helps to know where each one lives.

When you tell Claude "remember that I review invoices on Fridays", it goes to auto memory. When you say "add this to CLAUDE.md", it goes to the file. /memory lists both and opens them.

For a second brain, keep the context you care about inside the vault, where you can read it, git tracks it and every agent can see it. A small context/now.md with this week's priorities, imported from CLAUDE.md, does more than a long memory file. Update it yourself on Mondays, or ask Claude to draft the update and review it like any other change.

Most of the value comes from a handful of repeatable jobs:

• Inbox triage. Claude proposes where each capture belongs, you approve, it moves the notes and links them.
• Meeting notes to project updates. Paste or drop a transcript; Claude writes a summary, updates the project README and lists open actions.
• Ask your notes. "What did I decide about the pricing page, and why?" Ask it to answer with links to the notes it used.
• Weekly review. Read the week's journal and project notes and draft a review note, without editing the originals.
• Link maintenance. Find orphan notes, broken links and notes that should link to each other, and propose fixes as a list.

Turn each job you repeat into a skill. A skill is a SKILL.md file in .claude/skills/<name>/; you run it by typing /<name>, and Claude can also pick it up when your request matches its description. Unlike CLAUDE.md, a skill only loads when it's used, so detailed procedures cost almost nothing the rest of the time.

---
description: Process the inbox. Use when I say 'process inbox' or 'triage'.
---
 
For each note in inbox/:
1. Decide where it belongs: a project, an area, or the bin.
2. Show me the plan as a table before moving anything.
3. After I approve, move the notes and add links from the
   project or area README.
4. Never delete a note. Put rejects in archive/inbox-rejects/.
5. List every file you touched.

Built-in commands worth knowing in a vault:

After a few weeks, a Claude Code second brain holds notes you didn't write yourself, and notes you did write that Claude has since edited. Both are fine, as long as you know which is which. Typical problems:

• A tidy-up pass rewrites a note in Claude's voice and drops the one caveat that mattered.
• A summary states a date or number that isn't in the source note.
• A move breaks links, because Claude moved the file with a shell command and nothing updated the links.
• You fix a fact in one note, and three others still carry the old version.
• A note Claude wrote months ago reads as confidently as one you checked yesterday.

Claude Code's /rewind helps within a session, with limits the checkpointing docs spell out: it doesn't track files changed by shell commands (such as mv or rm), and it's "not a replacement for version control". For notes you keep for years, you want a review step that doesn't depend on the session.

Git is the baseline. It's free and works today: commit before a session, let Claude work, then read the diff and keep only what you approve.

$ git status --short           # what changed while Claude worked
$ git diff --stat
$ git diff projects/           # read the edits, folder by folder
$ git add -p                   # keep what's right, hunk by hunk
$ git commit -m "inbox triage, reviewed"
$ git restore .                # discard the rest
$ git clean -n                 # preview new files you didn't keep

A few habits make this fast:

• One task per session, one commit per task. A diff of 4 files is easy to read; a diff of 60 isn't.
• Read the list of changed files first. Anything outside the folder you asked about deserves a closer look.
• Check new facts against the note or link they cite. Uncited facts are the ones to question.
• If anything commits your vault on a timer, its commits will mix your edits with Claude's. Commit by hand around Claude sessions, or review with git log -p afterwards.

Git shows you a diff when you remember to commit. Knowtarium keeps the review next to the notes, which is the setup we recommend once Claude writes more than you want to read in a terminal. It opens your notes as an OKF bundle: plain markdown whose frontmatter records who wrote each note, who checked it, where its claims came from and when it goes stale.

• Claude's changes wait for you. Every change Claude makes lands in the review queue as a diff against the last checked version. You approve it or send it back with a comment, and Claude can't overwrite an edit you made: conflicts come to you.
• Your edits wait for Claude. When you edit a note yourself, the edit is marked as yours and waits until you ask Claude to check it, for example "check today's edits". Claude compares it with everything connected, and any fixes it proposes wait for you.
• Every note has a trust tier. Unverified, machine-confirmed, human-reviewed, stale, or fully verified once both you and an agent have checked it after its last change. The graph takes the same colours.
• Nothing goes stale quietly. Notes past stale_after dim, and the queue shows what expires in the next 30 days.
• Claude keeps working on the files. Knowtarium doesn't call an AI itself. The included skill teaches Claude the conventions, and it signs every change with its name.

Everything stays on your computer, on macOS, Windows or Linux. Knowtarium costs $20 once, or $10 during pre-orders, with no subscription and no account. A free migration skill converts an Obsidian vault into an OKF bundle and leaves your writing alone. See the migration guide, and the comparison page for how the two apps differ.

Nothing here is specific to Claude Code. Any agent that can read and write files in a folder can run your second brain. The main difference is the name of the instruction file:

• Codex reads AGENTS.md, from ~/.codex and from the folders between the git root and where you start it, up to a combined 32 KiB by default (Codex docs).
• Cursor reads AGENTS.md too, as a simpler alternative to its .cursor/rules files (Cursor docs).
• Claude Code reads AGENTS.md when there's no CLAUDE.md, on recent versions. The portable setup is to keep your rules in AGENTS.md and make CLAUDE.md a single line, @AGENTS.md, plus anything Claude-specific.

Then every agent follows the same vault rules, and the same review catches all of them, in git or in Knowtarium's queue. Our guide to AGENTS.md for knowledge bases has a fuller template. If you're choosing an app to read the result, the AI second brain overview covers the wider picture, and Karpathy's LLM wiki idea file is worth reading for the wider pattern.