ClaudeBrain

A personal knowledge vault that Claude Code operates for you.

ClaudeBrain is an Obsidian-compatible Markdown PKM, wired so that Claude Code is the engine that reads, writes, and maintains it. PARA folders for your notes, a _meta/ "brain" Claude reads at the start of every session, a set of slash-command skills, a read-only multi-agent review council, and honesty hooks that lint your notes and brief you on session start.

It runs with zero external services by default — clone it, open it in Claude Code, run /setup, and you have a working single-machine vault. Notion, Google, an Obsidian GUI, and a nightly auto-maintenance pass are all optional add-ons.

Use this as a GitHub template, not a fork: you get a clean single-commit history with none of the original author's content — exactly what you want for a vault that will hold personal data.

---

Getting Started

What this is

An Obsidian PKM vault operated by Claude Code. PARA folders (00-inbox, 10-projects, 20-areas, 30-resources, 40-archive, plus 50-daily/55-goals) hold your notes; a _meta/ brain holds the files Claude reads to stay oriented; slash-command skills do the repetitive work (daily notes, captures, weekly reviews, project scaffolding); a 14-seat agent council stress-tests hard decisions; and lightweight hooks keep your notes honest. The whole capture/journaling loop works headless with no external services — integrations are opt-in.

Prerequisites

Required

Requirement	Notes
Git	To clone your repo and for the vault's git-backed workflows. On Windows, Git for Windows is recommended (it enables Claude Code's Bash tool).
Claude Code	The engine. Install via the native installer (auto-updates, no Node.js dependency).
A paid Claude plan or Console API access	Claude Pro / Max / Team / Enterprise, or a Claude Console account with credits (or Bedrock / Vertex AI / Foundry). The free Claude.ai plan does not include Claude Code.
A GitHub account	To create your private copy from the template.

Optional (each has a pure-vault fallback)

Optional	Why you'd add it
Obsidian	A human GUI: graph view, backlinks, the Properties panel. The vault is plain Markdown and runs fully headless without it.
Python 3 (python/python3 on PATH)	Powers the note-lint and session-status hooks and /dream's deterministic pass. Strongly recommended.
Notion + the Notion MCP	Task capture and the /daily task-pull. Fallback: tasks land in 00-inbox/.
Google (Calendar / Gmail) + their MCPs	Memory-jogs for /daily-catchup; email triage. Fallback: silently skipped.
A git remote with non-interactive push	Multi-machine sync and the optional nightly /dream.

1. Install Claude Code

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows — pick the line for your shell:

# PowerShell (prompt shows "PS"):
irm https://claude.ai/install.ps1 | iex

:: Command Prompt (no "PS" prefix):
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Verify (all OSes):

claude --version

The old npm install -g @anthropic-ai/claude-code path is deprecated. Use the native installer above.

2. Get your own copy (private first)

On this repo's page, click Use this template → Create a new repository. Set Visibility = Private — your vault will hold personal data. Your new repo starts from a single fresh commit with no inherited history and no "forked from" link; that clean history is exactly why a template (not a fork) is the right starting point.

3. Clone it

git clone https://github.com/<your-username>/<your-repo>.git
cd <your-repo>

Prefer SSH keys? Use the SSH clone URL shown under GitHub's green Code → SSH button instead of the HTTPS one above.

4. Open it in Claude Code

cd <your-repo>
claude

On first session start, Claude Code auto-discovers and loads: the project CLAUDE.md, the .claude/ tree (skills/, agents/, hooks/, settings.json), and any .mcp.json at the repo root. The SessionStart hook prints a computed status briefing.

5. Run /setup

/setup

The guided first-run. It interviews you (preferred name, vault name, which integrations), proposes a batch of edits that personalize the _meta/* placeholders, sets your vault name across configs and obsidian://vault= URIs, replaces the <your-username>/<your-vault> references, retires the setup checklist, and seeds the changelog. Each write is a diff you approve; profile.md and memory.md are protected (propose-and-wait). Anything you skip stays a > [!todo] prompt — that's fine, not a failure.

Fallback: follow START-HERE.md by hand.

A newcomer can stop here and have a fully working, single-machine, zero-external- service vault. Everything below is optional.

6. (Optional) Open in Obsidian

Install Obsidian (free, no account), choose Open folder as vault, and select the repo root (the folder with CLAUDE.md and the shipped .obsidian/). [[wikilinks]] become clickable, YAML frontmatter renders as a Properties panel, and Ctrl/Cmd-G opens the graph. The vault works fully headless — this is just a GUI on top of the same files.

7. (Optional) Connect integrations

Notion, Google Calendar, and Gmail are each opt-in via MCP, each with a pure-vault fallback. Map the skills to your schema; never hardcode anyone else's IDs.

# Example: add the Notion MCP for your own user (not committed to the repo):
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp
claude mcp list   # status should read "Connected"

See _meta/integrations.md for the full optional-integrations catalog and _meta/notion-bridge.md for the configurable-mapping policy.

8. (Optional) (Advanced) Nightly /dream

/dream is the vault's nightly hygiene + chief-of-staff pass. It works any time, manually, with zero setup — just type /dream. If you want it to run unattended every night, the scheduler recipes (macOS launchd / Linux cron or systemd / Windows Task Scheduler) live in docs/dream-autonomous-setup.md. A new user can ignore this entirely.

9. (Optional) Go public when ready

When you want to share your customization, flip the repo to public in Settings → General → Danger Zone → Change visibility — but scrub the working tree and every commit you added first. Run the residual-data scan:

python scripts/scan-residual.py

It flags emails, phone numbers, Notion IDs, absolute user paths, and any names/handles in its PERSONAL_TERMS list, and exits non-zero on a hit.

[!warning] Privacy: what NOT to put in a public copy. The vault syncs across devices and lives on GitHub. Treat it like a journal a third party could read. Never commit passwords, API keys, account numbers, recovery phrases, or 2FA seeds; other people's private info without consent; or anything you wouldn't read aloud in a job interview. Truly sensitive material belongs in a password manager, not here. Keep the repo Private while it holds personal data.

---

How the vault works (read next)

📖 Want the complete tour? docs/repository-guide.md explains every folder and every file in this repo, top to bottom (~13k words). The table below is the quick version; the guide is the deep one.

Piece	Where	What it is
Operating instructions	CLAUDE.md	The house rules Claude reads every session: source-of-truth policy, the folder layout, link/frontmatter hygiene, the Notion bridge.
The _meta/ brain	_meta/	The files Claude reads to stay oriented. orient.md (current state of the world), profile.md / memory.md (who you are — protected), tags.md (the tag vocabulary), skills.md (the live skill registry), glossary.md, people.md, and more.
Folder system (PARA)	repo root	00-inbox (unsorted captures) → 10-projects (time-bounded work) → 20-areas (ongoing responsibilities) → 30-resources (reference) → 40-archive (done; excluded from search). Plus 50-daily/ (daily notes + reviews) and 55-goals/ (strategic goals only).
Skills (13)	.claude/skills/	Slash commands: /setup, /daily, /daily-catchup, /weekly, /capture-note, /capture-task, /project, /project-scaffold, /workspace, /audit, /audit-extreme, /council, /dream. The canonical, always-current list is _meta/skills.md.
The agent council (14)	.claude/agents/	A read-only panel — architect, skeptic, pragmatist, first-principles, pre-mortem, north-star, and more — that /council convenes to stress-test a genuine judgment call in a blind→adversarial debate, then writes a dissent-preserving verdict. Inert until /council calls them.
Hooks	.claude/hooks/	Live validators: a note-lint on every Write/Edit (frontmatter + wikilink hygiene) and a session-start status briefing. Fail soft when Python is absent.
Authoring conventions	CLAUDE.md + templates/	Every note gets YAML frontmatter (type / date / status / tags); internal references use [[wikilinks]], never markdown links; search before creating; cite sources.

Want a knowledge-graph "Connections" feed in your nightly brief? Add the optional /graphify skill — /dream reads its output if present and degrades gracefully when it's absent.

---

License

MIT.