What Happens When You Install This

After a meeting: /obsidian-save Claude pulls out every decision, person, task, and idea and saves each one to the right note. You do nothing.

You recorded a voice memo: /obsidian-ingest meeting.m4a Claude transcribes it with a local Whisper install, attributes speakers where the transcript makes them identifiable, extracts every promise and action item, and distributes across entity pages, task boards, and the daily note.

You screenshot a whiteboard: /obsidian-ingest photo.png Claude reads the image, extracts text and structure, creates concept notes, links to related projects. A photo becomes knowledge.

You find a great video: /obsidian-ingest https://youtube.com/... Claude doesn't summarize into one note. It REWRITES your existing pages. People get updated. Contradictions get resolved. Patterns trigger new synthesis pages. One URL in. The vault is smarter.

Before a big decision: /obsidian-challenge Claude searches your vault for past failures and reversed decisions on the same topic. Pushes back with your own words. Your vault holds you accountable.

You want to see the big picture: /obsidian-visualize Claude generates a visual canvas of your entire vault. Hub nodes centered, color-coded by type, orphans highlighted. Open it in Obsidian and see the shape of your knowledge.

You go to sleep: The nightly agent runs 5 phases: closes the day, reconciles contradictions, synthesizes cross-source patterns, heals orphan notes, and rebuilds the index. You wake up to a smarter vault.

You start a new day: /obsidian-daily Claude pulls your calendar events, overdue tasks, and overnight changes into today's note. Your morning starts informed.

Someone shares an X post: /x-read https://x.com/... Grok with live X access fetches the post, the thread, and the replies. Returns verbatim text + TL;DR + key claims + reply sentiment + voices to watch. No more screenshots.

You're planning today's content: /x-pulse "AI automation" Grok scans X for what's trending in your topic right now. Returns 3-5 emerging themes (with rep posts + key voices), gaps nobody is filling, hook formats that are working, and 3 specific post ideas you could write today.

You need real research: /research "AI memory tools" Perplexity Sonar Pro pulls a deep dossier with citations: summary, key facts (every claim with a recency marker and source domain), timeline, key players, contrarian views, recommended further reading, open questions. Saved to your vault, auto-opens in Obsidian.

You want vault-first deep research: /research-deep "AI memory tools" Scans your vault for what you already know. Identifies gaps. Spawns 3-5 targeted searches via Perplexity (web) and Grok (X discourse). Synthesizes a delta report: what's new, what's confirmed, contradictions to resolve, recommended vault updates. Vault baseline doesn't get re-researched. Only gaps get filled.

You hit a great YouTube video: /youtube https://youtu.be/... Free transcript via youtube-transcript-api. Optional metadata + top comments via YouTube Data API v3. Gemini (free tier, Grok fallback) summarizes into TL;DR, Key Points, Notable Quotes (verbatim), Themes, Comment Sentiment, and Worth Following Up On. Saved as an AI-first note in your vault. Add --visual to also watch it: scene-change frame extraction (ffmpeg) that Claude reads with its own vision to capture on-screen text, code, diagrams, and demos the transcript misses.

You never open Obsidian. Everything happens through Claude.

---

Install

One codebase, eight builds. Pick yours below. The vault behavior is identical across all of them; only the install path and the dispatcher file (CLAUDE.md / AGENTS.md / GEMINI.md / .agents/skills/ / .pi/ / workflow SKILL.md) differ.

Rather than ask you to take that on faith, here is what each build currently passes:

Generated by scripts/conformance_report.py, verified in CI on every push. Each build is compiled from the same source tree, then checked for a non-empty output, a resolved script root, reference paths that actually exist in that build, and a Python project shipped beside the scripts. A red cell here is a real red cell, not a missing test.

Prerequisites: Claude Code (or one of the other six platforms below), git, and uv for the Python helpers (health check, research toolkit, bootstrap). jq is required for the classic script install - scripts/setup.sh uses it to edit ~/.claude/settings.json safely and exits if it is missing. Not needed on the plugin path. Optional: Ollama for local semantic search, openai-whisper (installed on first audio ingest, pulls in PyTorch). No API keys needed for the core vault commands.

install with skills.sh (writes one shared .agents/skills/ tree), from your vault root:

npx skills add /path/to/obsidian-second-brain/dist/agent-skills -a antigravity -a codex -a opencode

Review dist/grok-bot/INSTALL.md for platform-specific instructions

```

The Grok Bot build emits workflow SKILL.md files that Grok Bot and Sand agents invoke with / or @. Each skill is a self-contained playbook (name, description, operating instructions). The user-obsidian-second-brain MCP server (already connected in Grok Bot) provides the vault I/O layer via obsidian_* tools (obsidian_search, obsidian_read_note, obsidian_save_note, obsidian_update_note, obsidian_validate_note, etc.). Skills tell the agent which MCP tool to call and how to structure the data. Set $OBSIDIAN_VAULT_PATH to your vault root. No hooks, no scheduled agents - Grok Bot has no hook runtime.

then follow dist/hermes/INSTALL.md (copy into ~/.hermes/skills/ or add as a tap)

This is the skill/playbook half of the Hermes work; the bounded vault-data half is the [MCP connector](integrations/obsidian-mcp-server/). Native cron and lifecycle-hook integration are tracked in [Issue #79](https://github.com/eugeniughelbur/obsidian-second-brain/issues/79).

Point OpenCode at Hermes via OpenRouter. Authenticate once (`/connect`, search OpenRouter, paste your key - or `export OPENROUTER_API_KEY=...`), then in `opencode.json`:

Hermes models on OpenRouter (as of 2026-06, openrouter.ai):

For the privacy story, run a smaller Hermes locally through Ollama or LM Studio and point OpenCode at the local endpoint - no data leaves your machine.

What to expect (open models follow instructions less reliably than Claude, so this is honest, not a promise of parity): the core commands - /obsidian-save, /obsidian-daily, /obsidian-capture, /obsidian-find, /obsidian-task, and /research in free mode - hold up well. The sub-agent-heavy commands and the deep synthesis ones (/obsidian-architect, /obsidian-reconcile, /research-deep) lean hard on instruction-following, so prefer hermes-4-405b (or Claude) for those. The AI-first vault rule still applies on every write regardless of model.

Research toolkit (optional)

The 7 research commands use API keys (2 of them fall back to free sources without any).

Installed the plugin? You have no repo checkout, so install.sh, .env.example, and uv sync are not on your disk. Create the env file by hand instead - the research scripts read this path regardless of how you installed, and the plugin's MCP server already runs under uv run --no-project --with 'mcp<2', so there is nothing to uv sync:

```bash mkdir -p ~/.config/obsidian-second-brain touch ~/.config/obsidian-second-brain/.env chmod 600 ~/.config/obsidian-second-brain/.env

Semantic search (optional, off by default)

Search (/obsidian-find and the MCP connector) works out of the box as fast keyword search - no setup, no model, nothing to install. You can optionally add a meaning-based layer that finds notes even when your query shares no words with them. It is opt-in by setup and, when present, leads the ranking with keyword search as tiebreak and freshness signals on top (measured on a ~2,350-note vault: keyword recall@10 1.0, paraphrased-question recall@10 77%, and non-English queries went from 13% to 63% recall@5, a 5x gain, with the multilingual default model - full reference in scripts/eval/BASELINE.md). If the model is ever unreachable, search silently falls back to keyword - it never breaks or hangs.

Two ways to provide the embedding model:

• Local + private (recommended), via Ollama: install Ollama, ollama pull bge-m3, then build the index: uv run python scripts/eval/semantic_search.py --path "<vault>" --build. Your notes never leave the machine. Re-run it as you write - see below.
• No Ollama? Any OpenAI-compatible endpoint. Set OBSIDIAN_EMBED_BACKEND=openai, OBSIDIAN_EMBED_URL=<base url>, OBSIDIAN_EMBED_MODEL=<model>, and OBSIDIAN_EMBED_KEY=<key if needed>. This covers other local runtimes (LM Studio, llama.cpp's server) for free/private use, or a cloud API (OpenAI, a gateway) for top quality - note a cloud endpoint means note text leaves your machine, so use OBSIDIAN_EMBED_EXCLUDE=<folder prefixes> to keep private folders local-only.

Keep it current. The index does not update itself, and a note that is not in it can only be found by literal word match - which on a query in another language means it cannot be found at all. Re-run --build regularly; it is incremental, so only new and changed notes re-embed. /obsidian-health reports coverage, and search warns on stderr once the index falls more than 5% behind (tune with OBSIDIAN_INDEX_STALE_WARN_PCT).

Knobs: OBSIDIAN_SEARCH_SEMANTIC=0 disables the layer entirely. The index file is large and regenerable - gitignore it.

---

Codex CLI / Gemini CLI / OpenCode

Codex and OpenCode users: prefer the Agent Skills build below. The standalone codex-cli and opencode builds are deprecated and superseded by it; both print that notice in their own INSTALL.md. They still work, and will until they are removed. Gemini CLI has no replacement build, so this is the right path there.

git clone https://github.com/eugeniughelbur/obsidian-second-brain
cd obsidian-second-brain
bash scripts/build.sh --platform codex-cli   # or gemini-cli, or opencode
cp -R dist/codex-cli/. /path/to/your/vault/   # or dist/gemini-cli/. or dist/opencode/.

Then start your CLI from the vault root.

The Codex build emits native Codex Agent Skills: one skill per command under .agents/skills/<name>/SKILL.md. Codex discovers them automatically with progressive disclosure (only each skill's name + description load until it's selected), and they run in your current session - invoke one with $<name>, pick it from /skills, or just describe the task and let Codex match it implicitly. AGENTS.md stays as a thin always-on manual (vault conventions + the AI-first rule); there is no routing table to maintain because the skill list is the router. The Gemini / OpenCode builds still emit a GEMINI.md / AGENTS.md dispatcher with an auto-generated routing table to command files under .gemini/ / .opencode/.

Run bash scripts/build.sh with no arguments to build every platform at once. See dist/<platform>/INSTALL.md after building for platform-specific notes.

Do I need API keys to use this?

Mostly no. The vault commands (/obsidian-save, /obsidian-daily, etc.) need no API keys. /research and /research-deep are also key-free now - with no Perplexity key they automatically fall back to free, key-less sources (Wikipedia, HackerNews, arXiv, Reddit, and more) and Claude synthesizes the dossier. The remaining research commands (/x-read, /x-pulse, /notebooklm, /youtube, /podcast) need their respective keys (xAI Grok, Perplexity, Google Gemini, optionally YouTube Data API v3 / OpenAI Whisper) and exit with a clear setup message when one is missing. The calendar command (/obsidian-calendar, all four modes) needs the Google Calendar MCP connector rather than an API key.

Is this an Obsidian plugin or a Claude Code skill?

This is a Claude Code skill, not an Obsidian plugin. An Obsidian plugin lives inside Obsidian and adds UI features there. A Claude Code skill lives inside Claude Code (Anthropic's terminal AI coding agent) and gives Claude the ability to read, write, and reason over your Obsidian vault from outside Obsidian. You install this skill into Claude Code, not into Obsidian. Your vault is unchanged, just better-leveraged.

FAQ