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

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, 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, which parses arguments and delegates to the core logic in 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:

# 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:

# 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 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, while the core vault operations—including the non-destructive initialization and adoption logic—are implemented in claude_obsidian/vault_ops.py. User-facing documentation appears in docs/install-guide.md.

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