Skip to main content
command CX Codex

obsidian-init — Claude Code command: setup and install

obsidian-init scans an Obsidian vault and creates _CLAUDE.md, index.md, and a log pointer. Use it to prepare vault guidance and a note catalog for Claude.

MIT ★ 5,412 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain
Open on GitHub

What obsidian-init does

Run /obsidian-init to map the vault and write _CLAUDE.md with working guidance, index.md with a note catalog, and log.md pointing to daily logs. The command also adds an initialization entry under Logs/ and creates base files for projects, people, tasks, and daily notes. Existing base files are left untouched.

Parallel subagents inspect the dashboard, templates, boards, and sample notes from major folders. Existing privacy rules in _CLAUDE.md still apply: finding a protected file does not grant permission to read its contents. Existing notes are not moved or edited.

The optional First-Brain layout requires user confirmation. If .vault-config.json lacks rewrite_policy, the command asks whether to keep confirmation before rewrites or use unattended. That choice matters: unattended ingestion can let a poisoned source rewrite existing notes without asking. This command is for Claude Code.

What it helps with

  • generate _CLAUDE.md from the vault’s structure
  • catalog notes in index.md by folder
  • set up a root log pointer and daily log entry
  • create missing project, people, task, and daily base files

Example prompts for the agent

  • Initialize my Obsidian vault with /obsidian-second-brain:obsidian-init.
  • Scan the vault and build _CLAUDE.md and index.md with /obsidian-second-brain:obsidian-init.
  • Set up the log files and bases by running /obsidian-second-brain:obsidian-init.

How to install obsidian-init

1Plugin marketplace

/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brain

2Manually: put the files in place

.claude/commands/obsidian-init.md

Call it with /obsidian-init. For all projects use ~/.claude/commands/

Questions about obsidian-init

How do I install obsidian-init in Claude Code?

Run /plugin marketplace add eugeniughelbur/obsidian-second-brain, then /plugin install obsidian-second-brain@obsidian-second-brain. The command file is .claude/commands/obsidian-init.md.

What does obsidian-init do?

It scans an Obsidian vault and creates Claude’s operating guide, a note catalog, and a pointer to daily logs. It also adds base files while preserving any that already exist.

Does obsidian-init read protected notes?

It follows existing privacy rules in _CLAUDE.md; discovering a file path does not authorize reading its body. Catalog entries for protected sources are limited to permitted metadata.

Source text

obsidian-init.md · MIT
---
description: Scan your vault and generate a _CLAUDE.md operating manual, index.md catalog, and log.md pointer
category: meta
triggers_en: ["init vault", "bootstrap vault", "setup vault", "scan vault"]
triggers_de: ["Vault einrichten", "Vault initialisieren", "Vault konfigurieren", "Vault scannen"]
triggers_es: ["inicializa el vault", "arranca el vault", "configura el vault", "escanea el vault", "inicia el vault", "deja listo el vault"]
triggers_pt: ["inicialize o vault", "bootstrap do vault", "configure o vault", "escaneie o vault"]
triggers_zh: ["初始化知识库", "为这个知识库生成初始配置", "扫描并配置我的知识库", "生成知识库操作手册"]
---

Use the obsidian-second-brain skill. Execute `/obsidian-init`:

1. Glob the vault (`<vault>/**/*.md`) to map the full vault structure
   - Before reading note bodies, honor any existing sensitive-content rules in `_CLAUDE.md`. Discovery of a path does not authorize reading private content.
   - **Optional First-Brain wiki-style variant:** if `First-Brain/` exists, offer this variant; otherwise offer it as an explicit layout choice when setting up wiki-style. An existing `First-Brain/` triggers an offer, never an automatic layout switch. A root folder whose name differs from `First-Brain` only by case, `_`, or a space (for example `First_Brain/` or `first brain/`) triggers the same offer: ask whether it is the human source layer. Preserve the current layout when the variant is declined. See `references/vault-schema.md` under "First-Brain wiki-style variant".
   - When selected, ensure `First-Brain/` exists, creating it if absent with filesystem tools. Before creating directories, check that planned paths remain inside the vault and existing paths are directories; stop on a file named `First-Brain` or an unsafe linked path. If the user confirmed an existing folder with another spelling as the source layer, use that folder and do not create `First-Brain/` beside it. Record the exact folder name the user confirmed; every later step writes that name wherever this playbook or the template says `First-Brain/`. Do not move, rename, edit, or ingest existing notes during initialization.
   - Resolve output destinations through `references/folder-map.md`, using wiki-style defaults for this variant even if `wiki/` was absent before this run. Create missing destination directories with filesystem tools. Include raw-source subfolders (articles, transcripts, pdfs, videos), research, operation logs, and Bases in their established locations. Keep existing custom output routes unless the user approves replacing them; never route generated outputs under the source folder.
2. Spawn parallel subagents to discover vault context simultaneously:
   - **Dashboard agent**: read `Home.md` or equivalent dashboard
   - **Templates agent**: read all files in `Templates/`
   - **Boards agent**: read all files in `Boards/`
   - **Samples agent**: read one existing note per major folder to capture naming conventions and frontmatter patterns
3. Merge all agent results into a complete picture of the vault
4. Generate a complete `_CLAUDE.md` using the template bundled with the skill at `SKILL_ROOT/references/claude-md-template.md` (its absolute path was given at session start as **Skill root**), filled with real values from the vault
   - For the selected variant, include the template's **First Brain Protection** section and a `First-Brain/` source-layer row, plus explicit note-type destinations resolved through `references/folder-map.md`. Cover entities, concepts/synthesis, projects, meetings, decisions/conflicts, tasks/recurring obligations, daily notes, work logs, reviews, agenda, and boards; keep raw captures, research, operation logs, and Bases in their established locations. Update auto-save rules, propagation rules, and key-file references to those resolved destinations rather than copying human-first defaults. Human originals are not candidates for AI-first conversion. Carry these ownership rules into any subagent instructions.
5. Generate `index.md` at the vault root - a catalog of all pages organized by category:
   - List every note in the vault grouped by folder (Projects, People, Ideas, etc.)
   - Include a one-line description for each note (from frontmatter or first paragraph)
   - Claude reads this file FIRST when navigating the vault - cheaper and faster than searching
   - Format: `- [[Note Name]] - brief description`
   - For protected sources, catalog only permitted metadata; do not read private note bodies merely to generate descriptions. First Brain catalog entries are source pointers, not permission to rewrite those files.
6. Initialize the vault operations log:
   - Create `Logs/` directory at the vault root
   - Write `log.md` at the vault root as a thin pointer file: explains the per-day structure, points at `Logs/`, and ships the entry template (do NOT put log entries in `log.md` itself)
   - Write today's `Logs/YYYY-MM-DD.md` with the init entry: `**HH:MM** - init | Vault initialized with _CLAUDE.md, index.md, Logs/`
   - Per-day file format: frontmatter (`type: log`, `date`, `ai-first: true`) + `**HH:MM** - action | description` entries, append-only
7. Create `Bases/` at the vault root if it does not exist. Stamp the four premade base files from `SKILL_ROOT/references/bases/` (the skill root given at session start):

   | Template | Output file | Obsidian-style folder | Wiki-style folder |
   |---|---|---|---|
   | `projects.base.template` | `Bases/Projects.base` | `Projects` | `wiki/projects` |
   | `people.base.template` | `Bases/People.base` | `People` | `wiki/entities` |
   | `tasks.base.template` | `Bases/Tasks.base` | `Tasks` | `wiki/tasks` |
   | `daily.base.template` | `Bases/Daily.base` | `Daily` | `wiki/daily` |

   Use the selected First-Brain variant's wiki-style routes when applicable; otherwise detect vault style from the folder structure discovered in step 1: if `wiki/` exists at the root, use wiki-style folder names; otherwise use obsidian-style. Honor approved custom Folder Map destinations. For each template, replace its named placeholder (`{{DAILY_FOLDER}}`, `{{PEOPLE_FOLDER}}`, `{{PROJECTS_FOLDER}}`, `{{TASKS_FOLDER}}`) with the correct folder name, then write to `Bases/`.

   Skip any base file that already exists in `Bases/` - never overwrite.

8. Rewrite policy, asked once (#250). If `<vault>/.vault-config.json` has no `rewrite_policy` key, ask one question: does this vault keep the confirm-before-rewrite gate on `/obsidian-ingest` (the default, `confirm`), or does it run unattended with its own review layer such as git history (`unattended`)? Say the cost of `unattended` in one sentence: a poisoned source can then rewrite existing notes with nobody asked. Write the key only when the answer is `unattended`; the default needs no key. Merge into the existing file if there is one - never drop its other keys (`exclude-dirs`, `exclude-paths`, `exclude-link-scan`). If the key already exists, do not ask again.

9. Write `_CLAUDE.md`, `index.md`, root `log.md` (pointer), `Logs/YYYY-MM-DD.md` (today's entries), and any new `Bases/*.base` files
10. Write `<vault>/.claude/CLAUDE.md` holding a single import line, `@../_CLAUDE.md`, unless that file already exists with other content - in which case add the import line to it and leave the rest alone. This is what loads the manual for a Claude Code session started in the vault: Claude Code follows the import natively, with a 4 MiB limit, while the SessionStart hook is capped at 10,000 characters of context and cannot carry a real manual (#270).
11. Confirm what was written and tell the user to restart their Claude session so the new files take effect
   - If the selected First-Brain variant has eligible sources, suggest `/obsidian-ingest First-Brain/ --preview` followed by explicit directory ingestion. Use only permitted path metadata to identify candidates, including supported PDFs, audio, and images. Do not launch ingestion or read private bodies to make the suggestion.

If `_CLAUDE.md` already exists: show a diff of what would change and ask before overwriting.
If `index.md` already exists: regenerate it (it's always a fresh catalog of current vault state).
If a monolithic `log.md` already exists with `## YYYY-MM-DD` sections: run `uv run --directory "SKILL_ROOT" scripts/migrate_log.py --vault <vault-path>` (its absolute path was given at session start as **Skill root**; substitute it for `SKILL_ROOT`) to split it into `Logs/YYYY-MM-DD.md` files. Do not overwrite manually.

---

**AI-first rule:** Every note created or updated by this command MUST follow `references/ai-first-rules.md` - `## For future agent` preamble, rich frontmatter (`type`, `date`, `tags`, `ai-first: true`, plus type-specific fields), recency markers per external claim, mandatory `[[wikilinks]]` for every person/project/concept referenced, sources preserved verbatim with URLs inline, and confidence levels where applicable. If that path does not resolve from your working directory, search upward for it; if you still cannot read it, say so before writing rather than producing a note that silently skips the rule. The vault is for future agent retrieval - not human reading.

**Anti-fabrication:** Search exhaustively before claiming any note, person, or file is absent - false absence is the most common failure mode - and never invent facts, entities, or dates (mark unknowns as `TBD`). See the anti-fabrication and search-completeness hard rules in `references/ai-first-rules.md`.

© Eugeniu Ghelbur · MIT · eugeniughelbur/obsidian-second-brain

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set51

The whole set →
obsidian-merge obsidian-merge merges near-duplicate Obsidian notes without deleting files. It preserves links, unions frontmatter, and converts the retired note into a redirect stub. CX Codex +1 ★ 5,412repo stars obsidian-checkin The obsidian-checkin command asks the vault owner to confirm aging facts in notes and records their replies. Use it to review details about people or projects that may have changed. CX Codex +1 ★ 5,412repo stars research-deep research-deep scans your Obsidian vault to map what you already know, identifies missing or stale information, fills gaps via Perplexity or Grok, synthesizes the findings, and updates your notes on people, projects, and ideas automatically. CX Codex +1 ★ 5,412repo stars create-command create-command scaffolds a new slash command for Obsidian through an interactive interview, removing the need to write Markdown or frontmatter by hand. CX Codex +1 ★ 5,412repo stars obsidian-health obsidian-health scans your Obsidian vault for contradictions, concept gaps, stale claims, and structural issues. Reports findings grouped by severity and spins up specialized agents to triage each category. CX Codex +1 ★ 5,412repo stars obsidian-calendar obsidian-calendar connects an Obsidian vault to Google Calendar across four modes: agenda snapshots, task reconciliation, meeting notes, and event scheduling. CX Codex +1 ★ 5,412repo stars obsidian-ingest The obsidian-ingest command brings a source or folder batch into an Obsidian vault, updates entities, and reconciles conflicting concepts. Use it for research intake. CX Codex +1 ★ 5,412repo stars obsidian-second-brain obsidian-second-brain connects Claude Code to your Obsidian vault so notes become searchable memory. New sources rewrite existing pages, contradictions get reconciled, stale facts get flagged. ★ 5,412repo stars

Project sponsors

Companies that keep this analytics open