How to Set Up claude-obsidian with an Existing Obsidian Vault

To set up claude-obsidian with an existing Obsidian vault, use the adopt command's dry-run workflow to generate a cryptographic plan, approve it via SHA256 checksum, and apply the changes atomically—this adds only hidden scaffolding files without modifying your existing notes.

The claude-obsidian project by AgriciDaniel/claude-obsidian enables AI-powered operations on Obsidian vaults through a Python CLI interface. When you need to set up claude-obsidian with an existing Obsidian vault that already contains your notes, the system provides a specialized adoption workflow that treats your vault as a plain directory while adding only the necessary metadata structures.

Understanding the Non-Destructive Adoption Model

According to the source code in claude_obsidian/vault_ops.py, the adoption process is explicitly designed to be idempotent and read-only regarding your existing content. The system scans the vault directory containing Markdown, JSON, and source files, then generates a deterministic plan that lists only the missing product metadata.

What the Adopt Command Actually Creates

During adoption, the CLI writes hidden scaffolding required for provenance and transaction logic:

• .claude-obsidian.json – Product configuration metadata
• inbox/ – Directory for incoming processed content
• .raw/ – Directory for raw data storage
• .vault-meta/ – Vault-specific metadata directory

These additions enable operations like /claude-obsidian:wiki-ingest and /claude-obsidian:wiki-query while preserving full ownership of your existing notes.

Prerequisites and Vault Selection

Before running the adoption commands, ensure you have Python 3 installed and the repository cloned. The CLI resolves the target vault using a precedence chain documented in docs/install-guide.md lines 55-62.

Vault Selection Precedence

While you can configure default vaults in your environment, the most explicit method is supplying --vault <path> as a command-line argument, which overrides all other resolution methods. Always use absolute paths to avoid ambiguity when setting up claude-obsidian with an existing Obsidian vault.

Step-by-Step Adoption Workflow

The adoption process implemented in scripts/claude-obsidian.py follows a strict two-phase commit pattern to ensure safety.

1. Preview the Adoption Plan (Dry Run)

First, generate the adoption plan without making changes. This invokes the adopt planner that outputs a JSON plan detailing every file the product would create or modify:

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

The --generated-at timestamp and --operation-id parameters ensure plan traceability. Review the printed JSON output carefully before proceeding.

2. Review and Approve the Plan

Inspect the generated plan to confirm it only affects hidden scaffolding directories. Copy the approved_plan_sha256 value from the JSON output—this cryptographic hash ensures the plan hasn't been modified between review and execution.

3. Execute the Atomic Transaction

Re-run the same command with the approval hash and the --apply flag to perform the single atomic transaction:

python3 scripts/claude-obsidian.py adopt "$VAULT_PATH" \
  --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --operation-id adopt-reviewed \
  --approved-plan-sha256 "3a5f…bc9d" \
  --apply

The core logic in claude_obsidian/vault_ops.py performs this write operation as a single transaction, ensuring that either all scaffolding files are created successfully or none are.

4. Verify the Integration

After adoption, confirm the vault is ready for operations using the verification commands documented in docs/install-guide.md lines 66-71:

python3 scripts/claude-obsidian.py doctor --vault "$VAULT_PATH"
python3 scripts/claude-obsidian.py contracts --verify --vault "$VAULT_PATH"

The doctor command checks vault health, while contracts --verify validates that the required metadata structures are present and correctly formatted.

Summary

• The adopt command in scripts/claude-obsidian.py provides a non-destructive way to set up claude-obsidian with an existing Obsidian vault.
• Always perform a dry-run first to generate the approved_plan_sha256 before applying changes with the --apply flag.
• The process creates only hidden scaffolding files (.claude-obsidian.json, inbox/, .raw/, .vault-meta/) and never overwrites existing notes.
• Use --vault <path> to explicitly specify your vault location, overriding default selection logic documented in docs/install-guide.md.
• Verify adoption completion using doctor and contracts --verify commands to ensure the vault is ready for wiki operations.

Frequently Asked Questions

Will claude-obsidian overwrite my existing notes?

No. According to the implementation in claude_obsidian/vault_ops.py, the adoption workflow is strictly additive. It creates only the hidden scaffolding files required for the system's provenance and transaction logic, leaving all existing Markdown, JSON, and source files untouched. This design ensures you retain full ownership of your vault content while enabling AI-powered operations.

What if I want to adopt multiple vaults?

You can run the adoption workflow independently on multiple vaults by specifying different paths with the --vault argument for each invocation. Each vault maintains its own .claude-obsidian.json configuration and metadata directories, allowing you to operate on multiple vaults from the same CLI installation without cross-contamination.

How do I verify the adoption was successful?

After running the adopt command with --apply, execute python3 scripts/claude-obsidian.py doctor --vault <path> to check vault health, followed by python3 scripts/claude-obsidian.py contracts --verify --vault <path> to confirm the scaffolding files are correctly initialized. These commands are documented in docs/install-guide.md lines 66-71 and validate that the vault is ready for operations like wiki-ingest and wiki-query.

Is the adopt command safe to run multiple times?

Yes. The adoption process is explicitly idempotent as implemented in the source code. If you run the same adopt command again after successful adoption, the system will detect that the scaffolding files already exist and will not attempt to recreate them. This makes it safe to re-run the command if you are unsure whether a previous attempt completed successfully.

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