# Difference Between init and adopt in claude-obsidian: A Technical Guide

> Understand the difference between init and adopt in claude-obsidian. Learn how init creates new vaults and adopt integrates with existing folders without altering your notes.

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

---

**In claude-obsidian, `init` creates a brand-new vault from scratch while `adopt` safely wraps metadata structures around an existing Obsidian folder without touching your notes.**

The claude-obsidian project treats every knowledge base as a *vault* that requires specific metadata structures to enable AI-assisted management. According to the AgriciDaniel/claude-obsidian source code, these two distinct entry-point commands determine whether you are building a fresh repository or integrating with legacy Obsidian data.

## Core Conceptual Difference

The primary distinction lies in the starting state of your target directory and the safety guarantees each command provides.

### What `init` Does

**`init`** is the **vault creation** command designed for empty or non-existent directories. When executed, it generates the complete directory layout including `.raw/`, `wiki/`, and `.vault-meta/` subdirectories, and writes a fresh `claude-obsidian.initialization-plan.v1` file. As implemented in [`claude_obsidian/vault_ops.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/vault_ops.py), this command is strictly non-destructive—it refuses to overwrite existing vault content unless you explicitly provide the `--force` flag, matching the behavior verified in `test_init_refuses_existing_content_without_force`.

### What `adopt` Does

**`adopt`** is the **vault integration** command for existing Obsidian folders. Rather than creating new content directories, it scans your supplied folder, creates hidden `.claude-obsidian` bookkeeping structures, and writes an `claude-obsidian.adoption-plan.v1` file. As confirmed by `test_init_and_adopt_are_non_destructive`, this command leaves all user-generated markdown files completely untouched, making it safe for legacy vaults.

## Technical Implementation and File Structure

Both commands are orchestrated through [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py), which parses arguments and delegates to the core logic in [`claude_obsidian/vault_ops.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/vault_ops.py).

The implementation diverges in plan generation:

- **Initialization Plan**: Created by `init`, defines scaffolding for new directories
- **Adoption Plan**: Created by `adopt`, maps existing file trees into the vault metadata system without file system mutations

Both plans follow the same dry-run → review → apply lifecycle to ensure user consent before any disk operations occur.

## Command Workflow and Usage Examples

Each command supports identical CLI patterns requiring `--generated-at` timestamps and `--operation-id` identifiers for audit trails.

### Creating a New Vault with `init`

Use this when starting a project with no existing `.claude-obsidian` metadata:

```bash

# Dry-run to generate and review the initialization plan

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

# Apply after reviewing the generated plan

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

```

### Integrating an Existing Vault with `adopt`

Use this when you have an existing Obsidian vault at `~/ExistingObsidianVault` that needs claude-obsidian metadata:

```bash

# Dry-run to inspect the adoption plan

python3 scripts/claude-obsidian.py adopt ~/ExistingObsidianVault \
    --generated-at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
    --operation-id adopt-reviewed

# Apply the metadata wrapper

python3 scripts/claude-obsidian.py adopt ~/ExistingObsidianVault \
    --generated-at "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
    --operation-id adopt-reviewed \
    --apply

```

## Summary

- **`init`** creates a brand-new vault structure from an empty baseline, generating directories like `.raw/` and `wiki/` while writing an `initialization-plan.v1` file.
- **`adopt`** wraps existing Obsidian vaults with metadata structures, preserving all existing content and creating an `adoption-plan.v1` mapping.
- Both commands implement non-destructive safeguards: `init` refuses to overwrite existing vaults without `--force`, while `adopt` never modifies user markdown files.
- The workflow in [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py) enforces a mandatory review phase via `--dry-run` before `--apply` commits changes to disk.

## Frequently Asked Questions

### Will `adopt` modify my existing Obsidian notes?

No. According to the test suite in the repository, specifically `test_init_and_adopt_are_non_destructive`, the `adopt` command only creates hidden `.claude-obsidian` metadata directories and leaves all your existing markdown files and folder structures completely untouched.

### What happens if I run `init` on an existing vault?

The command will refuse to execute and exit with an error unless you provide the `--force` flag. As verified by `test_init_refuses_existing_content_without_force`, this prevents accidental overwrites of existing vault metadata.

### Do both commands support dry-run mode?

Yes. Both `init` and `adopt` implement identical dry-run semantics through the `--dry-run` flag (implied when `--apply` is omitted). This generates JSON plan files describing proposed changes without writing to disk, allowing inspection before commitment.

### Which files define the actual implementation of these commands?

The CLI parsing and orchestration reside in [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py), while the core vault operations—including the non-destructive initialization and adoption logic—are implemented in [`claude_obsidian/vault_ops.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/vault_ops.py). User-facing documentation appears in [`docs/install-guide.md`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/docs/install-guide.md).