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
/plugin marketplace add eugeniughelbur/obsidian-second-brain
/plugin install obsidian-second-brain@obsidian-second-brainWhat 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.mdfrom the vault’s structure - catalog notes in
index.mdby 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.mdandindex.mdwith/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-brain2Manually: put the files in place
.claude/commands/obsidian-init.mdCall it with /obsidian-init. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/obsidian-init.mdCall it with /prompts:obsidian-init. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/obsidian-init.prompt.mdManually: put the files in place
.gemini/commands/obsidian-init.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
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