Daily-ritual scaffolding for Obsidian + Claude Code. Local-first slash commands for journaling, gratitude, fitness, diet, daily planning, brainstorming, and clipping triage. macOS only. Your vault stays on your machine — no accounts, no servers, no telemetry.

Obsidian is the writing surface. A markdown vault is the corpus (iCloud-synced or plain local — your choice). pbrain slash commands handle the rituals. Optionally, gbrain adds an AI memory layer exposed to Claude via MCP.

Compatibility: macOS only (Obsidian Desktop + iCloud Drive container). iOS works for read/write through the synced vault on iPhone/iPad, but the slash commands themselves run from Claude Code on macOS (or the OpenAI Codex CLI — see Codex interoperability). Linux, Windows, and Android aren't supported.

The pbrain slash commands work against any vault directory you point them at — PBRAIN_VAULT env var, a path written to ~/.config/pbrain/vault, or the default iCloud Obsidian path. /init-obsidian handles the setup.

The flow:

• Obsidian (Mac + iOS) — where you write — syncs the vault/ (a standalone git repo) across devices over iCloud.
• The vault holds life/ (daily journal), domain folders (fitness/, startup/, side-quests/, software-dev/, …), and agent-work/ (everything Claude generates — brainstorms/, chat-history/, drafts/, notes/, research/, people/).
• A launchd job runs gbrain sync every 30 min, indexing the vault into a local gbrain index (PGLite + Ollama embeddings, ~/.gbrain/ — local-only, free, private).
• Claude Code and Claude Desktop both reach that index over MCP (stdio).

The stack is three independent layers — pick what you need.

# 1. Install the plugin — two steps (register the marketplace, then install)
/plugin marketplace add baymac/pbrain
/plugin install pbrain@pbrain
#    If either step fails, use the Local development path below — same
#    commands, just symlinked from a local clone.

# 2. Bootstrap a vault — checks for Obsidian, creates the vault,
#    optionally migrates it to iCloud for mobile sync, sets up a private
#    notes dir, writes config. Idempotent.
/init-obsidian

# 3. Start using it
/journal              # morning anchor — raw dump first, clears the head
/gratitude-journal    # then gratitude, on cleared ground (second)
/brainstorm "idea"    # quick idea dump
/plan-my-day          # goal-anchored daily planner (first run sets up your goals)

That's it for the core experience. /init-obsidian writes ~/.config/pbrain/vault so every other command knows where to write.

First-run setup — you only need it once. Every other command reads ~/.config/pbrain/vault and just works after this is done. Re-running is safe (idempotent) but only useful if you're switching vault locations, adding a git remote later, or adding the private dir after the fact.

Step by step:

1. PROBE state — checks whether Obsidian.app is installed, ~/.config/pbrain/vault is valid, and the iCloud Obsidian container is present.
2. Already configured? → if yes, report status and exit (or offer the optional add-ons below).
3. Obsidian.app missing? → prompt brew install --cask obsidian.
4. PICK vault location — default (~/Library/Mobile Documents/iCloud~md~obsidian/Documents/vault) or any custom path.
5. BOOTSTRAP (idempotent — re-running on an existing vault leaves it alone): mkdir the vault dir, git init, write vault/.gitignore (.gbrain/, .DS_Store, private.nosync/), write vault/CLAUDE.md (project-level CC instructions for sessions opened inside the vault — not slash commands, those live in ~/.claude/commands), initial commit, then write ~/.config/pbrain/vault (the pointer every other command reads).
6. Optional add-ons (asked one-by-one): MIGRATE from an existing vault (rsync old → new, verify file count, source preserved for manual delete); SET UP vault/private.nosync/ for off-iCloud / off-git notes; ADD a git remote + push.

What's written inside the vault: vault/.gitignore, vault/CLAUDE.md, optionally vault/private.nosync/README.md. That's it. Slash commands are never installed into the vault — they live in ~/.claude/commands (via /plugin install or scripts/install-commands.sh).

What's written outside the vault: ~/.config/pbrain/vault (one-line text file with the vault path).

Clone the repo and run the install script — it symlinks each command into ~/.claude/commands/ individually, so every CC session anywhere picks them up with no re-install, and any non-pbrain commands you already have there are preserved:

git clone https://github.com/baymac/pbrain.git ~/code/pbrain
~/code/pbrain/scripts/install-commands.sh

The script is idempotent — re-run it after git pull if new commands land. If you previously symlinked the whole commands/ directory, the script detects that and replaces it with per-file links.

The install script also makes live edits to .sh scripts take effect immediately: it registers your clone as PBRAIN_DEV_DIR in ~/.claude/settings.json, so the command wrappers always execute from your live repo instead of the marketplace snapshot. Restart Claude Code / Conductor once after the first install for the env change to load. scripts/uninstall-commands.sh removes that entry again (only if it still points at this clone).

Prefer settings.json over a ~/.zshrc export here: GUI-launched apps (Conductor, the desktop app) don't source ~/.zshrc, so a shell-profile export is invisible to them — the wrappers fall back to the stale marketplace snapshot and your edits don't run. The settings.json env block is read regardless of how the app was launched. The install script writes it for you, but if you set it by hand, put it there.

Run pbrain commands from any directory — your current project, a Conductor workspace, the tooling repo, wherever you are. The vault path is resolved from your config ($PBRAIN_VAULT → ~/.config/pbrain/vault → iCloud default), never from cwd. Notes always land in the right place.

Commands not showing up after running the install script?

1. Restart Claude Code. Slash commands are loaded at session start; sessions opened before the symlinks existed won't see them.
2. Stale startup cache. Rare, but if a full restart still doesn't surface them: rm ~/.claude/.last-cleanup and restart CC.
3. Broken symlinks. If you deleted or moved the cloned repo, the per-file symlinks under ~/.claude/commands/ will be dangling. Re-clone and re-run scripts/install-commands.sh.

User-curated topical folders live at the root. Claude-generated content lives under agent-work/.

Concepts, sources, ideas, etc. are co-located with their topic — e.g. startup/<your-app>/ideas/, side-quests/<your-hobby>/sources/ — not at the vault root.

Packaged as the pbrain Claude plugin (manifest at .claude-plugin/plugin.json). One short doc per command under docs/.

The commands compose into a full-day ritual. Run them top-to-bottom — most are zero-input, just type the slash command and answer the prompts.

/thoughts [<text>], /brainstorm <topic>, /discuss <topic>, /recall <query>, /loose-ends, /weekly-review, /monthly-review, /habits, /remind <text>, /remind-blocking <text>, /laptop-tracking, and /organize-clippings are on-demand — not part of the daily loop. Pull them in when needed. (/habits also surfaces automatically inside /plan-my-day and /end-of-day, and habits get logged from your journaling sessions without you asking. /remind lives in Apple Reminders and does not surface there.)

Each command's default path is overrideable via env var. Full reference:

The vault root is resolved via PBRAIN_VAULT → ~/.config/pbrain/vault → default iCloud path, in that order.

pbrain is primarily a Claude Code plugin, but the same commands can run from the OpenAI Codex CLI — useful if you (or someone you share with) live in Codex. Run /codex-install from Claude Code, once, after /init-obsidian:

/init-obsidian            # set up the vault (Claude Code)
/codex-install            # wire pbrain into Codex   (Claude Code)

It generates, under $CODEX_HOME (default ~/.codex):

• skills/pbrain-<command>/SKILL.md — one Codex agent skill per pbrain command, each a thin wrapper that runs the same commands/<command>.sh. Codex discovers them automatically; invoke by plain name (journal, plan my day, brainstorm should I build X), explicitly as $pbrain-journal, or just describe the task and let Codex auto-select. (init-obsidian and the installer itself stay Claude-only.)
• a managed, clearly-delimited pbrain block in AGENTS.md with the cross-command behaviour Codex needs (how to invoke, morning sequence, ride-along blocks, vault write rules, launch command) — scoped so it won't affect unrelated Codex sessions.

Don't type /journal in Codex — its CLI rejects unknown /slash commands before the model sees them. Invoke pbrain by plain name.

One source of truth, no conflicts. The skills reimplement nothing — they run the same shell scripts and resolve the same vault + ~/.config/pbrain config + SQLite DB at runtime. Alternating between Codex and Claude Code on the same machine can't get out of sync. Re-run /codex-install after moving/reinstalling pbrain or when new commands ship (idempotent; prunes only its own stale skills, never yours).

Launching Codex so pbrain can write to the vault and config without per-write approval: the installer writes a codex-pbrain shell function to your RC file — source ~/.zshrc, then just run codex-pbrain. Equivalent manual launch (the installer prints it with your real vault path):

codex --sandbox workspace-write --add-dir "/path/to/your/vault" --add-dir "$HOME/.config/pbrain"

Full details: docs/codex-install.md. (pbrain originally used Codex custom prompts; those are now deprecated and were undiscoverable on recent Codex builds, so it moved to agent skills — the supported, default-on mechanism. Re-running /codex-install migrates you automatically.)

If you went with the iCloud-synced vault, you can keep notes off git and off iCloud using the .nosync suffix convention. /init-obsidian offers to set up vault/private.nosync/ automatically.

gbrain adds hybrid vector + keyword search and exposes it to Claude via MCP — so Claude can recall what you wrote weeks ago. Not required for any of the commands above.

🚧 Currently broken. A recent upstream schema migration causes the scheduled launchd sync to hang. The brain only stays fresh while Claude is open (MCP writes go through gbrain serve in-process); scheduled background sync is disabled by default. Skip this section for now — everything else in pbrain works without it. Will be fixed in a future release. Details: gbrain/docs/gbrain-sync.md · upstream repro: gbrain/docs/gbrain-bug-report.md.

brew install ollama && brew services start ollama && ollama pull nomic-embed-text
git clone https://github.com/garrytan/gbrain.git ~/code/gbrain
cd ~/code/gbrain && bun install && bun link
cd "$(cat ~/.config/pbrain/vault)" && gbrain init --pglite --embedding-model ollama:nomic-embed-text --embedding-dimensions 768
gbrain config set embedding_model ollama:nomic-embed-text
gbrain sync --repo . --skip-failed
claude mcp add gbrain "$HOME/.bun/bin/gbrain" serve
# Optional (currently degraded — see note above):
# ./gbrain/scripts/install-launchd.sh

Full setup: gbrain/docs/setup.md. What gbrain unlocks beyond search: gbrain/docs/gbrain-beyond-notes.md.

The repo is the plugin — a single-plugin Claude marketplace would just nest the same files under plugins/pbrain/ for no gain. gbrain/ stays separate because it's not part of the plugin distribution; it's local sync glue.

pbrain/
├── .claude-plugin/
│   └── plugin.json                     ← Claude plugin manifest
├── commands/                           ← .md + .sh pairs for each slash command
├── lib/
│   ├── vault.sh                        ← shared VAULT_DIR resolver + entry point for helpers
│   ├── update-check.sh                 ← upgrade nudge (sourced by vault.sh)
│   ├── prefs.sh                        ← per-command preference injection
│   ├── self-improve.sh                 ← end-of-session feedback capture
│   ├── profile.sh                      ← plans-profile JSON extractor
│   ├── db.sh                           ← shared SQLite store (habit events + reminders)
│   ├── habits.sh                       ← habits profile/criteria + dated tracking layer
│   ├── habit_schedule.py               ← habit schedule engine (is_due, derive_schedule, spacing helpers)
│   ├── profiles.sh                     ← versioned profile store (.profile dirs: latest/new/commit)
│   ├── migrations.sh + migrations/     ← vault migration runner + ordered migration scripts
│   ├── profile_lock.py                 ← atomic read-modify-write for Habits Profile.md (flock + tempfile-rename)
│   ├── launchd.sh                      ← shared native-helper build + LaunchAgent helpers (pbrain_swift_build, pbrain_launchagent_install)
│   ├── reminders.sh                    ← Apple Reminders helpers + cron→recurrence mapper (/remind); blocking overlay/tick/cron (/remind-blocking); Calendar read for plan-my-day
│   ├── pbrain-reminders.swift          ← source for the EventKit Reminders helper app (/remind)
│   ├── pbrain-notify.swift             ← source for pbrain's macOS notifier app
│   ├── pbrain-overlay.swift            ← source for pbrain's full-screen blocking overlay app (warning panel + lock-persist)
│   └── pbrain-tracker.swift            ← source for the laptop-tracking daemon (foreground + bg_media tracking)
├── scripts/
│   ├── install-commands.sh             ← symlink commands into ~/.claude/commands/
│   └── uninstall-commands.sh           ← reverse of install
├── tests/                              ← bats test suite for lib/ helpers
├── docs/                               ← one short doc per command (user-facing)
├── gbrain/                             ← gbrain ops (sync, launchd, docs)
│   ├── scripts/
│   │   ├── install-launchd.sh          ← render plist + load launchd
│   │   ├── gbrain-sync-wrapper.sh      ← wraps sync with lockfile + JSONL log
│   │   ├── gbrain-dashboard.sh         ← stuck procs, sync stats, brain stats
│   │   └── gbrain-upgrade.sh           ← bun-link based upgrade flow
│   ├── launchd/
│   │   └── com.pbrain.sync.plist.template
│   ├── docs/
│   │   ├── setup.md                    ← gbrain-only setup (Ollama, init, MCP, launchd)
│   │   ├── gbrain-sync.md              ← sync architecture + lock model
│   │   ├── gbrain-beyond-notes.md      ← capabilities beyond search
│   │   └── gbrain-bug-report.md        ← upstream bug repro
│   └── .logs/                          ← gitignored: sync-runs.jsonl, upgrade-status.json
├── promo-video/                        ← HyperFrames source composition for the promo video (renders excluded via .gitignore)
├── CLAUDE.md
└── README.md

The vault is a separate git repo (or just a directory). Not a submodule of this repo.

Claudian — an Obsidian plugin that runs Claude Code inside Obsidian, with word-level diff previews, vault-wide search, and three safety modes (Safe / Plan / YOLO). pbrain pushes structured notes into the vault from Claude Code on the terminal; Claudian lets Claude read, edit, and connect notes inside the Obsidian UI itself. The two are complementary — install both and you can write a /journal entry from the terminal, then ask Claude to enrich and backlink it inside Obsidian without leaving the editor.

MIT — see LICENSE.

• Don't write notes in this outer repo — use the vault
• Don't bypass the global ~/.claude/commands symlink with per-vault copies — edit commands/ here and every session picks up the change.
• Don't put gbrain scripts inside commands/ or lib/ (or pbrain scripts inside gbrain/). Plugin = slash commands. Gbrain ops = gbrain/.
• Don't bun install -g github:garrytan/gbrain — broken postinstall hook; clone and link manually (see gbrain/docs/setup.md)
• Don't init gbrain at the pbrain root — it'll index your scripts as notes. Always init from inside the vault.