How to Initialize a New Claude-Obsidian Vault: Step-by-Step Setup Guide

Initializing a new Claude-Obsidian vault requires a two-step review-and-apply workflow that generates a SHA-256 hashed transaction plan before writing any files to disk.

The Claude-Obsidian project—hosted at AgriciDaniel/claude-obsidian—provides a deterministic vault initialization process that scaffolds the mandatory directory structure for AI-assisted note management. Unlike conventional Obsidian setups, this tool enforces a transaction-based safety model to prevent accidental filesystem mutations.

Understanding the Vault Architecture

When you initialize a new vault, the system creates an immutable foundation consisting of hidden metadata files, a clean-room inbox/ directory for source captures, a read-only .raw/ payload store, and a generated wiki/ hierarchy containing index, log, hot cache, and overview files. This structure enables subsequent Claude-Obsidian skills—such as wiki-ingest and save—to operate within strict contractual boundaries.

The initialization logic resides in scripts/claude-obsidian.py, which delegates file-system operations to claude_obsidian/vault_ops.py while the transaction engine in claude_obsidian/transaction.py manages the plan-signing mechanism.

Step 1 – Review the Initialization Plan

Before creating any files, you must generate a preview of the proposed vault structure. This dry-run constructs a transaction bundle and prints a SHA-256 hash that uniquely identifies the plan.

Run the init command with a timestamp and operation ID:

python3 scripts/claude-obsidian.py init /path/to/new-vault \
  --generated-at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
  --operation-id init-reviewed

The CLI outputs a SHA-256 hash (e.g., abc123...). At this stage, no files are written. The transaction bundle is stored internally according to the protocol defined in claude_obsidian/transaction.py, allowing you to inspect exactly which directories and hidden files will be created before approving the operation.

Step 2 – Apply the Vault Initialization

Once you have verified the preview, apply the plan by passing the previously generated hash via --approved-plan-sha256 and adding the --apply flag:

python3 scripts/claude-obsidian.py init /path/to/new-vault \
  --generated-at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
  --operation-id init-reviewed \
  --approved-plan-sha256 abc123... \
  --apply

The vault_ops.py module now executes the concrete file-system actions, writing the following components to /path/to/new-vault:

• .gitignore – Exclusion rules for the vault
• .claude-obsidian.json – Product metadata and configuration
• inbox/ – Clean-room directory for pending captures
• .raw/ – Read-only storage for payload data
• wiki/ – Generated hierarchy containing:
  • index.md
  • log.md
  • hot.md
  • overview.md
• .obsidian/ – Standard Obsidian configuration directory
• .vault-meta/ – Hidden metadata storage

Verifying Your New Vault

After initialization, validate the vault integrity using the built-in diagnostic commands:

python3 scripts/claude-obsidian.py doctor --vault /path/to/new-vault
python3 scripts/claude-obsidian.py contracts --verify --vault /path/to/new-vault

These commands cross-check the directory structure against the contractual expectations defined in the source code, ensuring that inbox/, .raw/, and the wiki hierarchy conform to the initialization specification.

Summary

• Claude-Obsidian vault initialization uses a deterministic transaction model requiring explicit SHA-256 approval before any filesystem changes occur.
• The process splits into two distinct phases: generating a preview hash (Step 1) and applying the scaffolded structure (Step 2).
• Key source files include scripts/claude-obsidian.py (CLI entry), claude_obsidian/transaction.py (plan generation), and claude_obsidian/vault_ops.py (file creation).
• The resulting vault contains mandatory directories: inbox/, .raw/, wiki/, .obsidian/, and .vault-meta/, plus configuration files .gitignore and .claude-obsidian.json.
• Post-initialization verification relies on doctor and contracts --verify subcommands to ensure structural compliance.

Frequently Asked Questions

Does the initializer configure Git remotes or install plugins?

No. According to the implementation in claude_obsidian/vault_ops.py, the initialization process explicitly does not add Git remotes, install community plugins, or modify existing notes. It strictly scaffolds the required directory structure so that subsequent Claude-Obsidian skills can function safely within the established boundaries.

Why does the init command require a SHA-256 hash approval?

The SHA-256 requirement implements the transaction safety model defined in claude_obsidian/transaction.py. By hashing the plan during the review phase and requiring that exact hash during the apply phase, the system guarantees that the filesystem mutations match your preview exactly. This prevents race conditions, configuration drift, or accidental execution of modified plans between review and application.

Can I initialize a vault without Python installed?

While the primary workflow requires Python to run scripts/claude-obsidian.py, the repository includes an optional helper script at bin/setup-vault.sh for previewing vault creation logic in environments without a Python runtime. However, full initialization and transaction signing still require the Python-based toolchain to execute the complete two-step workflow.

What happens if the --apply flag is omitted?

Omitting --apply executes a dry run only. The command generates the transaction bundle, calculates the SHA-256 hash of the proposed changes, and outputs the hash to your terminal. No directories are created, and no files are written to the target path. This allows safe inspection of the planned filesystem layout across different environments before committing to the initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}