second-brain-sync

A Claude Code plugin marketplace that installs a cross-machine, git-synced Obsidian + Claude Code second brain: one vault that is the ground-truth library and the shared memory for every Claude Code session you run, on every machine you own.

Everything is plain text, git, and shell. Nothing is locked in, and you can read every line before you trust it.

The one rule

No assumptions, no hallucination. If a fact is not verifiable from a file, a command output, or the user, write "unknown" instead of guessing.

This rule sits at the top of the shipped vault constitution and is repeated verbatim in every skill and every agent charter, because a false fact copied into memory is paid for again every time it is reused.

Install (one command per step)

Inside Claude Code:

/plugin marketplace add OfficialBishal/second-brain-sync
/plugin install second-brain@second-brain-sync

Then, on each machine (workstation or server), run the setup command:

/second-brain:setup

(It drives the setup-second-brain skill - asking Claude to "set up my second brain" in plain words triggers the same skill.)

It asks for your vault name, your vault's GitHub repo URL, and whether the machine is a workstation (Obsidian + GUI) or a server (headless). It then clones or initializes the vault, seeds it from the shipped template, installs the helper scripts into ~/bin, and writes ~/.second-brain.env so every script knows where your vault lives. No personal values are baked in anywhere; everything comes from that config file.

What you get

Skill	Command	What it does
setup-second-brain	/second-brain:setup	One-command setup of the vault, scripts, config, and sync on this machine.
wire-projects	/second-brain:wire	Adds a "## Second brain" pointer block to each project repo's CLAUDE.md and creates the matching vault skeleton. Skeletons only, no invented content.
backfill	/second-brain:backfill	The ground-truth archivist: reconstructs a project's goal, state, and decision lineage from README, git history, code, and results only. Every node cites its evidence.
sync-doctor	/second-brain:status	Diagnoses and fixes sync problems: unrelated histories, divergent branches, failing cron pushes, missing credentials, Obsidian Git quirks.
dashboard	/second-brain:dashboard	Renders the vault into a self-contained interactive dashboard.html, pre-rendered Obsidian dashboard notes, and an agent orientation layer (index.json + orientation.md). Build-time snapshot, ground truth only.

Plus seven optional war-room agents (orchestrator, scout, data-steward, engineer, critic, writer, reviewer) for multi-agent sprints, and a full vault template: constitution, dashboard, folder structure, note templates, and maintenance skills. The dashboard generator ties it together: one command renders your whole vault into an interactive cockpit (browser + Obsidian) and a machine-readable index that agents use to orient without scanning the vault.

How the sync works

Git is the spine. GitHub (or any git remote) is the meeting point between machines.

• Workstation (Obsidian + GUI): the Obsidian Git community plugin auto-pulls and auto-commit-and-syncs as you edit notes. The setup skill prints the exact plugin settings to use.
• Server (headless): cc-start.sh pulls at the start of each Claude Code session and cc-end.sh commits and pushes at the end. An optional cron runs vault-sync.sh (commit, then pull, then push) between sessions. Unattended pushes need stored HTTPS credentials or a passphrase-free SSH deploy key; the setup skill explains how to set that up but never touches or stores a secret itself.
• Both machines set git config pull.rebase false so concurrent edits reconcile by merge instead of stopping on a divergent-branches error.

One gotcha worth knowing up front: the Obsidian Git plugin only auto-syncs edits made in Obsidian. A commit you make in a terminal will not auto-push; push it once by hand. The sync-doctor skill covers this and the other failure modes.

Reconstructed history is provisional

The backfill skill labels everything it reconstructs confidence: reconstructed and ends with a "GAPS TO CONFIRM" section written as questions. Do not trust a reconstruction until you have reviewed those gaps and confirmed the nodes yourself. Only then change confidence: reconstructed to confidence: confirmed. Downstream agents treat reconstructed nodes as provisional.

Manual install (fallback, without the plugin system)

git clone https://github.com/OfficialBishal/second-brain-sync.git
mkdir -p ~/.claude/skills
cp -R second-brain-sync/plugins/second-brain/skills/* ~/.claude/skills/

Keep the clone around: the skills reference the plugin's bundled assets (vault template and scripts) via ${CLAUDE_PLUGIN_ROOT}, which is only set when installed as a plugin. When it is not set, the skills ask you where you cloned this repo and use <clone>/plugins/second-brain/assets instead.

Repo layout

second-brain-sync/
  .claude-plugin/marketplace.json      the marketplace manifest
  plugins/second-brain/
    .claude-plugin/plugin.json         the plugin manifest
    skills/                            setup-second-brain, wire-projects, backfill, sync-doctor, dashboard
    commands/                          /second-brain:setup, :wire, :backfill, :status, :dashboard
    agents/                            the seven war-room charters
    assets/vault-template/             the genericized vault (constitution, templates, structure)
    assets/scripts/                    cc-start.sh cc-end.sh vault-sync.sh scaffold.sh newproject.sh vault-dashboard.py

License

MIT. See LICENSE.