Claude Code's second brain — turns your Claude Code sessions into a living, searchable knowledge system backed by an Obsidian vault.
Braynee is a Claude Code plugin that scaffolds a PARA vault, wires up your company knowledge base, detects your environment, installs the right Obsidian plugins, and keeps everything in sync session to session.
Requires Claude Code ≥ 2.1.128. Braynee's hooks deliberately do not use the
iffield — it proved version-unreliable (on CC 2.1.143 anif-gated hook never fires at all), so every hook registers on its event and self-gates in JavaScript instead. Every hook also declares an explicit timeout, so a slow one degrades instead of stalling your turn.≥ 2.1.214 recommended: a hook exiting 2 blocks reliably even when its stdout JSON fails schema validation (Braynee's deny hooks depend on that), and since 2.1.210 a hook timeout is no longer misreported to the model as a user rejection.
Marketplace (recommended):
claude plugin marketplace add hamchowderr/braynee
claude plugin install braynee@brayneeDirect from a release URL (no marketplace) — requires Claude Code ≥ v2.1.128 for zip/URL plugin loading:
claude --plugin-url https://github.com/hamchowderr/braynee/releases/download/braynee--v<version>/braynee.zipEvery braynee--v<version> GitHub Release ships a braynee.zip asset, built automatically when the tag is pushed (claude plugin tag . → git push origin braynee--v<version>). Pin the tag to the version you want.
Braynee creates an org-aware vault structure under 2. Areas/Business/. Each business gets a folder with:
Clients/— per-client notes, engagement logs, call prepOrg/— Decisions, Strategy, Competitors, Pipeline, RisksOperations/— Consulting, Education, Marketing, FulfillmentShipped/— live products still being maintained
You provide your company name and email domain during setup; braynee seeds the structure and names everything correctly from the start.
Braynee auto-detects your installed mail client:
- ProtonMail (Bridge or app)
- Gmail (browser profile or native app)
- Apple Mail (macOS)
- Outlook
Email context is stored in your knowledge base and surfaced during daily planning and client call prep.
Braynee detects your calendar platform and wires it into daily notes:
- Google Calendar
- Apple Calendar (macOS)
- Outlook Calendar
scan-projects.py scans every common projects-root folder name (code, projects, dev, Developer, repos, src, workspace, work, Sites, source, plus Windows-specific paths like source/repos, Documents/GitHub), finds git repos, detects the stack (Next.js, Convex, FastAPI, etc.), and writes a project map. The wizard surfaces these to Claude so it knows what you're building without you having to explain it.
Braynee declares its hooks in the plugin's hooks/hooks.json — they run automatically when the plugin is active, with nothing written into ~/.claude/settings.json. 37 hooks across 15 Claude Code events keep the vault, sessions, beads, and tasks in sync:
| Event | Hooks | What they do |
|---|---|---|
| SessionStart | ensure-obsidian.js, reinject-after-compact.js, session-auto-track.js, braynee-heartbeat.js, check-beads-init.js, beads-work-surface.js, check-git-init.js, check-testing-setup.js |
Launch Obsidian, open/update the session note, write the heartbeat, ensure beads + git are initialized, surface the ready beads queue, flag a missing test stack, and re-inject vault context after a compaction |
| UserPromptSubmit | memory-reminder.js, beads-nudge.js |
Remind Claude to search vault memory before guessing and to keep the beads workflow current |
| PreToolUse | check-no-main-push.js, branch-name-check.js |
Protect main/master: block pushing to it, committing on it, or --orphan-ing onto it (opt out with BRAYNEE_ALLOW_MAIN_COMMITS=1), and enforce branch naming |
| PostToolUse | memory-index-sync.js, plan-capture.js, session-note-nudge.js, statusline-state.js, commit-cadence-nudge.js, beads-claim-to-branch.js, beads-status-sync.js, beads-todo-reminder.js, beads-dashboard-refresh.js, mtn-to-beads-sync.js |
Keep MEMORY.md indexed, capture approved plans, nudge session-note updates and commit cadence, branch on bd … --claim, and mirror beads ⇄ Claude todos ⇄ TaskNotes |
| PostToolBatch | beads-batch-reconcile.js |
Reconcile beads state after batched tool calls |
| PreCompact | pre-compact-snapshot.js |
Snapshot context before a compaction |
| PostCompact | post-compact.js |
Restore and re-inject context after a compaction |
| Stop | session-auto-close.js, session-export-qmd.js, session-stop-check.js, beads-stop-check.js, stop-task-verify.js |
Close the session, export the transcript and refresh the QMD index, and run the session-close / beads / task checklists |
| StopFailure | stop-failure.js |
Detect a Stop that didn't produce a clean wrap |
| SessionEnd | session-end.js |
Finalize the session note and clean up |
| ConfigChange | config-change-resurface.js |
Resurface relevant context after a Claude Code config change |
| CwdChanged | cwd-changed-check.js |
Re-evaluate project context when the working directory changes |
| FileChanged | memory-file-changed.js |
Re-index MEMORY.md when it's edited externally |
| TaskCreated | task-created-check.js |
Validate newly created tasks |
| TaskCompleted | task-completed-check.js |
Verify completed tasks |
Hooks that have stateful side effects detect existing equivalents and never duplicate them.
install-obsidian-plugins.py installs and configures the following plugins into your vault:
- Dataview — query your vault like a database
- TaskNotes — one-file-per-task management, used as the vault-side mirror of beads issues
- Templater — powerful templating for notes and daily pages
- Calendar — daily note calendar navigation
- Obsidian Git — vault backup and version history
- Excalidraw — sketch + diagram drawings stored in the vault
The full scaffold (top-level PARA + the 2. Areas subfolders Braynee uses):
Inbox/ → captures and incubating ideas
1. Projects/ → active codebases (one file per project)
2. Areas/
├── Business/<YourBusiness>/ → Org, Teams, Projects, Clients, Operations, Shipped
├── Product Manager/ → PRDs, Roadmaps, Research, Launches, Metrics
├── Development/ → framework reference (auto-populated by stack)
├── Sessions/ → one note per Claude Code working session
├── TaskNotes/Tasks/ → vault-side mirror of beads issues
├── Claude Memory/ → persistent agent memory (MEMORY.md + files)
└── Excalidraw/ → drawings
3. Resources/ → reference material, Templates/
4. Archives/ → completed and retired work
Zettelkasten/ → atomic permanent notes
| Skill | Command | What it does |
|---|---|---|
setup |
/setup |
Onboarding wizard — runs the full install or audits an existing vault and shows only what's missing |
daily |
/daily |
Open today's note, log what you're working on, and run an EOD summary |
recap |
/recap |
Load context from previous sessions — temporal, topic (QMD BM25 + semantic), and graph modes |
query |
/query |
Search the vault — keyword (BM25), semantic, and deep research modes |
sessions |
/sessions |
Export Claude Code sessions to Obsidian markdown, list, and annotate |
session-backfill |
/session-backfill |
Backfill structured summaries for historical sessions via claude -p |
prd |
/prd |
Author and audit PRDs under 2. Areas/Product Manager/PRDs/; seed beads issues from acceptance criteria |
clients |
/clients |
Client relationship management — context, engagement logs, call prep |
zettelkasten |
/zettelkasten |
Create, find, and link atomic notes — permanent knowledge distillation |
excalidraw |
/excalidraw |
Create Excalidraw diagrams natively in Obsidian for any workflow, architecture, or codebase walkthrough |
insightful |
/insightful |
Generate a comprehensive HTML report from your complete Claude Code session history |
health |
/health |
System health check — Four Cs audit (Context, Connections, Capabilities, Cadence) |
# From the Claude Code marketplace
/plugin install braynee@braynee
# Or locally (from a cloned braynee checkout)
/plugin install .After installing, run /setup to launch the wizard.
If you already have an Obsidian vault, /setup detects it and runs a non-destructive audit. It shows only what's missing — no duplicate folders created, no existing notes overwritten, no hooks added if you already have equivalent ones.
Braynee installs QMD (a local BM25 + semantic search engine) and keeps its index fresh via the session-export-qmd.js Stop hook. All braynee skills use QMD for vault search — never grep or filesystem scanning.
node ${CLAUDE_PLUGIN_ROOT}/scripts/qmd-wrapper.mjs search "query" # exact terms
node ${CLAUDE_PLUGIN_ROOT}/scripts/qmd-wrapper.mjs vsearch "query" # semantic
node ${CLAUDE_PLUGIN_ROOT}/scripts/qmd-wrapper.mjs query "query" # deep researchOpinionated guides on how the author builds. Recommendations, not requirements — adapt or replace freely.
- Project lifecycle — vault → PRD → bd → code → ship
- PRD authoring — schema + acceptance criteria patterns
- Testing stack — Vitest, Supertest, Playwright, AIMock
- Recommended stack — Convex, Mastra, Clerk, Vercel, Coolify, Infisical
- Claude Code CLI
- Node.js 18+
- Python 3.10+
- Git
- A markdown vault — Obsidian is optional (see below)
Braynee is, at its foundation, a folder of markdown + frontmatter in a PARA
layout — beads, QMD search, sessions, recall, PRDs, and every hook read and
write plain files. So it works with any local-markdown PKM: Obsidian, Logseq,
Foam, Dendron, SilverBullet, Zettlr, iA Writer,
Shockwave, or a plain .md folder.
- Point braynee at your vault with
BRAYNEE_VAULT=/path/to/vault— the canonical opt-in for a vault at a non-standard path or a non-Obsidian app. Auto-detection also accepts any folder carrying the PARA skeleton (the numbered1. Projects…4. Archivesfolders), not only ones with a.obsidian/dir. - Obsidian running is not required. When the Obsidian desktop CLI is
present, write-path skills drive the running app for instant refresh; when
it's absent they fall back to direct filesystem writes.
/healthreportsobsidian — CLI: not present (fs-write fallback active)rather than an error. - Obsidian-only rendering: a few artifacts still write fine anywhere but
only render natively in Obsidian — Excalidraw (
.excalidraw), Bases (.base), and some callouts/embeds. Wikilinks ([[…]]) render in Logseq and Foam too.install-obsidian-plugins.pyis Obsidian-specific by nature.
braynee — published under the otaku-solutions namespace.
Don't use claude plugin update for every edit. Launch Claude Code with --plugin-dir pointing at the source:
claude --plugin-dir "/path/to/braynee"The local copy takes precedence over the installed marketplace version for that session. After each edit, run /reload-plugins — no restart needed. It reloads plugins, skills, agents, hooks, MCP, and LSP servers.
Validate the plugin install end-to-end:
node bin/braynee-self-test # human-readable
node bin/braynee-self-test --json # machine-readableOr via the health skill: /braynee:health self-test.
The self-test runs all of these in sequence:
- Parse all hooks/monitors/scripts
- Validate hooks.json + monitors.json + plugin.json schemas
- Verify every skill + agent has valid frontmatter
- Execute every hook with mock stdin (catches crashes)
- Boot-test every monitor (3s startup check)
- Dispatch each bundled script to confirm it's callable
Exit 0 = all passed. Non-zero = at least one failure.
.github/workflows/test.yml runs the self-test on every push to main and every PR, across:
- Ubuntu / macOS / Windows
- Node 20 + Node 22
This catches platform regressions before they ship.