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

> Initialize a new Claude-Obsidian vault with our step-by-step guide. Learn the two-step review-and-apply workflow for SHA-256 hashed transaction plans before disk writes.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: getting-started
- Published: 2026-08-28

---

**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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py), which delegates file-system operations to [`claude_obsidian/vault_ops.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/vault_ops.py) while the transaction engine in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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:

```bash
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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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:

```bash
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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/.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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/index.md)
  - [`log.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/log.md)
  - [`hot.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/hot.md)
  - [`overview.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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:

```bash
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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py) (CLI entry), [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) (plan generation), and [`claude_obsidian/vault_ops.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/.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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py), the repository includes an optional helper script at [`bin/setup-vault.sh`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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.