obsidian

obsidian

Obsidian vault integration for Claude Code — auto-save sessions, capture git commit context, and create/recall notes from the CLI.

Why

Long Claude sessions and the commits they produce hold context that's gone the moment the session ends: why a decision was made, what was investigated and rejected, loose ends flagged for later. Pasting that into Obsidian by hand is the kind of chore that doesn't get done. This plugin captures it automatically — sessions on stop, commit context on every git commit — and routes notes to the right folder by domain.

How it works

• A Stop hook runs at session end; if the session is significant, a background claude --print summarizer writes a structured note to your vault.
• Session capture infers both session_intent and capture_action with confidence scores and evidence bullets, so routing can distinguish execution, research, planning, operations, reflection, and scratch work.
• A PostToolUse hook on Bash detects successful git commit calls and appends goal / investigation / decision / loose-ends bullets to a per-repo daily file.
• Slash commands (skills) cover the manual paths: save, find, recall, daily, new, bookmark, setup.
• Routing is driven by obsidian.local.md — a vault path and a keyword-based domain taxonomy you edit directly.

Skills

Command	Purpose
/obsidian:setup	First-run wizard. Writes obsidian.local.md with vault path, domains, routing.
/obsidian:save [topic]	Save the current session. Optional topic hint overrides auto-routing.
/obsidian:find <query>	Search the vault by keyword, tag, or topic.
/obsidian:new <title>	Create a new note or project folder.
/obsidian:daily [content]	Open or append to today's daily note.
/obsidian:bookmark [label]	Mark a chapter boundary; saved as a separate note at session end.
/obsidian:recall <query>	Cross-search vault, git history, GitHub PRs, and claude-mem.
/obsidian:ask	Ask the vault librarian — index-grounded answers with citations, or file new info without back-and-forth.

Vault Librarian

/obsidian:ask dispatches the vault-librarian subagent. It answers queries by routing to the relevant domain folder, refreshing that slice's INDEX.md on-demand (two-stage: file mtime narrows candidates, a stored size:sha256 content hash confirms real changes — so a Syncthing mtime-bump doesn't trigger re-indexing), then reading only the indexed notes and citing them with a confidence level. It reports indexing gaps rather than answering from a partial slice, and falls back to the find skill for raw-text search when the index misses.

For inserts it routes new notes through the taxonomy, dedups against existing notes, writes via the matching Templates/ file, and appends a link to the right INDEX — deferring genuine unknowns to [ask] markers in Pending.md instead of interrupting you.

Per-INDEX machine state (content hashes + last-reconciled timestamp) lives in a hidden .<index>.state sidecar file beside each INDEX.md, so the human- readable index is only ever appended to, never rewritten.

vaultkeeper watcher

The plugin includes a two-layer background maintenance system that keeps the vault accurate without LLM overhead on every tick.

Two-layer model

Layer 1 — deterministic substrate tick (scripts/vaultkeeper-tick.sh): a pure-bash script that runs on cron (Linux) or launchd (macOS), namespaced com.nhangen.obsidian-vaultkeeper. It validates frontmatter against the required keys, scans for unfiled notes, open [ask] markers, and promotable clusters, then surfaces candidates into Librarian.md and appends only genuinely-new items to Pending.md. No LLM involved; no writes to the CEO vault.

Layer 2 — on-demand agent (/obsidian:ask): the vault-librarian subagent answers queries and acts on the pre-computed candidate lists from Layer 1, only spinning up an LLM when a human query needs it.

Machine-owned Librarian.md

Librarian.md is written exclusively by the keeper tick. Manual edits do not persist — the next tick overwrites it atomically. Read it as a live dashboard; don't edit it.

Activation (automatic)

The keeper activates itself. The first time the session-end hook (session-save.sh) runs on a host where the keeper isn't scheduled yet, it seeds the frontmatter schema, writes default keeper config, and installs the namespaced scheduler — no command to run. Once installed it's a cheap no-op on every later session end.

Because Syncthing carries the vault but not a launchd plist / crontab line, each host self-activates the first time you work on it. Opt out with keeper_autostart: false in obsidian.local.md.

To install manually (or on a host you never run a session on), the engine is still directly invokable:

bash scripts/install-watcher.sh install "$(pwd)/scripts/vaultkeeper-tick.sh"