📋 Requirements

• Obsidian 1.12+ (for CLI support)
• An AI coding agent: Claude Code (full support), Codex CLI, or Gemini CLI
• Node 22+ LTS (for hook scripts — typically already installed alongside Claude Code / Codex / Gemini CLI)
• Git (for version history)
• QMD (optional, for semantic search)

Note on the Node flag. Hook scripts execute TypeScript directly via Node's --experimental-strip-types flag, stable in Node 22.6+ (Aug 2024) and the default behaviour in Node 23.6+. The flag is marked experimental but has been unchanged across 22 LTS and 24 LTS; if a future Node release retires or renames it, hook commands in .claude/settings.json, .codex/hooks.json, and .gemini/settings.json need a one-line update.

---

📦 Install via ShardMind (recommended)

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind

shardmind install writes into the current directory, so create and enter a fresh folder first. The wizard collects your name, organization, vault purpose, agents to include, and whether to enable QMD; ShardMind then initializes git, optionally bootstraps QMD, and personalizes brain/North Star.md with your answers. Then:

1. Open the installed folder as an Obsidian vault
2. Enable the Obsidian CLI in Settings → General (requires Obsidian 1.12+)
3. Run your agent in the vault directory: claude, codex, or gemini. Codex runs the vault's hooks only once the folder is trusted and each hook approved: see Using with Other Agents.
4. Start talking about work

ShardMind is the package manager for Obsidian vault templates. The install adds a .shardmind/ sidecar that powers the wizard, optional modules (skip what you don't use), and three-way-merge upgrades. With every value at its default the install is byte-equivalent to git clone — clone-UX is preserved exactly. Delete .shardmind/ and shard-values.yaml from the installed vault and it keeps working: ShardMind is additive, not load-bearing.

🚀 Quick Start

→ "You have 2 active projects. The auth refactor is blocked on API contract.

📅 Daily Workflow

Morning: Run /om-standup. Your agent loads your North Star, active projects, open tasks, and recent changes. You get a structured summary and suggested priorities.

Throughout the day: Talk naturally. Mention a decision you made, an incident that happened, a 1:1 you just had, a win you want to remember. The classification hook nudges the agent to file each piece correctly. For bigger brain dumps, use /om-dump and narrate everything at once.

End of day: Say "wrap up" and the agent invokes /om-wrap-up — verifies notes, updates indexes, checks links, spots uncaptured wins.

Weekly: Run /om-weekly for cross-session synthesis — North Star alignment, patterns, uncaptured wins, and next-week priorities. Run /om-vault-audit to catch orphan notes, broken links, and stale content.

Review season: Run /om-review-brief manager and get a structured review prep document with all the evidence already linked.

---

🩺 Troubleshooting

Claude Code ignores the vault's conventions. Claude Code reads a CLAUDE.md in place of AGENTS.md and skips AGENTS.md without saying so. Two ways that happens:

• A leftover CLAUDE.md in the vault. An update keeps a CLAUDE.md you edited. The session hygiene flags say CLAUDE.md present beside AGENTS.md, and /om-vault-upgrade lists it under Move out. Move what you added to .claude/rules/local.md (or into AGENTS.md if every agent needs it, keeping AGENTS.md under 23 KB, where the hygiene flags start: Antigravity stops reading it at ~24,000 bytes), then delete CLAUDE.md. Nothing is merged automatically.
• A CLAUDE.md in a folder above the vault. Claude Code reads that one too, and AGENTS.md is skipped. The hygiene flag cannot see it, because it checks the vault root only. Move the vault out from under that folder, or move that file's content somewhere it applies only where you want it.

Gemini CLI loads no instructions when started in a vault subfolder. Gemini's context search walks up the folders, but its settings lookup does not, so a session started in a subfolder never reads the vault's .gemini/settings.json and never learns to look for AGENTS.md. Start Gemini from the vault root.

Gemini ignores what you added to GEMINI.md. Gemini now reads AGENTS.md (through .gemini/settings.json), so a leftover GEMINI.md is never loaded. The hygiene flags say GEMINI.md present beside AGENTS.md, and /om-vault-upgrade lists it under Move out. Move your additions to AGENTS.md, then delete it.

Grok reads nothing from the vault. Grok loads project instructions only from a trusted folder. Trust the vault once: run /hooks-trust in a Grok session, or launch with --trust. One grant covers MCP, LSP, hooks, project instructions and project skills.

---