Scaffold the PKM system onto an existing Obsidian vault. Scans your vault structure, maps folders interactively, and generates configuration — no template required.
Bring Your Own Vault (BYOV) — install the Claude PKM system onto an existing Obsidian vault.
/adopt # Run from the root of your existing Obsidian vault
Analyze the existing vault to understand its organization.
List top-level directories using ls, excluding system dirs (.obsidian, , , , )
.git.claude.trash.claude-pluginFor each directory, gather signals:
.md files (using Glob)YYYY-MM-DD*.md) — indicates daily notesCLAUDE.md in subdirs — indicates projectsDetect organization method based on signals:
00-09, 10-19 style folder namesPresent findings to the user:
Vault scan complete!
Found 342 notes across 8 folders:
Daily/ → 180 notes (date-named — likely daily notes)
Projects/ → 45 notes (has CLAUDE.md files — likely projects)
Goals/ → 12 notes (contains goal keywords)
Templates/ → 8 notes (contains template keywords)
Archive/ → 67 notes
Inbox/ → 15 notes
Resources/ → 10 notes
Meeting Notes/ → 5 notes
Detected method: PARA-like structure
Use AskUserQuestion to confirm or correct the detected mappings.
Each role maps a PKM function to a folder in the user's vault:
| Role | Purpose | Detection Signal |
|---|---|---|
| Daily Notes | Daily journal entries | Date-named files (YYYY-MM-DD) |
| Goals | Goal cascade (3-year → weekly) | Files with goal/review keywords |
| Projects | Active projects | Subdirs with CLAUDE.md or project keywords |
| Templates | Reusable note structures | Files with template keywords or in Templates/ |
| Archives | Completed/inactive content | Folder named Archive(s) or with old dates |
| Inbox | Uncategorized captures | Folder named Inbox, or files tagged #inbox |
For each role, ask the user to confirm or correct:
Question format (use AskUserQuestion):
Edge cases:
CLAUDE.md.backup or merge contentStore the folder mapping for use in later phases:
dailyNotes → "Daily"
goals → "Goals"
projects → "Projects"
templates → "Templates"
archives → "Archive"
inbox → "Inbox" (or null if skipped)
Ask the same 4 questions as /onboard:
Question 1: Your name
Question 2: Preferred review day
/review auto-detection and session-init nudgesQuestion 3: Primary goal areas
Question 4: Work style
settings.jsonWrite .claude/settings.json with permissions scoped to the user's actual folders:
{
"permissions": {
"allow": [
"Read",
"Write **/{mapped-daily}/**",
"Write **/{mapped-goals}/**",
"Write **/{mapped-projects}/**",
"Write **/{mapped-templates}/**",
"Edit **/{mapped-daily}/**",
"Edit **/{mapped-goals}/**",
"Edit **/{mapped-projects}/**",
"Glob",
"Grep"
]
}
}
Replace {mapped-*} with actual folder names from Phase 2.
CLAUDE.mdGenerate a root CLAUDE.md that describes the user's actual vault structure. Use the same format as the template's CLAUDE.md but with:
If the user had an existing CLAUDE.md, merge their content into the appropriate sections (preserve their mission statement, custom conventions, etc.).
vault-config.jsonWrite vault-config.json in the vault root:
{
"name": "User's name",
"reviewDay": "Sunday",
"goalAreas": ["Career & Professional", "Health & Wellness"],
"workStyle": "Direct and concise",
"setupDate": "2026-02-17",
"version": "3.1",
"adoptedVault": true,
"folderMapping": {
"dailyNotes": "Daily",
"goals": "Goals",
"projects": "Projects",
"templates": "Templates",
"archives": "Archive",
"inbox": "Inbox"
}
}
Write or update CLAUDE.local.md with env var exports for hooks:
## Environment Overrides
These env vars allow hooks and scripts to find your folders:
<!--
Export these in your shell profile or they'll be set by session-init:
-->
DAILY_NOTES_DIR={mapped daily notes folder}
GOALS_DIR={mapped goals folder}
PROJECTS_DIR={mapped projects folder}
TEMPLATES_DIR={mapped templates folder}
INBOX_DIR={mapped inbox folder}
ARCHIVES_DIR={mapped archives folder}
Also create .claude/hooks/adopt-env.sh that exports these variables:
#!/bin/bash
# Environment variables for adopted vault folder mapping
# Generated by /adopt — edit vault-config.json and re-run /adopt to update
export DAILY_NOTES_DIR="{mapped daily notes}"
export GOALS_DIR="{mapped goals}"
export PROJECTS_DIR="{mapped projects}"
export TEMPLATES_DIR="{mapped templates}"
export INBOX_DIR="{mapped inbox}"
export ARCHIVES_DIR="{mapped archives}"
Then add a source line to session-init.sh if not already present:
# Source adopted vault env vars if present
ADOPT_ENV="$VAULT_PATH/.claude/hooks/adopt-env.sh"
if [ -f "$ADOPT_ENV" ]; then
source "$ADOPT_ENV"
fi
Check what's missing and offer to create it. Always ask before creating.
If the goals folder is empty or newly created:
If the templates folder is empty or newly created:
If CLAUDE.local.md.template doesn't exist:
Ensure these directories exist (create silently):
.claude/skills/ (for future skill additions).claude/rules/.claude/hooks/.claude/agents/Copy standard rules files if .claude/rules/ is empty:
markdown-standards.mdproductivity-workflow.mdproject-management.mdtask-tracking.mdRun quick checks:
vault-config.json is valid JSON (read it back)CLAUDE.md is present and non-empty.claude/hooks/adopt-env.sh is present and executablePresent a summary:
Adoption complete!
Vault: /path/to/vault
Method: PARA-like (preserved your existing structure)
Mapped folders:
Daily Notes → Daily/
Goals → Goals/
Projects → Projects/
Templates → Templates/
Archives → Archive/
Inbox → Inbox/
Created:
✓ CLAUDE.md (vault context)
✓ vault-config.json (preferences)
✓ .claude/hooks/adopt-env.sh (folder mapping)
✓ Goal cascade files (4 files)
✓ Standard templates (3 files)
Your vault structure is unchanged — only configuration files were added.
Suggest what to do next:
/daily to create today's note using your vault's structure"/review for a guided weekly review"/push to commit these changes to git"CLAUDE.local.md for private preferences (not committed to git)".obsidian directory found, warn: "This doesn't look like an Obsidian vault. Continue anyway?"vault-config.json exists with adoptedVault: true, ask: "This vault was already adopted. Re-run adoption? (This will regenerate config files.)".claude/ can't be written, suggest checking permissions.md files found, suggest using /onboard with the template insteadWorks with:
/onboard — adopt replaces onboard for existing vaults/daily — uses mapped daily notes folder/weekly — uses mapped goals folder/review — respects adopted vault structure/push — commits adoption changesadopt-env.sh