{"id":50928021,"url":"https://github.com/baymac/pbrain","last_synced_at":"2026-06-17T01:04:28.144Z","repository":{"id":360746897,"uuid":"1244541444","full_name":"baymac/pbrain","owner":"baymac","description":"Life Maxxing inside your coding agent","archived":false,"fork":false,"pushed_at":"2026-06-11T20:57:27.000Z","size":12789,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T22:21:05.775Z","etag":null,"topics":["claude-code","codex","productivity","skills"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/baymac.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T11:11:15.000Z","updated_at":"2026-06-10T07:03:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/baymac/pbrain","commit_stats":null,"previous_names":["baymac/pbrain"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/baymac/pbrain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baymac%2Fpbrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baymac%2Fpbrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baymac%2Fpbrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baymac%2Fpbrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/baymac","download_url":"https://codeload.github.com/baymac/pbrain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baymac%2Fpbrain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34429501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex","productivity","skills"],"created_at":"2026-06-17T01:04:22.177Z","updated_at":"2026-06-17T01:04:28.079Z","avatar_url":"https://github.com/baymac.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pbrain\n\n\u003e **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.\n\n## Demo\n\n\u003cimg src=\"docs/media/pbrain-promo.gif\" alt=\"pbrain demo — a daily ritual in your terminal\" width=\"100%\"\u003e\n\n\u003c!-- GIF autoplays inline on GitHub. mp4 link above for HD+audio. Source composition: promo-video/ (HyperFrames). --\u003e\n\n**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.\n\n**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](#codex-interoperability)). Linux, Windows, and Android aren't supported.\n\nThe 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.\n\n---\n\n## Architecture\n\n![pbrain architecture](docs/diagrams/architecture.svg)\n\n\u003c!-- Source: docs/diagrams/architecture.d2 — re-render with:\n     d2 --theme 0 --dark-theme 200 --pad 20 docs/diagrams/architecture.d2 docs/diagrams/architecture.svg --\u003e\n\nThe flow:\n\n- **Obsidian (Mac + iOS)** — where you write — syncs the **vault/** (a standalone git repo) across devices over iCloud.\n- 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/`).\n- 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).\n- **Claude Code** and **Claude Desktop** both reach that index over MCP (stdio).\n\n---\n\n## Quick start\n\nThe stack is three independent layers — pick what you need.\n\n### Minimal: plugin + vault (everyone starts here)\n\n```bash\n# 1. Install the plugin — two steps (register the marketplace, then install)\n/plugin marketplace add baymac/pbrain\n/plugin install pbrain@pbrain\n#    If either step fails, use the Local development path below — same\n#    commands, just symlinked from a local clone.\n\n# 2. Bootstrap a vault — checks for Obsidian, creates the vault,\n#    optionally migrates it to iCloud for mobile sync, sets up a private\n#    notes dir, writes config. Idempotent.\n/init-obsidian\n\n# 3. Start using it\n/journal              # morning anchor — raw dump first, clears the head\n/gratitude-journal    # then gratitude, on cleared ground (second)\n/brainstorm \"idea\"    # quick idea dump\n/plan-my-day          # goal-anchored daily planner (first run sets up your goals)\n```\n\nThat's it for the core experience. `/init-obsidian` writes `~/.config/pbrain/vault` so every other command knows where to write.\n\n### What `/init-obsidian` does\n\nFirst-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.\n\n![/init-obsidian flow](docs/diagrams/init-obsidian.svg)\n\n\u003c!-- Source: docs/diagrams/init-obsidian.d2 — re-render with:\n     d2 --theme 0 --dark-theme 200 --pad 20 docs/diagrams/init-obsidian.d2 docs/diagrams/init-obsidian.svg --\u003e\n\nStep by step:\n\n1. **PROBE state** — checks whether Obsidian.app is installed, `~/.config/pbrain/vault` is valid, and the iCloud Obsidian container is present.\n2. **Already configured?** → if yes, report status and exit (or offer the optional add-ons below).\n3. **Obsidian.app missing?** → prompt `brew install --cask obsidian`.\n4. **PICK vault location** — default (`~/Library/Mobile Documents/iCloud~md~obsidian/Documents/vault`) or any custom path.\n5. **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).\n6. **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.\n\n**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`).\n\n**What's written outside the vault:** `~/.config/pbrain/vault` (one-line text file with the vault path).\n\n### Local development\n\nClone 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:\n\n```bash\ngit clone https://github.com/baymac/pbrain.git ~/code/pbrain\n~/code/pbrain/scripts/install-commands.sh\n```\n\nThe 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.\n\nThe 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).\n\n\u003e 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.\n\nRun 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.\n\n#### Troubleshooting\n\nCommands not showing up after running the install script?\n\n1. **Restart Claude Code.** Slash commands are loaded at session start; sessions opened before the symlinks existed won't see them.\n2. **Stale startup cache.** Rare, but if a full restart still doesn't surface them: `rm ~/.claude/.last-cleanup` and restart CC.\n3. **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`.\n\n---\n\n## Vault structure\n\nUser-curated topical folders live at the root. Claude-generated content lives under `agent-work/`.\n\n| Directory | What goes here |\n|---|---|\n| `life/daily-tracking/` | Daily journal entries (created by `/journal`) |\n| `life/`, `fitness/`, `startup/`, `notes/`, etc. | Your hand-curated topical folders (whatever shape you want) |\n| `agent-work/brainstorms/tbd/` | `/brainstorm` outputs (active, default landing). |\n| `agent-work/brainstorms/backlog/` | Parked ideas — not now, not dropped. |\n| `agent-work/brainstorms/done/` | Actioned, shipped, or set aside. |\n| `agent-work/chat-history/` | Chat takeaways saved on request |\n| `agent-work/drafts/` | Drafts written by Claude |\n| `agent-work/notes/` | Misc agent-captured notes |\n| `agent-work/research/` | Web summaries, research outputs |\n| `agent-work/people/` | People pages (auto-enriched or hand-written) |\n\nConcepts, sources, ideas, etc. are **co-located** with their topic — e.g. `startup/\u003cyour-app\u003e/ideas/`, `side-quests/\u003cyour-hobby\u003e/sources/` — not at the vault root.\n\n---\n\n## Slash commands\n\nPackaged as the **pbrain** Claude plugin (manifest at `.claude-plugin/plugin.json`). One short doc per command under [`docs/`](docs/).\n\n| Command | What it does | Default path |\n|---|---|---|\n| `/journal` | Today's daily note | `$VAULT/life/daily-tracking/` |\n| `/gratitude-journal` | Gratitude + reflection (runs after `/journal`) | `$VAULT/life/gratitude-journal/` |\n| `/plan-my-day` | Goal-anchored daily planner | `$VAULT/life/daily-planning/` |\n| `/end-of-day` | Close-of-day completion pass (bookend to `/plan-my-day`) | fills `## How it went` (executive summary + carry-forward) in `$VAULT/life/daily-planning/\u003cdate\u003e.md` (in place) |\n| `/weekly-review` | 7-day synthesis across journal, gratitude, plan, fitness, diet; weekly goals lifecycle | `$VAULT/life/weekly-tracking/YYYY-Www.md` |\n| `/monthly-review` | Month-end synthesis across weekly reviews; monthly goals versioning; plans-profile hygiene pass | `$VAULT/life/monthly-tracking/YYYY-MM.md` |\n| `/brainstorm \u003ctopic\u003e` | New brainstorm file | `$VAULT/agent-work/brainstorms/tbd/` |\n| `/discuss \u003ctopic\u003e` | Personal dilemma discussion — Socratic, one question at a time, saves insight note | `$VAULT/agent-work/notes/` |\n| `/recall \u003ctopic\u003e` | Grep-based search across vault narrative folders | (read-only — prints matches) |\n| `/loose-ends` | Surfaces stale ideas, open questions, todos, deferred seeds, focus drift | (read-only — surfacing dashboard) |\n| `/habits` | Track habits, each with its own criteria (daily / N-per-week / N-per-month, build or cap); day-to-day log in dated `life/habit-tracking/\u003cdate\u003e.md` files (DB synced from them for analysis); progress vs each, top 20 by priority; auto-marked from your journals | `$VAULT/life/Habits Profile.md` + `$VAULT/life/habit-tracking/` + local DB |\n| `/thoughts [\u003ctext\u003e]` | Explode and log a timestamped thought mid-day; on-demand, any time | `$VAULT/life/thought-tracking/` |\n| `/remind \u003ctext\u003e` | Real Apple Reminders (EKReminder) — timed due date, cron-based recurrence, priority, early alarms; create/list/edit/done/cancel. Reminders + iCloud fire and sync. NOT a calendar anchor for `/plan-my-day` | Apple Reminders (no vault file, no DB) |\n| `/remind-blocking \u003ctext\u003e` | Reminders that fire as a full-screen blocking overlay (\"Take a break\"; hold Control to skip / let countdown run for done); cron-flexible schedules, fires via its own background poller. 10s warning panel before the overlay drops; overlay persists across screen lock/unlock (re-appears with countdown adjusted) | local SQLite DB (no vault file) |\n| `/laptop-tracking` | Resident macOS daemon: which app + for how long, and browser DOMAIN (+ per-video YouTube rows), excluding locked/idle/asleep time (a playing video still counts). Background audio/video (music, PiP) tracked separately as `bg_media` — excluded from focus time, shown in its own section. `report` shows the full 00:00→24:00 window for past days, a browser attribution table for unresolved domain time, and per-video YouTube rows. Feeds the **Deep work** scored habit: `focus-breakdown` maps work-block windows → active minutes per category (via an editable domain/app **category map**), scored at `/end-of-day`. `start \\| access \\| status \\| report \\| focus-breakdown \\| categorize \\| stop` | `$VAULT/life/laptop-tracking/YYYY-MM-DD.md` (domain-level; granular DB is local-only, never synced) |\n| `/diet-journal` | Diet log + nutrition analysis + named-food library | `$VAULT/fitness/diet-tracking/` |\n| `/fitness-journal` | Adaptive workout for today | `$VAULT/fitness/daily-tracking/` |\n| `/organize-clippings` | Sort `Clippings/` into the right folders | source: `$VAULT/Clippings/` |\n\n### Daily flow\n\nThe 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.\n\n![pbrain daily flow](docs/diagrams/daily-flow.svg)\n\n\u003c!-- Source: docs/diagrams/daily-flow.d2 — re-render with:\n     d2 --theme 0 --dark-theme 200 --pad 20 docs/diagrams/daily-flow.d2 docs/diagrams/daily-flow.svg --\u003e\n\n| When | Command | What you do |\n|---|---|---|\n| Morning, before anything else | `/journal` | Raw dump first: today's mood, yesterday's residue, random thoughts, whatever's loud. Then answer the open questions it asks. Clears the head. |\n| Right after journaling | `/gratitude-journal` | Just run it — answers the prompts. With the head cleared, gratitude anchors the day to *enough* before agent work starts. |\n| Pre/post workout | `/fitness-journal` | Just run it — it picks today's session based on your activity rotation and asks you to log sets/reps. |\n| With meals (or end of day) | `/diet-journal` | Just run it — log what you ate, get a nutrition + plan-adherence read. Say \"nothing yet\" and it plans the full day from your food library. |\n| Once mind is clear | `/plan-my-day` | Just run it — goal-anchored daily plan. First run sets up your goals; subsequent runs reuse them. |\n| End of day | `/end-of-day` | Just run it — close-of-day reflection. Bookends `/plan-my-day`: what shipped, what slipped, what carries over. |\n\n`/thoughts [\u003ctext\u003e]`, `/brainstorm \u003ctopic\u003e`, `/discuss \u003ctopic\u003e`, `/recall \u003cquery\u003e`, `/loose-ends`, `/weekly-review`, `/monthly-review`, `/habits`, `/remind \u003ctext\u003e`, `/remind-blocking \u003ctext\u003e`, `/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.)\n\n![pbrain on-demand commands](docs/diagrams/on-demand.svg)\n\n\u003c!-- Source: docs/diagrams/on-demand.d2 — re-render with:\n     d2 --theme 0 --dark-theme 200 --pad 20 docs/diagrams/on-demand.d2 docs/diagrams/on-demand.svg --\u003e\n\nEach command's default path is overrideable via env var. Full reference:\n\n| Env var | Used by | Default |\n|---|---|---|\n| `PBRAIN_DEV_DIR` | all commands | — (see Local dev below) |\n| `PBRAIN_VAULT` | all | iCloud Obsidian path |\n| `PBRAIN_SELF_IMPROVE` | all commands (self-improve loop) | `prefs` — also `off` (disable) or `dev` (propose source edits; needs `PBRAIN_DEV_DIR`) |\n| `PBRAIN_PREFS_DIR` | all commands — preferences ROOT (`_global/prefs.md` + per-command `\u003ccmd\u003e/prefs.md`) | `$VAULT/.pbrain` |\n| `PBRAIN_FEEDBACK_DIR` | all commands — quality-fix ROOT (`\u003ccmd\u003e/feedback.md`) | `$VAULT/.pbrain` |\n| `PBRAIN_MIGRATIONS` | all commands — set `0` to disable the vault migration runner | `1` |\n| `PBRAIN_DB_FILE` | `/habits`, `/remind-blocking` (shared SQLite store: habit events + blocking-reminder queue; `/remind` does NOT use the DB) | `~/.config/pbrain/pbrain.db` |\n| `PBRAIN_REMINDERS_LIST` | `/remind` (which Apple Reminders list to create/read in) | unset → system default list |\n| `PBRAIN_REMINDER_MARKER` | `/remind` (hidden notes marker tagging pbrain reminders) | `⟦pbrain-reminder⟧` |\n| `PBRAIN_REMINDERS_APP` | `/remind` (cached build of the EventKit Reminders helper app) | `~/.config/pbrain/pbrain-reminders.app` |\n| `PBRAIN_NOTIFY_APP` | `/remind-blocking` (cached build of pbrain's macOS notifier — the overlay's no-swiftc fallback) | `~/.config/pbrain/pbrain-notify.app` |\n| `PBRAIN_NOTIFY_IDENTITY` | `/remind-blocking` (bundle id the notifier delivers under; `\"\"` = no impersonation) | unset → `com.apple.Terminal` |\n| `PBRAIN_OVERLAY_APP` | `/remind-blocking` (cached build of pbrain's full-screen overlay app) | `~/.config/pbrain/pbrain-overlay.app` |\n| `PBRAIN_OVERLAY_BG` | `/remind-blocking` (default overlay background colour, hex) | unset → slate |\n| `PBRAIN_TRACKER_DB_FILE` | `/laptop-tracking` (its OWN local SQLite DB — segments; never synced to the vault) | `~/.config/pbrain/tracker.db` |\n| `PBRAIN_TRACKER_APP` | `/laptop-tracking` (cached build of the resident tracker daemon app) | `~/.config/pbrain/pbrain-tracker.app` |\n| `PBRAIN_TRACKER_DIR` | `/laptop-tracking` (daily report write dir) | `$VAULT/life/laptop-tracking` |\n| `PBRAIN_TRACKER_POLL` / `PBRAIN_TRACKER_IDLE` | `/laptop-tracking` (daemon poll interval / idle-away threshold, seconds) | `10` / `300` |\n| `PBRAIN_LAPTOP_CATEGORIES_FILE` | `/laptop-tracking` (domain/app → category map behind the *Deep work* focus score) | `$VAULT/life/laptop-tracking/categories.md` |\n| `PBRAIN_THOUGHTS_DIR` | `/thoughts` | `$VAULT/life/thought-tracking` |\n| `PBRAIN_JOURNAL_DIR` | `/journal`, read by `/plan-my-day`, `/loose-ends` | `$VAULT/life/daily-tracking` |\n| `PBRAIN_BRAINSTORMS_DIR` | `/brainstorm`, read by `/loose-ends` | `$VAULT/agent-work/brainstorms` |\n| `PBRAIN_NOTES_DIR` | `/discuss` | `$VAULT/agent-work/notes` |\n| `PBRAIN_DIET_DIR` | `/diet-journal` | `$VAULT/fitness/diet-tracking` |\n| `PBRAIN_DIET_PROFILE_FILE` | `/diet-journal` (explicit file override; bypasses the versioned store) | latest committed `diet-profile.vN.md` in `$VAULT/fitness/diet-tracking/.profile/` |\n| `PBRAIN_FOOD_LIBRARY_FILE` | `/diet-journal` (named-food library — log by name; override) | latest `food-library.vN.md` in the diet store |\n| `PBRAIN_FITNESS_DIR` | `/fitness-journal`, read by `/diet-journal`, `/plan-my-day` | `$VAULT/fitness/daily-tracking` |\n| `PBRAIN_GYM_PLAN_FILE` / `PBRAIN_FITNESS_PLANS_DIR` / `PBRAIN_FITNESS_ACTIVITIES_FILE` | legacy paths — read only by the one-time fitness migration (0003) | — |\n| `PBRAIN_GRATITUDE_DIR` | `/gratitude-journal` | `$VAULT/life/gratitude-journal` |\n| `PBRAIN_PLAN_DIR` | `/plan-my-day`, `/end-of-day`, `/weekly-review`, `/loose-ends` | `$VAULT/life/daily-planning` |\n| `PBRAIN_PLAN_PROFILE_FILE` | `/plan-my-day`, read by `/loose-ends`, `/discuss`, `/weekly-review` (explicit override) | latest committed `plans-profile.vN.md` in `$VAULT/life/daily-planning/.profile/` |\n| `PBRAIN_HABITS_PROFILE_FILE` | `/habits`, read by `/plan-my-day`, `/end-of-day`, `/weekly-review` (explicit override) | latest committed `habits-profile.vN.md` in `$VAULT/life/habit-tracking/.profile/` |\n| `PBRAIN_HABIT_TRACK_DIR` | `/habits` (dated tracking files), synced→DB by `/plan-my-day`, `/end-of-day`, `/weekly-review` | `$VAULT/life/habit-tracking/` |\n| `PBRAIN_HABIT_SUGGEST_FILE` | `/habits` + journaling commands (new-habit nudge suppress-list) | `~/.config/pbrain/habit-suggest-seen` |\n| `PBRAIN_HABIT_SUGGEST_TTL_DAYS` | `/habits` + journaling commands | `14` (days a suggested habit stays suppressed) |\n| `PBRAIN_WEEKLY_DIR` | `/weekly-review` | `$VAULT/life/weekly-tracking` |\n| `PBRAIN_MONTHLY_DIR` | `/monthly-review` | `$VAULT/life/monthly-tracking` |\n| `PBRAIN_RECALL_SCOPE` | `/recall` | `life agent-work startup side-quests software-dev notes` (space-separated subdirs relative to vault) |\n| `PBRAIN_STALE_DAYS` | `/loose-ends` | `7` (age at which an item counts as stale) |\n| `PBRAIN_LOOSE_ENDS_LOOKBACK` | `/loose-ends` | `30` (days of journals/plans to scan) |\n| `PBRAIN_CLIPPINGS_DIR` | `/organize-clippings` | `$VAULT/Clippings` |\n| `PBRAIN_CLIPPINGS_TARGETS` | `/organize-clippings` | (interactive prompt — set to `all` or a comma-separated subset to skip it) |\n| `CODEX_HOME` | `/codex-install` | Codex home dir to install skills + AGENTS.md into (default `~/.codex`) |\n\n\nThe vault root is resolved via `PBRAIN_VAULT` → `~/.config/pbrain/vault` → default iCloud path, in that order.\n\n---\n\n## Codex interoperability\n\npbrain 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`**:\n\n```bash\n/init-obsidian            # set up the vault (Claude Code)\n/codex-install            # wire pbrain into Codex   (Claude Code)\n```\n\nIt generates, under `$CODEX_HOME` (default `~/.codex`):\n\n- `skills/pbrain-\u003ccommand\u003e/SKILL.md` — one Codex **agent skill** per pbrain command, each a thin wrapper that runs the *same* `commands/\u003ccommand\u003e.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.)\n- 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.\n\n\u003e Don't type `/journal` in Codex — its CLI rejects unknown `/slash` commands before the model sees them. Invoke pbrain by plain name.\n\n**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).\n\n**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):\n\n```bash\ncodex --sandbox workspace-write --add-dir \"/path/to/your/vault\" --add-dir \"$HOME/.config/pbrain\"\n```\n\nFull details: [`docs/codex-install.md`](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.)\n\n---\n\n## Private notes\n\nIf 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.\n\n---\n\n## Optional: gbrain (AI search over the vault) — 🚧 not working, fix coming in a future release\n\ngbrain 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.**\n\n\u003e 🚧 **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`](gbrain/docs/gbrain-sync.md) · upstream repro: [`gbrain/docs/gbrain-bug-report.md`](gbrain/docs/gbrain-bug-report.md).\n\n```bash\nbrew install ollama \u0026\u0026 brew services start ollama \u0026\u0026 ollama pull nomic-embed-text\ngit clone https://github.com/garrytan/gbrain.git ~/code/gbrain\ncd ~/code/gbrain \u0026\u0026 bun install \u0026\u0026 bun link\ncd \"$(cat ~/.config/pbrain/vault)\" \u0026\u0026 gbrain init --pglite --embedding-model ollama:nomic-embed-text --embedding-dimensions 768\ngbrain config set embedding_model ollama:nomic-embed-text\ngbrain sync --repo . --skip-failed\nclaude mcp add gbrain \"$HOME/.bun/bin/gbrain\" serve\n# Optional (currently degraded — see note above):\n# ./gbrain/scripts/install-launchd.sh\n```\n\nFull setup: [`gbrain/docs/setup.md`](gbrain/docs/setup.md). What gbrain unlocks beyond search: [`gbrain/docs/gbrain-beyond-notes.md`](gbrain/docs/gbrain-beyond-notes.md).\n\n---\n\n## Repository structure\n\nThe 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.\n\n```\npbrain/\n├── .claude-plugin/\n│   └── plugin.json                     ← Claude plugin manifest\n├── commands/                           ← .md + .sh pairs for each slash command\n├── lib/\n│   ├── vault.sh                        ← shared VAULT_DIR resolver + entry point for helpers\n│   ├── update-check.sh                 ← upgrade nudge (sourced by vault.sh)\n│   ├── prefs.sh                        ← per-command preference injection\n│   ├── self-improve.sh                 ← end-of-session feedback capture\n│   ├── profile.sh                      ← plans-profile JSON extractor\n│   ├── db.sh                           ← shared SQLite store (habit events + reminders)\n│   ├── habits.sh                       ← habits profile/criteria + dated tracking layer\n│   ├── habit_schedule.py               ← habit schedule engine (is_due, derive_schedule, spacing helpers)\n│   ├── profiles.sh                     ← versioned profile store (.profile dirs: latest/new/commit)\n│   ├── migrations.sh + migrations/     ← vault migration runner + ordered migration scripts\n│   ├── profile_lock.py                 ← atomic read-modify-write for Habits Profile.md (flock + tempfile-rename)\n│   ├── launchd.sh                      ← shared native-helper build + LaunchAgent helpers (pbrain_swift_build, pbrain_launchagent_install)\n│   ├── reminders.sh                    ← Apple Reminders helpers + cron→recurrence mapper (/remind); blocking overlay/tick/cron (/remind-blocking); Calendar read for plan-my-day\n│   ├── pbrain-reminders.swift          ← source for the EventKit Reminders helper app (/remind)\n│   ├── pbrain-notify.swift             ← source for pbrain's macOS notifier app\n│   ├── pbrain-overlay.swift            ← source for pbrain's full-screen blocking overlay app (warning panel + lock-persist)\n│   └── pbrain-tracker.swift            ← source for the laptop-tracking daemon (foreground + bg_media tracking)\n├── scripts/\n│   ├── install-commands.sh             ← symlink commands into ~/.claude/commands/\n│   └── uninstall-commands.sh           ← reverse of install\n├── tests/                              ← bats test suite for lib/ helpers\n├── docs/                               ← one short doc per command (user-facing)\n├── gbrain/                             ← gbrain ops (sync, launchd, docs)\n│   ├── scripts/\n│   │   ├── install-launchd.sh          ← render plist + load launchd\n│   │   ├── gbrain-sync-wrapper.sh      ← wraps sync with lockfile + JSONL log\n│   │   ├── gbrain-dashboard.sh         ← stuck procs, sync stats, brain stats\n│   │   └── gbrain-upgrade.sh           ← bun-link based upgrade flow\n│   ├── launchd/\n│   │   └── com.pbrain.sync.plist.template\n│   ├── docs/\n│   │   ├── setup.md                    ← gbrain-only setup (Ollama, init, MCP, launchd)\n│   │   ├── gbrain-sync.md              ← sync architecture + lock model\n│   │   ├── gbrain-beyond-notes.md      ← capabilities beyond search\n│   │   └── gbrain-bug-report.md        ← upstream bug repro\n│   └── .logs/                          ← gitignored: sync-runs.jsonl, upgrade-status.json\n├── promo-video/                        ← HyperFrames source composition for the promo video (renders excluded via .gitignore)\n├── CLAUDE.md\n└── README.md\n```\n\nThe vault is a **separate** git repo (or just a directory). Not a submodule of this repo.\n\n---\n\n## Pairs well with\n\n[**Claudian**](https://github.com/YishenTu/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.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## What not to do\n\n- Don't write notes in this outer repo — use the vault\n- Don't bypass the global `~/.claude/commands` symlink with per-vault copies — edit `commands/` here and every session picks up the change.\n- Don't put gbrain scripts inside `commands/` or `lib/` (or pbrain scripts inside `gbrain/`). Plugin = slash commands. Gbrain ops = `gbrain/`.\n- Don't `bun install -g github:garrytan/gbrain` — broken postinstall hook; clone and link manually (see `gbrain/docs/setup.md`)\n- Don't init gbrain at the pbrain root — it'll index your scripts as notes. Always init from inside the vault.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaymac%2Fpbrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaymac%2Fpbrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaymac%2Fpbrain/lists"}