refactor(vault): Phase 5 — single agent contract
- Rewrite AGENTS.md as single operations manual (PARA, permission table, frontmatter conventions, safety rules, code style) - Root CLAUDE.md = one-line pointer to AGENTS.md - Delete 13 stub CLAUDE.md files across vault directories - Delete .claude/project-instructions.md + .claude/memory/instructions/ (content merged into AGENTS.md) - .claude/settings.json: deny plugin data.json + 04_Archive + git push; ask on .obsidian/** edits; remove SessionStart hook (claudesidian welcome) - Delete 3 upstream commands (init-bootstrap, install-claudesidian, upgrade) - Add risk/writes metadata to 14 remaining commands - Rewrite README.md (remove all claudesidian content) - package.json: name → my-vault, remove check-updates/firecrawl scripts
This commit is contained in:
windyboy
@@ -1,7 +0,0 @@
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
*No recent activity*
|
||||
</claude-mem-context>
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: medium
|
||||
writes: 00-03 .md frontmatter
|
||||
|
||||
---
|
||||
description:
|
||||
Add or update YAML frontmatter properties to enhance note organization
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: low
|
||||
writes: .claude/sessions/
|
||||
|
||||
---
|
||||
allowed-tools: Read
|
||||
description: Summarize and compress conversation history to reduce token usage
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: low
|
||||
writes: .claude/commands/
|
||||
|
||||
---
|
||||
allowed-tools: Write, Read, Bash(ls:*, mkdir:*), Edit
|
||||
description: Create a new Claude Code slash command
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Daily Review
|
||||
risk: medium
|
||||
writes: 00_Inbox/ daily notes
|
||||
|
||||
Conduct an end-of-day review to capture progress and set up tomorrow.
|
||||
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: medium
|
||||
writes: note content 00-03
|
||||
|
||||
---
|
||||
allowed-tools: Read, Write, Edit
|
||||
description: Remove AI-generated jargon and restore human voice to text
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# download-attachment
|
||||
risk: low
|
||||
writes: 05_Attachments/
|
||||
|
||||
Download files from URLs to attachments folder and organize them with
|
||||
descriptive names.
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: low
|
||||
writes: none (generates text)
|
||||
|
||||
---
|
||||
allowed-tools: Bash, AskUserQuestion
|
||||
description: AI-generated git commit messages from staged changes
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Inbox Processor
|
||||
risk: medium
|
||||
writes: 00_Inbox → 01-03
|
||||
|
||||
Help organize and process items in the 00_Inbox folder according to the PARA
|
||||
method.
|
||||
|
||||
@@ -1,854 +0,0 @@
|
||||
---
|
||||
name: init-bootstrap
|
||||
description:
|
||||
Interactive setup wizard that helps new users create a personalized CLAUDE.md
|
||||
file based on their Obsidian workflow preferences
|
||||
allowed-tools: [Read, Write, MultiEdit, Bash, Task]
|
||||
argument-hint: "(optional) path to existing vault or 'new' for fresh setup"
|
||||
---
|
||||
|
||||
# Initialize Bootstrap Configuration
|
||||
|
||||
This command helps you create a personalized CLAUDE.md configuration file by
|
||||
asking questions about your Obsidian workflow and preferences.
|
||||
|
||||
## Task
|
||||
|
||||
Read the CLAUDE-BOOTSTRAP.md template and interactively gather information about
|
||||
the user's:
|
||||
|
||||
- Existing vault structure (if any)
|
||||
- Workflow preferences
|
||||
- Note-taking style
|
||||
- Organization methods
|
||||
- Specific requirements
|
||||
|
||||
Then generate a customized CLAUDE.md file tailored to their needs.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Initial Environment Setup**
|
||||
- Get current date with `date` command for timestamps
|
||||
- Check current folder name and ask if they want to rename it
|
||||
- If yes, guide them through renaming (handle parent directory move)
|
||||
- Check for package.json and install dependencies:
|
||||
- Try `pnpm install` first (faster, better)
|
||||
- Fall back to `npm install` if pnpm not available
|
||||
- Verify core dependencies are installed
|
||||
- Check git status:
|
||||
- If no .git folder: Initialize git repository
|
||||
- If has remote origin: Ask about development work
|
||||
- Personal vault: Remove origin and .github folder
|
||||
- Contributing: Keep origin and workflows intact
|
||||
- If clean local repo: Ready to go
|
||||
- Don't create folders yet - wait until after asking about organization
|
||||
method
|
||||
|
||||
2. **Check Existing Configuration**
|
||||
- Look for existing CLAUDE.md
|
||||
- If exists, ask if they want to update or start fresh
|
||||
- Check for CLAUDE-BOOTSTRAP.md template
|
||||
|
||||
3. **Gather Vault Information**
|
||||
- Search common locations for existing Obsidian vaults (.obsidian folder)
|
||||
- Check these paths with appropriate depth limits:
|
||||
- `~/Documents` (maxdepth 3) - all platforms
|
||||
- `~/Desktop` (maxdepth 3) - all platforms
|
||||
- `~/Library/Mobile Documents/iCloud~md~obsidian/Documents` (maxdepth 5 -
|
||||
**macOS only**, iCloud vaults)
|
||||
- Home directory `~/` (maxdepth 2) - all platforms
|
||||
- Current directory parent (maxdepth 2) - all platforms
|
||||
- If found, ask: "Found Obsidian vault at [path]. Is this the vault you want
|
||||
to import?"
|
||||
- Count files correctly: `find [path] -type f -name "*.md" | wc -l` (no depth
|
||||
limit)
|
||||
- Show vault size: `du -sh [path]`
|
||||
- If confirmed, analyze vault structure:
|
||||
- Run `tree -L 3 -d [path]` to see folder hierarchy
|
||||
- Sample 10-15 random notes to understand content types
|
||||
- List 30-50 recent file names to detect naming patterns
|
||||
- Check for daily notes folder and format
|
||||
- Identify most active folders by file count
|
||||
- Detect if using PARA, Zettelkasten, Johnny Decimal, or custom
|
||||
- If not the right one or none found:
|
||||
- **On macOS only:** Ask: "Is your vault stored in iCloud Drive? (yes/no)"
|
||||
- If yes (macOS): "Please enter the full path to your vault (e.g.,
|
||||
~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault)"
|
||||
- If no, or on Linux/Windows: "Please enter the path to your existing
|
||||
vault, or type 'skip' to start fresh"
|
||||
- **Validate user-provided paths** (see "User Path Validation" section
|
||||
below)
|
||||
- If no existing vault or user skips, they're starting fresh
|
||||
|
||||
4. **Ask Configuration Questions**
|
||||
- "What's your name?" (for personalization)
|
||||
- "Would you like me to research your public work to better understand your
|
||||
context?"
|
||||
- If yes: Search for information
|
||||
- ALWAYS show findings and ask "Is this correct?" for confirmation
|
||||
- If multiple people found, list them numbered for selection
|
||||
- If wrong person, offer to search again or skip
|
||||
- Save relevant context about their work, writing style, areas of expertise
|
||||
- "Do you follow the PARA method or have a different organization system?"
|
||||
- "What are your main use cases? (research, writing, project management,
|
||||
knowledge base, daily notes)"
|
||||
|
||||
**If using PARA, ask specific setup questions:**
|
||||
[PARA Method by Tiago Forte](https://fortelabs.com/blog/para/)
|
||||
- "What active projects are you working on?" (Create folders in 01_Projects)
|
||||
- "What areas of responsibility do you maintain?" (e.g., Work, Health,
|
||||
Finance, Family)
|
||||
- "What topics do you research frequently?" (Set up in 03_Resources)
|
||||
- "Any projects you recently completed?" (Can archive with summaries)
|
||||
|
||||
**General preferences:**
|
||||
- Check .obsidian/community-plugins.json to see what plugins they use
|
||||
- Analyze existing files to detect naming convention automatically
|
||||
- Check for attachments folder to see if they work with media files
|
||||
- "Do you use git for version control?"
|
||||
- "Any specific websites or resources you reference often?"
|
||||
- "Do you have any specific writing style preferences?"
|
||||
- "Are there any workflows or patterns you want Claude to follow?"
|
||||
- "Would you like a weekly review ritual? (e.g., Thursday project review)"
|
||||
- "Do you prefer 'thinking mode' (questions/exploration) vs 'writing mode'?"
|
||||
|
||||
5. **Optional Tool Setup**
|
||||
|
||||
**Gemini Vision (already included)**
|
||||
- Ask: "Gemini Vision is already included for analyzing images, PDFs, and
|
||||
videos. Would you like to activate it? (yes/no/later)"
|
||||
- Explain: "You just need a free API key from Google. This lets Claude
|
||||
analyze any visual content in your vault."
|
||||
- If later: "No problem! You can set it up anytime by running
|
||||
`/setup-gemini`"
|
||||
- If yes:
|
||||
- Guide to get API key from https://aistudio.google.com/apikey (free, takes
|
||||
30 seconds)
|
||||
- Help add to shell profile (.zshrc, .bashrc, etc.)
|
||||
- Run
|
||||
`claude mcp add --scope project gemini-vision node .claude/mcp-servers/gemini-vision.mjs`
|
||||
- Configure .mcp.json with API key
|
||||
- Test the connection with a sample command
|
||||
|
||||
**Firecrawl (already included)**
|
||||
- Ask: "Firecrawl is included for web research. Would you like to set it up?
|
||||
(yes/no/later)"
|
||||
- Explain: "This is a game-changer for research! When you find an article or
|
||||
website, you can save it directly to your vault as markdown - preserving
|
||||
the content forever, making it searchable, and letting Claude analyze it.
|
||||
Perfect for building a research library."
|
||||
- Example: "Just tell Claude: 'Save this article to my vault: [URL]' and it's
|
||||
done!"
|
||||
- If later: "You can set it up anytime by running `/setup-firecrawl`"
|
||||
- If yes:
|
||||
- Guide to get API key from https://firecrawl.dev (free tier available)
|
||||
- Help configure the scripts in .scripts/
|
||||
- Show example usage: `.scripts/firecrawl-scrape.sh https://example.com`
|
||||
|
||||
6. **Generate Custom Configuration**
|
||||
- Get current date: `date +"%B %d, %Y"` for the CLAUDE.md header
|
||||
- Save preferences to `.claude/vault-config.json`:
|
||||
```json
|
||||
{
|
||||
"user": {
|
||||
"name": "Jane Smith",
|
||||
"background": {
|
||||
"companies": ["Variance", "Percolate"],
|
||||
"roles": ["Co-founder", "Writer"],
|
||||
"publications": ["Why Is This Interesting?", "every.to"],
|
||||
"expertise": [
|
||||
"Developer tools",
|
||||
"Marketing tech",
|
||||
"Systems thinking"
|
||||
],
|
||||
"interests": ["AI for thinking", "Note-taking systems", "Creativity"]
|
||||
},
|
||||
"profileSources": [
|
||||
"https://whyisthisinteresting.com/about",
|
||||
"https://every.to/@username"
|
||||
],
|
||||
"customContext": "Focuses on AI as thinking augmentation, not just writing",
|
||||
"publicProfile": true
|
||||
},
|
||||
"vaultPath": "/path/to/existing/vault",
|
||||
"fileNamingPattern": "detected-pattern",
|
||||
"organizationMethod": "PARA",
|
||||
"primaryUses": ["research", "writing", "projects"],
|
||||
"tools": {
|
||||
"geminiVision": true,
|
||||
"firecrawl": false
|
||||
},
|
||||
"projects": ["Book - Productivity", "SaaS App"],
|
||||
"areas": ["Newsletter", "Health"],
|
||||
"importedAt": "2025-01-13",
|
||||
"lastUpdated": "2025-01-13"
|
||||
}
|
||||
```
|
||||
- Start with CLAUDE-BOOTSTRAP.md as base
|
||||
- Add user-specific sections:
|
||||
- Custom folder structure with their actual projects/areas
|
||||
- Personal workflows
|
||||
- Preferred tools and scripts
|
||||
- Specific guidelines
|
||||
- MCP configuration if set up
|
||||
- Include their websites/resources if provided
|
||||
- Add any custom naming conventions
|
||||
- Pre-populate with their projects and areas:
|
||||
- Create project folders in 01_Projects/
|
||||
- Create area folders in 02_Areas/
|
||||
- Create resource topics in 03_Resources/
|
||||
- Add README files explaining each project/area
|
||||
|
||||
7. **Import Existing Vault (if applicable)**
|
||||
- If user has existing vault:
|
||||
- Create OLD_VAULT folder: `mkdir OLD_VAULT`
|
||||
- Copy entire vault preserving structure:
|
||||
`cp -r [vault-path]/* ./OLD_VAULT/`
|
||||
- Copy Obsidian configuration: `cp -r [vault-path]/.obsidian ./`
|
||||
- Check for and copy other important files:
|
||||
- `.trash/` (Obsidian's trash folder)
|
||||
- `.smart-connections/` (if using that plugin)
|
||||
- Any workspace files: `.obsidian.vimrc`, etc.
|
||||
- Skip copying: `.git/` (they'll have their own), `.claude/` (using ours)
|
||||
- Show summary: "Imported your vault to OLD_VAULT/ (X files, Y folders)"
|
||||
- Explain: "Your original structure is preserved in OLD_VAULT. You can
|
||||
gradually migrate files to the PARA folders as needed."
|
||||
|
||||
8. **Create Supporting Files**
|
||||
- Generate initial folder structure if new vault
|
||||
- Create README files for main folders
|
||||
- For each project folder, create subfolders:
|
||||
- Research/ (source materials)
|
||||
- Chats/ (AI conversations)
|
||||
- Daily Progress/ (running log)
|
||||
- Create 05_Attachments/Organized/ directory
|
||||
- Set up .gitignore if using git (include .mcp.json, node_modules)
|
||||
- Create initial templates if requested
|
||||
- Create WEEKLY_REVIEW.md if user wants review ritual
|
||||
- Remove FIRST_RUN marker file if it exists
|
||||
- Make initial git commit if repository was initialized
|
||||
|
||||
9. **Run Test Commands**
|
||||
- Execute `pnpm vault:stats` to verify scripts work
|
||||
- Test attachment commands if folders exist
|
||||
- Test MCP tools if configured
|
||||
- Verify git is tracking files correctly
|
||||
|
||||
10. **Provide Next Steps**
|
||||
|
||||
- Summary of what was created and configured
|
||||
- Quick start guide specific to their setup
|
||||
- List of available commands they can use
|
||||
- Test commands to verify everything works
|
||||
- Suggestions for first tasks based on their use cases
|
||||
- How to modify configuration later
|
||||
|
||||
## Example Output
|
||||
|
||||
```markdown
|
||||
# Your Obsidian Vault Configuration
|
||||
|
||||
Generated on: [Run `date +"%B %d, %Y"` to get current date] Last updated: [Same
|
||||
date] Based on your preferences for: [main use cases] Setup completed with: ✅
|
||||
Dependencies ✅ Folder structure ✅ Git initialized
|
||||
|
||||
## Your Custom Folder Structure
|
||||
|
||||
[Their specific structure with explanations]
|
||||
|
||||
## Your Workflows
|
||||
|
||||
### Daily Routine
|
||||
|
||||
[Based on their answers]
|
||||
|
||||
### Project Management
|
||||
|
||||
[Their specific approach]
|
||||
|
||||
### Research Method (Noah Brier Style)
|
||||
|
||||
- Capture everything you read
|
||||
- Let important ideas naturally resurface
|
||||
- Start with writing to test understanding
|
||||
- Use search, not tags, to find things
|
||||
- [Learn more from Noah's system](https://every.to/superorganizers/ceo-by-day-internet-sleuth-by-night-267452)
|
||||
|
||||
### Weekly Review Ritual
|
||||
|
||||
[If enabled: Every Thursday at 4pm, review all projects]
|
||||
|
||||
## Your Preferences
|
||||
|
||||
### File Naming
|
||||
|
||||
- Pattern: [their convention]
|
||||
- Examples: [specific examples]
|
||||
|
||||
### Tools & Scripts
|
||||
|
||||
[Relevant scripts for their workflow]
|
||||
|
||||
## MCP Servers (if configured)
|
||||
|
||||
### Gemini Vision
|
||||
|
||||
- Status: ✅ Configured and tested
|
||||
- API Key: Set in .mcp.json
|
||||
- Test with: `Use gemini-vision to analyze [image path]`
|
||||
|
||||
## Available Commands
|
||||
|
||||
### Vault Management
|
||||
|
||||
- `pnpm vault:stats` - Show vault statistics
|
||||
- `pnpm attachments:list` - List unprocessed attachments
|
||||
- `pnpm attachments:organized` - Count organized files
|
||||
|
||||
### Claude Commands
|
||||
|
||||
- `claude run thinking-partner` - Collaborative thinking mode
|
||||
- `claude run daily-review` - Review your day
|
||||
- `claude run init-bootstrap` - Re-run this setup
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. [Personalized first step]
|
||||
2. [Next action based on their goals]
|
||||
3. [Specific to their workflow]
|
||||
|
||||
## Pro Tips from Research Masters
|
||||
|
||||
- **Be a token maximalist**: Provide lots of context to Claude
|
||||
- **Writing scales**: Document everything for future reference
|
||||
([Noah Brier](https://every.to/superorganizers/ceo-by-day-internet-sleuth-by-night-267452))
|
||||
- **Trust emergence**: Important ideas will keep surfacing
|
||||
- **Start with writing**: Always begin projects in text form
|
||||
- **Review regularly**: Set aside time weekly to prune and update
|
||||
- **PARA Method**: Projects, Areas, Resources, Archive
|
||||
([Tiago Forte](https://fortelabs.com/blog/para/))
|
||||
|
||||
## Setup Summary
|
||||
|
||||
✅ Dependencies installed (pnpm/npm) ✅ Folder structure created ✅ Git
|
||||
repository initialized and disconnected from original ✅ CLAUDE.md personalized
|
||||
✅ First-run setup completed [✅ MCP Gemini Vision configured - if set up] [✅
|
||||
First commit made - if git was initialized]
|
||||
```
|
||||
|
||||
## Important Implementation Notes
|
||||
|
||||
### Handling Multiple Vaults
|
||||
|
||||
When multiple vaults are detected:
|
||||
|
||||
1. **Always list all vaults found** with clear numbering and details
|
||||
2. **Require explicit selection** - don't assume which vault to use
|
||||
3. **Confirm the selection** before proceeding with import
|
||||
4. **Handle ambiguous responses** - if user provides unclear input (like pasting
|
||||
a screenshot), ask for clarification:
|
||||
- "I see you've shared a screenshot. Could you please type the number (1-3)
|
||||
of the vault you'd like to import?"
|
||||
- "I need a clear selection. Please type '1', '2', or '3' to choose a vault,
|
||||
or 'skip' to start fresh."
|
||||
|
||||
### Never Proceed Without Clear Confirmation
|
||||
|
||||
If the user's response is unclear:
|
||||
|
||||
- Don't guess or assume
|
||||
- Ask for explicit confirmation
|
||||
- Provide clear options again
|
||||
- Example: "I want to make sure I import the right vault. Please type the number
|
||||
of your choice (1, 2, or 3)."
|
||||
|
||||
### Platform Compatibility
|
||||
|
||||
This command is designed to work across Linux, macOS, and Windows (WSL/Git
|
||||
Bash), with platform-specific features:
|
||||
|
||||
**All Platforms:**
|
||||
|
||||
- Search ~/Documents, ~/Desktop, home directory
|
||||
- Standard Obsidian vault detection
|
||||
- Full vault import and setup
|
||||
|
||||
**macOS Only:**
|
||||
|
||||
- iCloud Drive vault detection and import
|
||||
- Obsidian's iCloud sync is macOS-only, so iCloud features are disabled on other
|
||||
platforms
|
||||
|
||||
**Platform Detection:**
|
||||
|
||||
```bash
|
||||
# Check platform
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
# macOS - enable iCloud features
|
||||
PLATFORM="macOS"
|
||||
ICLOUD_SUPPORTED=true
|
||||
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
|
||||
# Linux
|
||||
PLATFORM="Linux"
|
||||
ICLOUD_SUPPORTED=false
|
||||
elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then
|
||||
# Windows (Git Bash or WSL)
|
||||
PLATFORM="Windows"
|
||||
ICLOUD_SUPPORTED=false
|
||||
fi
|
||||
```
|
||||
|
||||
### iCloud Vault Search Implementation
|
||||
|
||||
When searching for vaults, use this find command pattern:
|
||||
|
||||
```bash
|
||||
# Standard locations (shallow search)
|
||||
# Note: 2>/dev/null suppresses expected permission errors from system directories
|
||||
# If no vaults are found, we'll ask the user for their vault path
|
||||
find ~/Documents ~/Desktop -maxdepth 3 -type d -name ".obsidian" 2>/dev/null
|
||||
|
||||
# iCloud location (deeper search needed due to nested structure)
|
||||
# Only search on macOS
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
find ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents -maxdepth 5 -type d -name ".obsidian" 2>/dev/null
|
||||
fi
|
||||
|
||||
# Home directory (shallow to avoid deep recursion)
|
||||
find ~ -maxdepth 2 -type d -name ".obsidian" 2>/dev/null
|
||||
```
|
||||
|
||||
The iCloud path requires:
|
||||
|
||||
- Higher maxdepth (5) due to nested folder structure
|
||||
- Escaped spaces in path name
|
||||
- Silent error handling (2>/dev/null) as many users won't have iCloud
|
||||
- Platform check (macOS only)
|
||||
|
||||
**Error Handling Note:** Permission errors are suppressed (2>/dev/null) because
|
||||
they're expected when searching system directories. If no vaults are found, the
|
||||
script gracefully prompts the user for their vault path.
|
||||
|
||||
### User Path Validation
|
||||
|
||||
When users manually provide a vault path, validate it thoroughly with helpful
|
||||
error messages:
|
||||
|
||||
```bash
|
||||
# User provided path
|
||||
USER_PATH="$1"
|
||||
|
||||
# Expand tilde and resolve to absolute path
|
||||
USER_PATH="${USER_PATH/#\~/$HOME}"
|
||||
REAL_PATH=$(realpath "$USER_PATH" 2>/dev/null)
|
||||
|
||||
# Validation 1: Path exists
|
||||
if [ -z "$REAL_PATH" ]; then
|
||||
echo "❌ Error: Path does not exist: $USER_PATH"
|
||||
echo ""
|
||||
echo "💡 Suggestions:"
|
||||
echo " • Check for typos in the path"
|
||||
echo " • Make sure you're using the full path (e.g., /Users/name/vault)"
|
||||
echo " • You can use ~ for your home directory (e.g., ~/Documents/vault)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validation 2: Is a directory
|
||||
if [ ! -d "$REAL_PATH" ]; then
|
||||
echo "❌ Error: Not a directory: $REAL_PATH"
|
||||
echo ""
|
||||
echo "💡 The path exists but points to a file, not a folder."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validation 3: Contains .obsidian folder
|
||||
if [ ! -d "$REAL_PATH/.obsidian" ]; then
|
||||
echo "❌ Error: Not a valid Obsidian vault (no .obsidian folder)"
|
||||
echo " Looking in: $REAL_PATH"
|
||||
echo ""
|
||||
echo "💡 Suggestions:"
|
||||
echo " • Make sure the path points to your vault root (not a subfolder)"
|
||||
echo " • Check that you've opened this vault in Obsidian at least once"
|
||||
echo " • Try the path without trailing slash"
|
||||
echo " • For iCloud: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validation 4: Readable permissions
|
||||
if [ ! -r "$REAL_PATH/.obsidian" ]; then
|
||||
echo "❌ Error: Cannot read vault directory (permission denied)"
|
||||
echo " Path: $REAL_PATH"
|
||||
echo ""
|
||||
echo "💡 You may need to:"
|
||||
echo " • Check file permissions with: ls -la \"$REAL_PATH\""
|
||||
echo " • Make sure you own this directory"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Show resolved path if different from input
|
||||
if [ "$USER_PATH" != "$REAL_PATH" ]; then
|
||||
echo "✓ Resolved path: $REAL_PATH"
|
||||
fi
|
||||
|
||||
# Valid vault path
|
||||
VAULT_PATH="$REAL_PATH"
|
||||
echo "✓ Valid Obsidian vault found"
|
||||
```
|
||||
|
||||
This validation:
|
||||
|
||||
- Expands `~` to home directory properly
|
||||
- Resolves symlinks and relative paths to absolute paths
|
||||
- Checks all essential requirements (exists, is directory, has .obsidian,
|
||||
readable)
|
||||
- Provides helpful, actionable error messages with suggestions
|
||||
- Shows the resolved path so users understand what's being checked
|
||||
- Trusts users (allows symlinks, paths outside home directory)
|
||||
- Cross-platform compatible (works on Linux, macOS, Windows/WSL)
|
||||
|
||||
### iCloud Sync State Checking
|
||||
|
||||
When a user selects an iCloud vault, check sync state and warn if needed:
|
||||
|
||||
```bash
|
||||
# After user confirms vault selection
|
||||
if [[ "$OSTYPE" == "darwin"* ]] && [[ "$vault_path" == *"iCloud"* ]]; then
|
||||
# Check for common iCloud sync indicators
|
||||
if [ -f "$vault_path/.icloud" ] || [ -f "$vault_path/.obsidian/.icloud" ]; then
|
||||
echo ""
|
||||
echo "📱 iCloud Sync Notice:"
|
||||
echo " This vault appears to be still downloading from iCloud."
|
||||
echo " For best results, open it in Obsidian first to ensure files are synced."
|
||||
echo ""
|
||||
read -p "Continue anyway? (yes/no): " sync_answer
|
||||
if [[ ! "$sync_answer" =~ ^[Yy] ]]; then
|
||||
echo "No problem! Open the vault in Obsidian, then re-run /init-bootstrap"
|
||||
exit 0
|
||||
fi
|
||||
else
|
||||
echo ""
|
||||
echo "📱 iCloud vault detected. If import seems incomplete, make sure sync is complete."
|
||||
echo ""
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
This provides a soft warning that:
|
||||
|
||||
- Only runs on macOS for iCloud paths
|
||||
- Checks for placeholder files that indicate incomplete download
|
||||
- Asks for confirmation if sync issues detected
|
||||
- Gives gentle reminder even when no issues found
|
||||
- Lets users proceed if they choose
|
||||
|
||||
## Interactive Example
|
||||
|
||||
````
|
||||
User: claude run init-bootstrap
|
||||
Assistant: Welcome! I'll help you set up your personalized Obsidian + Claude configuration.
|
||||
|
||||
📅 Today's date: [Gets from `date +"%B %d, %Y"`]
|
||||
|
||||
First, let me check your setup...
|
||||
|
||||
📁 **Folder Name Check**
|
||||
Current folder: claudesidian
|
||||
Would you like to rename this folder to something more personal? (e.g., my-vault, knowledge-base, obsidian-notes)
|
||||
*Why: Your vault should have a name that makes sense to you - you'll see it every day!*
|
||||
|
||||
[If yes: Handles the rename by moving to parent directory and back]
|
||||
|
||||
Now setting up your environment...
|
||||
|
||||
📦 **Installing Dependencies**
|
||||
[Checks for pnpm, uses npm if not available]
|
||||
[Installs dependencies with pnpm/npm]
|
||||
*Why: These tools enable Claude Code to work with your vault effectively*
|
||||
|
||||
🔓 **Repository Setup**
|
||||
|
||||
**Will you be contributing to claudesidian development?**
|
||||
- **No** (Personal vault only) → I'll remove GitHub workflows and disconnect from the repo
|
||||
- **Yes** (I want to contribute) → I'll keep the development setup intact
|
||||
|
||||
[Implementation:]
|
||||
```bash
|
||||
# If user says "No" (personal vault):
|
||||
rm -rf .github # Remove GitHub workflows
|
||||
git remote remove origin # Disconnect from claudesidian repo
|
||||
|
||||
# If user says "Yes" (contributing):
|
||||
# Keep .github folder and origin remote
|
||||
echo "Development setup preserved for contributing"
|
||||
````
|
||||
|
||||
_Why: Personal vaults don't need GitHub Actions, but contributors benefit from
|
||||
the automation_
|
||||
|
||||
📂 **Creating Folder Structure** [Creates folders based on your chosen
|
||||
organization method] _Why: A good structure helps you organize and find your
|
||||
knowledge effectively_
|
||||
|
||||
🎯 **Finalizing Setup** [Checks git status and removes first-run marker] _Why:
|
||||
Git gives you version control, and removing the marker ensures you won't see the
|
||||
welcome message again_
|
||||
|
||||
✅ Folder renamed (if requested) ✅ Dependencies installed ✅ Core folders
|
||||
created ✅ Git repository ready (disconnected from original claudesidian) ✅
|
||||
First-run marker removed
|
||||
|
||||
Now let me ask you a few questions to customize your setup:
|
||||
|
||||
🔍 **Searching for existing Obsidian vaults...** [Searches ~/Documents,
|
||||
~/Desktop, home directory, and parent directories. On macOS, also searches
|
||||
iCloud Drive]
|
||||
|
||||
### Case 1: Single Vault Found
|
||||
|
||||
Found Obsidian vault at: ~/Documents/MyNotes 📊 Vault stats: 2,517 markdown
|
||||
files, 1.1GB total size Would you like to import this vault?
|
||||
|
||||
- **yes** - Import this vault
|
||||
- **no** - Search for a different vault
|
||||
- **skip** - Start fresh without importing
|
||||
- **path** - Specify a different path manually
|
||||
|
||||
User: yes
|
||||
|
||||
### Case 2: Multiple Vaults Found
|
||||
|
||||
🔍 **Found multiple Obsidian vaults:**
|
||||
|
||||
1. **~/Documents/MyNotes** (2,517 files, 1.1GB)
|
||||
- Last modified: 2 hours ago
|
||||
- Contains: Daily notes, projects, resources
|
||||
|
||||
2. **~/Desktop/WorkVault** (892 files, 450MB)
|
||||
- Last modified: 3 days ago
|
||||
- Contains: Client projects, meeting notes
|
||||
|
||||
3. **~/Documents/ObsidianVault** (156 files, 23MB)
|
||||
- Last modified: 2 weeks ago
|
||||
- Contains: Personal notes, drafts
|
||||
|
||||
**Which vault would you like to import?**
|
||||
|
||||
- Enter **1-3** to select a vault
|
||||
- **all** - Import all vaults (each to a separate folder)
|
||||
- **skip** - Start fresh without importing
|
||||
- **path** - Specify a different path manually
|
||||
|
||||
User: 1
|
||||
|
||||
**Confirming your selection:** You selected: ~/Documents/MyNotes (2,517 files,
|
||||
1.1GB)
|
||||
|
||||
Is this correct? (yes/no)
|
||||
|
||||
User: yes
|
||||
|
||||
Great! I'll import your vault to OLD_VAULT/ where it will be safely preserved.
|
||||
You can migrate files to the PARA folders at your own pace.
|
||||
|
||||
### Case 3: No Vaults Found (Platform-Aware)
|
||||
|
||||
🔍 **No Obsidian vaults found in common locations.**
|
||||
|
||||
**On macOS:** Is your vault stored in iCloud Drive? (yes/no)
|
||||
|
||||
User: yes
|
||||
|
||||
Please enter the full path to your vault: (Example: ~/Library/Mobile
|
||||
Documents/iCloud~md~obsidian/Documents/YourVault)
|
||||
|
||||
User: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault
|
||||
|
||||
[Validates path and shows vault stats]
|
||||
|
||||
Found vault at: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault
|
||||
📊 Vault stats: 1,248 markdown files, 523MB total size
|
||||
|
||||
Would you like to import this vault? (yes/skip)
|
||||
|
||||
**On Linux/Windows:** Please enter the path to your existing Obsidian vault, or
|
||||
type 'skip' to start fresh: (Example: ~/Documents/MyVault or
|
||||
/home/user/obsidian-vault)
|
||||
|
||||
User: ~/Documents/MyVault
|
||||
|
||||
[Validates path and shows vault stats]
|
||||
|
||||
Found vault at: ~/Documents/MyVault 📊 Vault stats: 1,248 markdown files, 523MB
|
||||
total size
|
||||
|
||||
Would you like to import this vault? (yes/skip)
|
||||
|
||||
📦 **Analyzing your vault structure...** [Running tree to see folder hierarchy]
|
||||
[Sampling notes to understand content] [Detecting naming patterns from recent
|
||||
files]
|
||||
|
||||
I can see you're using:
|
||||
|
||||
- A modified PARA structure with custom folders
|
||||
- Date-prefixed files for daily notes (YYYY-MM-DD)
|
||||
- Project folders with nested research
|
||||
- Heavy use of the Resources folder for reference material
|
||||
|
||||
📦 **Importing your vault...** [Copying files to OLD_VAULT/] [Preserving
|
||||
.obsidian settings] [Checking for plugin folders]
|
||||
|
||||
✅ Imported 2,517 files (1.1GB) to OLD_VAULT/ Your original structure is
|
||||
completely preserved!
|
||||
|
||||
Now let's personalize your setup:
|
||||
|
||||
1. **What's your name?**
|
||||
|
||||
_Why I'm asking:_ I'll use this to personalize your CLAUDE.md file and help
|
||||
me understand your context better. This creates a more tailored experience
|
||||
where I can reference your work and interests naturally.
|
||||
|
||||
User: Noah Brier
|
||||
|
||||
2. **Would you like me to research your public work?**
|
||||
|
||||
_Why this helps:_ By understanding your background, expertise, and interests,
|
||||
I can:
|
||||
- Tailor suggestions to your specific field and workflow
|
||||
- Reference relevant examples from your domain
|
||||
- Better understand the context of your questions
|
||||
- Build a profile that helps me be a more effective thinking partner
|
||||
|
||||
User: Yes
|
||||
|
||||
Great! To make sure I find information about the real you, could you provide any
|
||||
of these details?
|
||||
|
||||
- Your company or organization
|
||||
- Your location (city/country)
|
||||
- A unique project you've worked on
|
||||
- Your website or social media handle
|
||||
- Any other distinguishing information
|
||||
|
||||
This helps me avoid confusion with others who share your name.
|
||||
|
||||
User: I co-founded Variance and Percolate, I write at every.to
|
||||
|
||||
Perfect! Let me search for you with those details...
|
||||
|
||||
[Searches for information using the provided identifying information]
|
||||
|
||||
Based on your details, I found you - Noah Brier, co-founder of Variance and
|
||||
Percolate, writer at every.to.
|
||||
|
||||
Let me confirm this is correct:
|
||||
|
||||
- Co-founded Variance (developer tools) and Percolate (marketing software)
|
||||
- Write at every.to and Why Is This Interesting? newsletter
|
||||
- Focus on systems thinking, creativity, and technology
|
||||
|
||||
Is this you? (yes/no)
|
||||
|
||||
User: yes
|
||||
|
||||
Excellent! I've identified the right profile.
|
||||
|
||||
**Building Your Profile** Would you like me to read any specific pages to better
|
||||
understand your work?
|
||||
|
||||
- Your personal website or blog
|
||||
- Recent articles or papers you've written
|
||||
- Company/project pages
|
||||
- LinkedIn or other profiles
|
||||
|
||||
Enter URLs (comma-separated) or 'skip' to continue:
|
||||
|
||||
User: https://whyisthisinteresting.com/about, https://every.to/@noahbrier
|
||||
|
||||
[Fetches and analyzes the provided URLs]
|
||||
|
||||
I've built a comprehensive profile:
|
||||
|
||||
- You co-founded Variance (developer tools) and Percolate (marketing software)
|
||||
- You write Why Is This Interesting? newsletter with Colin Nagy
|
||||
- You explore creativity, technology, and systems thinking
|
||||
- You've written about writing as thinking, note-taking systems, and AI
|
||||
|
||||
Is there anything else I should know about your work or interests?
|
||||
|
||||
User: I'm really interested in how AI can augment thinking, not just writing
|
||||
|
||||
Got it! I'll remember that you focus on AI as a thinking tool, not just a
|
||||
writing assistant.
|
||||
|
||||
3. **What will you primarily use this vault for?** (research, writing, project
|
||||
management, daily notes, knowledge base, or combination?)
|
||||
|
||||
User: I'll use it for research and writing, plus managing client projects
|
||||
|
||||
Assistant: Great! I'll configure your vault for research, writing, and client
|
||||
project management.
|
||||
|
||||
2. **What specific projects are you currently working on?** (I'll create folders
|
||||
for each in 01_Projects)
|
||||
|
||||
User: I'm writing a book about productivity systems, building a SaaS app, and
|
||||
planning a conference talk
|
||||
|
||||
Assistant: Perfect! I'll set up project folders for:
|
||||
|
||||
- 01_Projects/Book - Productivity Systems/
|
||||
- 01_Projects/SaaS App Development/
|
||||
- 01_Projects/Conference Talk/
|
||||
|
||||
3. **What ongoing areas of responsibility do you maintain?** (These go in
|
||||
02_Areas - things without an end date)
|
||||
|
||||
User: My newsletter, health & fitness, personal finances, and family activities
|
||||
|
||||
Assistant: I'll create area folders for:
|
||||
|
||||
- 02_Areas/Newsletter/
|
||||
- 02_Areas/Health & Fitness/
|
||||
- 02_Areas/Finances/
|
||||
- 02_Areas/Family/
|
||||
|
||||
4. **What topics do you frequently research or reference?** (I'll organize these
|
||||
in 03_Resources)
|
||||
|
||||
User: AI tools, productivity methods, SaaS metrics, and writing techniques
|
||||
|
||||
Assistant: Setting up resource folders for:
|
||||
|
||||
- 03_Resources/AI Tools/
|
||||
- 03_Resources/Productivity Methods/
|
||||
- 03_Resources/SaaS Metrics/
|
||||
- 03_Resources/Writing Techniques/
|
||||
|
||||
[Continues with questions...]
|
||||
|
||||
**Gemini Vision Setup** Gemini Vision is already included in claudesidian! It
|
||||
can analyze images, PDFs, and videos in your vault. To activate it, you just
|
||||
need a free Google API key (takes 30 seconds). Would you like to set it up now?
|
||||
(yes/no/later)
|
||||
|
||||
User: later
|
||||
|
||||
No problem! You can set it up anytime by running `/setup-gemini` when you're
|
||||
ready.
|
||||
|
||||
**Firecrawl Setup** Firecrawl is a game-changer for research! Save any article
|
||||
or website directly to your vault as markdown. Perfect for building a permanent,
|
||||
searchable research library. Would you like to set it up? (yes/no/later)
|
||||
|
||||
User: yes
|
||||
|
||||
Great choice! Firecrawl will transform how you collect research.
|
||||
|
||||
Assistant: Excellent! Here's how to get your API key:
|
||||
|
||||
1. Go to https://aistudio.google.com/apikey
|
||||
2. Click "Create API Key"
|
||||
3. Copy the key (starts with AIzaSy...)
|
||||
|
||||
Once you have it, paste it here and I'll configure everything for you.
|
||||
@@ -1,343 +0,0 @@
|
||||
---
|
||||
allowed-tools: [Read, Write, Bash]
|
||||
description: Install claudesidian shell command to launch Claude Code from anywhere
|
||||
argument-hint: (optional shell: bash/zsh/fish)
|
||||
---
|
||||
|
||||
# Install Claudesidian Command
|
||||
|
||||
Creates a shell alias/function that allows you to run `claudesidian` from
|
||||
anywhere to open your vault in Claude Code.
|
||||
|
||||
## Task
|
||||
|
||||
Install a shell command that:
|
||||
|
||||
1. Changes to your claudesidian vault directory
|
||||
2. Launches Claude Code
|
||||
3. Works from any directory in your terminal
|
||||
|
||||
Similar to having a quick launcher for your vault.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. **Detect Current Setup**
|
||||
|
||||
- Check which shell the user is using (bash/zsh/fish)
|
||||
- Find the current working directory (vault path)
|
||||
- Determine the appropriate config file
|
||||
|
||||
### 2. **Create the Command**
|
||||
|
||||
The command will be an alias that:
|
||||
|
||||
- Changes to the vault directory: `cd /path/to/your/vault`
|
||||
- Tries to resume existing session: `claude --resume 2>/dev/null`
|
||||
- Falls back to new session if no existing one: `|| claude`
|
||||
- All in one command with properly escaped path:
|
||||
`(cd "/path/to/vault" && (claude --resume 2>/dev/null || claude))`
|
||||
|
||||
**Important:** The path must be properly escaped to handle spaces and special
|
||||
characters.
|
||||
|
||||
This automatically enters resume mode if there's an existing session, or starts
|
||||
a new one if not.
|
||||
|
||||
### 3. **Install to Shell Config**
|
||||
|
||||
Add the alias to the appropriate config file:
|
||||
|
||||
- **Bash**: `~/.bashrc` or `~/.bash_profile`
|
||||
- **Zsh**: `~/.zshrc`
|
||||
- **Fish**: `~/.config/fish/config.fish`
|
||||
|
||||
### 4. **Verify Installation**
|
||||
|
||||
- Show the added line
|
||||
- Remind user to reload their shell or source the config
|
||||
- Provide test command
|
||||
|
||||
## Shell Detection
|
||||
|
||||
Detects the user's default shell, with support for command-line override:
|
||||
|
||||
```bash
|
||||
# Check if shell specified as argument (/install-claudesidian-command zsh)
|
||||
if [ -n "$1" ]; then
|
||||
# User provided shell type as argument
|
||||
SHELL_TYPE="$1"
|
||||
else
|
||||
# Auto-detect from $SHELL (user's default shell, not current shell)
|
||||
SHELL_TYPE=$(basename "$SHELL")
|
||||
fi
|
||||
|
||||
# Validate shell type and set appropriate config file
|
||||
case "$SHELL_TYPE" in
|
||||
zsh)
|
||||
CONFIG_FILE="$HOME/.zshrc"
|
||||
;;
|
||||
bash)
|
||||
# Prefer .bashrc on Linux, .bash_profile on macOS
|
||||
if [ -f "$HOME/.bashrc" ]; then
|
||||
CONFIG_FILE="$HOME/.bashrc"
|
||||
else
|
||||
CONFIG_FILE="$HOME/.bash_profile"
|
||||
fi
|
||||
;;
|
||||
fish)
|
||||
CONFIG_FILE="$HOME/.config/fish/config.fish"
|
||||
;;
|
||||
*)
|
||||
echo "❌ Unsupported shell: $SHELL_TYPE"
|
||||
echo " Supported shells: bash, zsh, fish"
|
||||
echo " Usage: /install-claudesidian-command [bash|zsh|fish]"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "🐚 Installing for: $SHELL_TYPE"
|
||||
echo "📝 Config file: $CONFIG_FILE"
|
||||
```
|
||||
|
||||
**Key improvements:**
|
||||
|
||||
- Uses `$SHELL` to detect default shell (not `$ZSH_VERSION`/`$BASH_VERSION`
|
||||
which detect current session)
|
||||
- Supports command-line argument to override auto-detection
|
||||
- Shows detected shell and config file for transparency
|
||||
- Validates shell type and provides clear error message for unsupported shells
|
||||
|
||||
## Installation Steps
|
||||
|
||||
1. **Detect shell**: Use argument if provided, otherwise auto-detect from
|
||||
`$SHELL`
|
||||
2. **Get vault path**: Use `pwd` to get current directory
|
||||
3. **Escape the path**: Properly escape quotes and special characters for shell
|
||||
safety
|
||||
```bash
|
||||
# Escape any double quotes in the path
|
||||
ESCAPED_PATH="${VAULT_PATH//\"/\\\"}"
|
||||
# Also escape backslashes
|
||||
ESCAPED_PATH="${ESCAPED_PATH//\\/\\\\}"
|
||||
```
|
||||
4. **Check if already installed**: Search config file for existing
|
||||
`claudesidian` alias/function
|
||||
```bash
|
||||
# Check for existing alias/function
|
||||
if grep -q "alias claudesidian\|function claudesidian" "$CONFIG_FILE"; then
|
||||
echo "⚠️ Found existing claudesidian command:"
|
||||
grep -A 3 "claudesidian" "$CONFIG_FILE"
|
||||
echo ""
|
||||
read -p "Replace it? (yes/no): " replace_answer
|
||||
if [[ ! "$replace_answer" =~ ^[Yy] ]]; then
|
||||
echo "Installation cancelled. Existing command preserved."
|
||||
exit 0
|
||||
fi
|
||||
# Mark for replacement (will remove before adding new one)
|
||||
REPLACING=true
|
||||
fi
|
||||
```
|
||||
5. **Get user confirmation**: Show what will be added and get final confirmation
|
||||
6. **Create backup**: Only if proceeding with modification
|
||||
```bash
|
||||
# Create backup with timestamp
|
||||
BACKUP_FILE="$CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)"
|
||||
cp "$CONFIG_FILE" "$BACKUP_FILE"
|
||||
echo "💾 Backup created: $BACKUP_FILE"
|
||||
```
|
||||
7. **Build the safe alias/function command**: Use the escaped path from step 3
|
||||
```bash
|
||||
# CRITICAL: Use $ESCAPED_PATH in the command (not raw $VAULT_PATH)
|
||||
if [ "$SHELL_TYPE" = "fish" ]; then
|
||||
# Fish uses function syntax, not alias
|
||||
COMMAND_TEXT="function claudesidian
|
||||
cd \"$ESCAPED_PATH\" && (claude --resume 2>/dev/null; or claude)
|
||||
cd -
|
||||
end"
|
||||
else
|
||||
# Bash/Zsh use alias syntax
|
||||
# IMPORTANT: Use double quotes around $ESCAPED_PATH to preserve escaping
|
||||
COMMAND_TEXT="alias claudesidian='(cd \"$ESCAPED_PATH\" && (claude --resume 2>/dev/null || claude))'"
|
||||
fi
|
||||
```
|
||||
8. **Remove old command if replacing**:
|
||||
```bash
|
||||
if [ "$REPLACING" = true ]; then
|
||||
# Remove old alias/function before adding new one
|
||||
sed -i.tmp '/alias claudesidian\|function claudesidian/,/^end$/d' "$CONFIG_FILE"
|
||||
rm -f "$CONFIG_FILE.tmp"
|
||||
fi
|
||||
```
|
||||
9. **Add command to config file**: Append using the escaped command text
|
||||
```bash
|
||||
echo "$COMMAND_TEXT" >> "$CONFIG_FILE"
|
||||
```
|
||||
10. **Show success message**: With instructions to reload shell
|
||||
|
||||
## Example Output
|
||||
|
||||
**Bash/Zsh Example (with spaces in path to demonstrate escaping):**
|
||||
|
||||
```
|
||||
🔧 Installing claudesidian command...
|
||||
|
||||
📁 Vault path: /home/user/My Obsidian Vault
|
||||
🐚 Shell detected: zsh
|
||||
📝 Config file: /home/user/.zshrc
|
||||
|
||||
💾 Backup created: /home/user/.zshrc.backup-20250107-143025
|
||||
|
||||
✅ Installed! Added to /home/user/.zshrc:
|
||||
alias claudesidian='(cd "/home/user/My Obsidian Vault" && (claude --resume 2>/dev/null || claude))'
|
||||
|
||||
🔄 To activate, run:
|
||||
source ~/.zshrc
|
||||
|
||||
Or start a new terminal session.
|
||||
|
||||
✨ Test it: Type 'claudesidian' from any directory!
|
||||
```
|
||||
|
||||
**Fish Shell Example:**
|
||||
|
||||
```
|
||||
🔧 Installing claudesidian command...
|
||||
|
||||
📁 Vault path: /home/user/My Obsidian Vault
|
||||
🐚 Shell detected: fish
|
||||
📝 Config file: /home/user/.config/fish/config.fish
|
||||
|
||||
💾 Backup created: /home/user/.config/fish/config.fish.backup-20250107-143025
|
||||
|
||||
✅ Installed! Added to /home/user/.config/fish/config.fish:
|
||||
function claudesidian
|
||||
cd "/home/user/My Obsidian Vault" && (claude --resume 2>/dev/null; or claude)
|
||||
cd -
|
||||
end
|
||||
|
||||
🔄 To activate, run:
|
||||
source ~/.config/fish/config.fish
|
||||
|
||||
Or start a new terminal session.
|
||||
|
||||
✨ Test it: Type 'claudesidian' from any directory!
|
||||
```
|
||||
|
||||
## Handling Special Characters
|
||||
|
||||
The implementation properly handles paths with:
|
||||
|
||||
- Spaces: `/Users/noah/My Vault`
|
||||
- Quotes: `/Users/noah/vault's backup`
|
||||
- Special characters that need escaping
|
||||
|
||||
Paths are double-quoted and any embedded quotes/backslashes are escaped.
|
||||
|
||||
## Fish Shell Support
|
||||
|
||||
Fish shell uses different syntax than Bash/Zsh:
|
||||
|
||||
**Bash/Zsh (alias):**
|
||||
|
||||
```bash
|
||||
alias claudesidian='(cd "/path" && command)'
|
||||
```
|
||||
|
||||
**Fish (function):**
|
||||
|
||||
```fish
|
||||
function claudesidian
|
||||
cd "/path" && (command; or fallback)
|
||||
cd -
|
||||
end
|
||||
```
|
||||
|
||||
Key differences:
|
||||
|
||||
- Fish uses `function` keyword instead of `alias` for complex commands
|
||||
- Fish uses `; or` instead of `||` for fallback logic
|
||||
- Fish uses `cd -` to return to previous directory (instead of subshell)
|
||||
- Multi-line function definition instead of single-line alias
|
||||
|
||||
The installation automatically detects Fish and uses the correct syntax.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
This command modifies your shell configuration file (a sensitive operation).
|
||||
Safety measures:
|
||||
|
||||
- **You'll see exactly what will be added** before any changes
|
||||
- **Timestamped backup is automatically created** before modification
|
||||
- **Vault path is properly escaped** to prevent injection attacks
|
||||
- **Only the claudesidian command is modified** - nothing else in your config
|
||||
- **Asks permission** before replacing existing commands
|
||||
|
||||
If anything goes wrong, restore from: `$CONFIG_FILE.backup-YYYYMMDD-HHMMSS`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- The command uses a subshell `()` (or `cd -` in Fish) so it returns to your
|
||||
original directory after
|
||||
- Automatically tries to resume existing sessions, falls back to new session
|
||||
- If alias/function already exists, asks user if they want to replace it
|
||||
- Always shows what will be added before modifying config files
|
||||
- **Always creates timestamped backup** of config file before modifying (format:
|
||||
`YYYYMMDD-HHMMSS`)
|
||||
- Backups are kept indefinitely - users can manually clean up old backups if
|
||||
needed
|
||||
- Shows backup location so users know where to restore from if needed
|
||||
|
||||
## Usage Examples
|
||||
|
||||
Install for your default shell (auto-detected):
|
||||
|
||||
```
|
||||
/install-claudesidian-command
|
||||
```
|
||||
|
||||
Install for specific shell (override auto-detection):
|
||||
|
||||
```
|
||||
/install-claudesidian-command zsh
|
||||
/install-claudesidian-command bash
|
||||
/install-claudesidian-command fish
|
||||
```
|
||||
|
||||
**When to specify shell:**
|
||||
|
||||
- You use multiple shells and want to install for a specific one
|
||||
- Auto-detection picked the wrong shell
|
||||
- You're setting up for someone else
|
||||
|
||||
## How It Works
|
||||
|
||||
**Bash/Zsh (alias with subshell):**
|
||||
|
||||
```bash
|
||||
alias claudesidian='(cd "/path/to/vault" && (claude --resume 2>/dev/null || claude))'
|
||||
```
|
||||
|
||||
1. `(cd "/path/to/vault" && ...)` - Subshell that changes directory temporarily
|
||||
(path is double-quoted for safety)
|
||||
2. `claude --resume 2>/dev/null` - Tries to resume existing session, suppresses
|
||||
error
|
||||
3. `|| claude` - If resume fails (no session), starts new session
|
||||
4. After Claude exits, subshell closes and returns to original directory
|
||||
automatically
|
||||
|
||||
**Fish (function with cd -):**
|
||||
|
||||
```fish
|
||||
function claudesidian
|
||||
cd "/path/to/vault" && (claude --resume 2>/dev/null; or claude)
|
||||
cd -
|
||||
end
|
||||
```
|
||||
|
||||
1. `cd "/path/to/vault"` - Changes to vault directory (path is double-quoted for
|
||||
safety)
|
||||
2. `claude --resume 2>/dev/null` - Tries to resume existing session, suppresses
|
||||
error
|
||||
3. `; or claude` - If resume fails (no session), starts new session (Fish
|
||||
syntax)
|
||||
4. `cd -` - Returns to previous directory after Claude exits
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: low
|
||||
writes: none (read-only)
|
||||
|
||||
---
|
||||
name: pragmatic-review
|
||||
description:
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Pull Request Command
|
||||
risk: high
|
||||
writes: git remote (push + PR)
|
||||
|
||||
Creates a new feature branch, commits changes, pushes to GitHub, and opens a
|
||||
pull request - all in one command. Perfect for contributing features or fixes.
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
risk: high
|
||||
writes: git remote (tag + push)
|
||||
|
||||
---
|
||||
name: release
|
||||
description:
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Research Assistant
|
||||
risk: medium
|
||||
writes: 03_Resources/
|
||||
|
||||
Conduct thorough research on topics by searching the vault and synthesizing
|
||||
findings.
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Thinking Partner
|
||||
risk: low
|
||||
writes: none (conversation)
|
||||
|
||||
You are a collaborative thinking partner specializing in helping people explore
|
||||
complex problems. Your role is to facilitate thinking through careful
|
||||
|
||||
@@ -1,645 +0,0 @@
|
||||
---
|
||||
name: upgrade
|
||||
description:
|
||||
Intelligently upgrade claudesidian with new features while preserving user
|
||||
customizations using AI-powered semantic analysis
|
||||
allowed-tools: [Read, Write, Edit, MultiEdit, Bash, WebFetch, Grep, Glob]
|
||||
argument-hint:
|
||||
"(optional) 'check' to preview changes, 'force' to skip confirmations"
|
||||
---
|
||||
|
||||
# Smart Upgrade Command
|
||||
|
||||
Intelligently upgrades your claudesidian installation by fetching the latest
|
||||
release from GitHub and using AI-powered semantic analysis to merge new features
|
||||
with your existing customizations. Preserves user intent while adding new
|
||||
capabilities.
|
||||
|
||||
## Task
|
||||
|
||||
1. Check GitHub for the latest claudesidian release
|
||||
2. Download and analyze what has changed since your version
|
||||
3. Use Claude's semantic understanding to identify user customizations
|
||||
4. Intelligently merge new features with existing customizations
|
||||
5. Safely apply updates while preserving user data and preferences
|
||||
6. Create backups and provide rollback options
|
||||
|
||||
## Process
|
||||
|
||||
### 1. **Version Check & Setup**
|
||||
|
||||
- Get current version from package.json
|
||||
- Check if already on latest version:
|
||||
|
||||
```bash
|
||||
# Use cut instead of sed to avoid zsh parentheses escaping issues
|
||||
CURRENT=$(grep '"version"' package.json | head -1 | cut -d'"' -f4)
|
||||
LATEST=$(curl -s https://raw.githubusercontent.com/heyitsnoah/claudesidian/main/package.json | grep '"version"' | head -1 | cut -d'"' -f4)
|
||||
|
||||
if [ "$CURRENT" = "$LATEST" ]; then
|
||||
echo "✅ You're already on the latest version ($CURRENT)"
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
- Create timestamped backup in `.backup/upgrade-YYYY-MM-DD-HHMMSS/`:
|
||||
|
||||
```bash
|
||||
# Create backup directory
|
||||
BACKUP_DIR=".backup/upgrade-$(date +%Y-%m-%d-%H%M%S)"
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
# Copy all important files to backup
|
||||
cp -r .claude "$BACKUP_DIR/"
|
||||
cp -r .scripts "$BACKUP_DIR/"
|
||||
cp package.json "$BACKUP_DIR/"
|
||||
cp CHANGELOG.md "$BACKUP_DIR/" 2>/dev/null || true
|
||||
cp README.md "$BACKUP_DIR/" 2>/dev/null || true
|
||||
|
||||
echo "✅ Backup created in $BACKUP_DIR"
|
||||
```
|
||||
|
||||
- Clone latest claudesidian to temp directory (doesn't affect user's repo):
|
||||
```bash
|
||||
# Get fresh copy in .tmp dir (hidden from Obsidian) - user's repo stays disconnected
|
||||
git clone --depth=1 --branch=main https://github.com/heyitsnoah/claudesidian.git .tmp/claudesidian-upgrade
|
||||
```
|
||||
- Now we have latest version to compare against
|
||||
|
||||
### 2. **Create Upgrade Checklist**
|
||||
|
||||
- Compare system files between current directory and .tmp/claudesidian-upgrade/:
|
||||
|
||||
```bash
|
||||
# Find all system files that differ AND new files in upstream
|
||||
# First, find files that exist in both but differ
|
||||
diff -qr . .tmp/claudesidian-upgrade/ --include="*.md" --include="*.sh" --include="*.json" |
|
||||
grep -E '(\.claude/|\.scripts/|package\.json|CHANGELOG\.md|README\.md)' |
|
||||
grep -v '(00_|01_|02_|03_|04_|05_|06_|\.obsidian|CLAUDE\.md)'
|
||||
|
||||
# Also find NEW files in upstream (like new commands)
|
||||
find .tmp/claudesidian-upgrade/.claude/commands -name "*.md" | while read f; do
|
||||
local_file=${f#.tmp/claudesidian-upgrade/}
|
||||
[ ! -f "$local_file" ] && echo "NEW: $local_file"
|
||||
done
|
||||
```
|
||||
|
||||
- Create checklist of files that need review
|
||||
- Explicitly EXCLUDE:
|
||||
- User content folders (00_Inbox, 01_Projects, etc.)
|
||||
- User's CLAUDE.md (their personalized version)
|
||||
- vault-config.json (user's vault configuration)
|
||||
- .obsidian/ (user's Obsidian settings)
|
||||
- Any .md files in the root except README and CHANGELOG
|
||||
- Create `.upgrade-checklist.md` with only system files that differ
|
||||
- Mark each file with status: `[ ] pending`, `[x] updated`, `[-] skipped`
|
||||
- Group files by type for easier review:
|
||||
|
||||
```markdown
|
||||
## Commands (12 files)
|
||||
|
||||
[ ] .claude/commands/init-bootstrap.md [ ] .claude/commands/release.md [ ]
|
||||
.claude/commands/thinking-partner.md ...
|
||||
|
||||
## Settings (2 files)
|
||||
|
||||
[ ] .claude/settings.json [ ] .claude/settings.local.json
|
||||
|
||||
## Core Files (3 files)
|
||||
|
||||
[ ] package.json [ ] CHANGELOG.md [ ] README.md
|
||||
```
|
||||
|
||||
### 3. **File-by-File Review**
|
||||
|
||||
**⚠️ CRITICAL IMPLEMENTATION REQUIREMENT:**
|
||||
|
||||
- **NEVER blindly overwrite files without showing diffs first**
|
||||
- **ALWAYS show diffs to the user first**
|
||||
- **ALWAYS ask for confirmation before replacing files**
|
||||
- **Skipping these steps can lose user customizations!**
|
||||
- **NEVER use `cp` or `cp -f` (both can cause prompts on protected files)**
|
||||
- **ALWAYS USE `cat source > dest` for guaranteed non-interactive replacement**
|
||||
- **WAIT for actual user input - don't automatically choose option 1**
|
||||
|
||||
For EACH file in the checklist:
|
||||
|
||||
1. Read current checklist status from `.upgrade-checklist.md`
|
||||
2. **MANDATORY: Show the diff between local and upstream**:
|
||||
```bash
|
||||
# ALWAYS show this to the user!
|
||||
diff -u current/file .tmp/claudesidian-upgrade/file
|
||||
```
|
||||
3. Determine update strategy:
|
||||
- **No local changes**: Direct replace from upstream
|
||||
- **Never update**: User's CLAUDE.md, vault-config.json, .mcp.json
|
||||
- **Local changes detected**: Ask user:
|
||||
|
||||
```
|
||||
File: .claude/commands/thinking-partner.md has local modifications
|
||||
|
||||
Options:
|
||||
1. Keep your version (skip update)
|
||||
2. Take upstream version (lose your changes)
|
||||
3. View diff and decide
|
||||
4. Try to merge both (AI-assisted)
|
||||
|
||||
Choice (1/2/3/4): [WAIT FOR USER TO TYPE NUMBER AND PRESS ENTER]
|
||||
```
|
||||
|
||||
**IMPORTANT**: Actually WAIT for the user to type their choice! Do NOT
|
||||
automatically select any option. The user must manually type 1, 2, 3, or 4
|
||||
and press Enter.
|
||||
|
||||
4. Apply the chosen strategy:
|
||||
- **For option 1 (Apply update/Take upstream)**:
|
||||
```bash
|
||||
# IMPORTANT: Check if file exists first, then use cat with redirection
|
||||
if [ -f ".tmp/claudesidian-upgrade/path/to/file" ]; then
|
||||
cat .tmp/claudesidian-upgrade/path/to/file > path/to/file && echo "✅ Updated"
|
||||
else
|
||||
echo "⚠️ File not found in upstream - keeping local version"
|
||||
fi
|
||||
```
|
||||
- **For option 2 (Keep your version)**:
|
||||
```bash
|
||||
echo "✅ Kept your version"
|
||||
```
|
||||
- **For option 4 (AI merge)**: Read both files and create merged version
|
||||
5. **CRITICAL: Update the checklist file immediately**:
|
||||
```markdown
|
||||
[ ] .claude/commands/init-bootstrap.md → becomes → [x]
|
||||
.claude/commands/init-bootstrap.md
|
||||
```
|
||||
6. Save `.upgrade-checklist.md` after EVERY file update
|
||||
7. Move to next file
|
||||
|
||||
### 4. **Update Types**
|
||||
|
||||
- **Safe to replace**: `.claude/commands/*.md`, `.claude/agents/*.md`,
|
||||
`.scripts/*`
|
||||
- **Needs review**: `package.json` (preserve user's custom scripts)
|
||||
- **Never touch**: User content folders, CLAUDE.md, API configs
|
||||
|
||||
#### Batch Updates for Similar Files
|
||||
|
||||
For commands that have only formatting changes, you can batch update:
|
||||
|
||||
```bash
|
||||
# Batch update multiple command files with same type of changes
|
||||
for file in thinking-partner.md daily-review.md inbox-processor.md; do
|
||||
if [ -f ".tmp/claudesidian-upgrade/.claude/commands/$file" ]; then
|
||||
cat ".tmp/claudesidian-upgrade/.claude/commands/$file" > ".claude/commands/$file"
|
||||
echo "✅ Updated $file"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
#### Handling Missing Upstream Files
|
||||
|
||||
Some files may exist locally but not in upstream (like deprecated agents):
|
||||
|
||||
```bash
|
||||
# Check if file exists in upstream before trying to update
|
||||
if [ ! -f ".tmp/claudesidian-upgrade/$filepath" ]; then
|
||||
echo "⚠️ $filepath not in upstream - keeping local version"
|
||||
# Mark as skipped in checklist: [-]
|
||||
fi
|
||||
```
|
||||
|
||||
### 5. **Progress Tracking**
|
||||
|
||||
- Use TodoWrite tool to track progress alongside the checklist
|
||||
- Save progress after each file in `.upgrade-checklist.md`
|
||||
- **MUST mark items in checklist**:
|
||||
- `[x]` = completed
|
||||
- `[-]` = skipped (user customization)
|
||||
- `[ ]` = still pending
|
||||
- If interrupted, can resume from where you left off
|
||||
- Show progress: "Updating file 5 of 23..."
|
||||
- Clear indication of what's been done and what's remaining
|
||||
|
||||
### 6. **Verification Check**
|
||||
|
||||
- Re-check all system files against the checklist
|
||||
- Compare with checklist to identify:
|
||||
- Files marked `[ ]` pending = likely missed (problem)
|
||||
- Files marked `[-]` skipped = intentionally kept different (fine)
|
||||
- Files marked `[x]` updated but still in diff = merge issues or user edits
|
||||
(review)
|
||||
- Show verification results:
|
||||
```
|
||||
✅ All required files updated successfully
|
||||
ℹ️ 2 files intentionally kept with user customizations:
|
||||
- .claude/commands/thinking-partner.md (user's concise style)
|
||||
- package.json (user's custom scripts preserved)
|
||||
- or -
|
||||
⚠️ Warning: 2 files appear to be missed (still marked pending):
|
||||
- .claude/commands/release.md
|
||||
- .scripts/vault-stats.sh
|
||||
```
|
||||
- Only flag as problem if files are still marked `[ ]` pending in checklist
|
||||
|
||||
### 7. **Final Steps**
|
||||
|
||||
- Update version in package.json
|
||||
- Verify all commands work
|
||||
- Clean up temp directory: `rm -rf .tmp/claudesidian-upgrade`
|
||||
- Save final checklist for reference (shows what was updated vs skipped)
|
||||
- Show summary of what was updated
|
||||
|
||||
## Update Categories
|
||||
|
||||
### 🤖 AI-Powered Intelligent Merge
|
||||
|
||||
**Commands** (`.claude/commands/*.md`):
|
||||
|
||||
- Analyze user's prompt style, output preferences, workflow modifications
|
||||
- Merge new features with existing customizations
|
||||
- Preserve user's tone, structure, and specific requirements
|
||||
|
||||
**Agents** (`.claude/agents/*.md`):
|
||||
|
||||
- Understand user's interaction preferences
|
||||
- Combine new capabilities with existing personality
|
||||
- Maintain user's established workflows
|
||||
|
||||
**Templates** (`06_Metadata/Templates/*.md`):
|
||||
|
||||
- Preserve custom fields and structure
|
||||
- Add new template features
|
||||
- Maintain user's formatting preferences
|
||||
|
||||
### ⚡ Automatic Safe Updates
|
||||
|
||||
- **New commands/agents**: Purely additive, no conflicts
|
||||
- **Scripts** (`.scripts/*`): Utility functions, safe to replace
|
||||
- **Dependencies** (`package.json`): Security and feature updates
|
||||
- **Documentation**: README, CONTRIBUTING updates
|
||||
|
||||
### 🛡️ Never Modified
|
||||
|
||||
- **User content**: All `00_*` through `06_*` folders (except templates)
|
||||
- **Personal config**: User's `CLAUDE.md`
|
||||
- **API keys**: `.mcp.json`, environment variables
|
||||
- **Git history**: User's commits and branches
|
||||
|
||||
## Smart Conflict Resolution
|
||||
|
||||
When Claude detects conflicts:
|
||||
|
||||
### Example Scenarios:
|
||||
|
||||
**Scenario 1: Command Enhancement**
|
||||
|
||||
```
|
||||
📝 thinking-partner command has updates:
|
||||
|
||||
YOUR VERSION: Custom concise output format, specific industry focus
|
||||
NEW VERSION: Added video analysis capability, improved questioning flow
|
||||
|
||||
🤖 SMART MERGE PROPOSAL:
|
||||
✅ Keep your concise output style
|
||||
✅ Keep your industry-specific prompts
|
||||
✅ Add new video analysis features
|
||||
✅ Integrate improved questioning (adapted to your style)
|
||||
|
||||
Options:
|
||||
1. 🎯 Apply smart merge (recommended)
|
||||
2. 👀 Show detailed diff first
|
||||
3. 🚫 Skip this update
|
||||
4. 💾 Replace with new version (backup yours)
|
||||
```
|
||||
|
||||
**Scenario 2: Template Updates**
|
||||
|
||||
```
|
||||
📋 Project Template has changes:
|
||||
|
||||
YOUR VERSION: Added custom fields for client info, budget tracking
|
||||
NEW VERSION: Enhanced metadata structure, new automation hooks
|
||||
|
||||
🤖 SMART MERGE PROPOSAL:
|
||||
✅ Preserve your custom client/budget fields
|
||||
✅ Add new metadata enhancements
|
||||
✅ Integrate automation hooks
|
||||
✅ Maintain your field ordering
|
||||
|
||||
Apply merge? (y/n/preview)
|
||||
```
|
||||
|
||||
## Command Usage
|
||||
|
||||
### Preview Mode (Recommended First Run)
|
||||
|
||||
```
|
||||
/upgrade check
|
||||
```
|
||||
|
||||
- Shows what would be updated
|
||||
- Displays intelligent merge previews
|
||||
- No changes made to files
|
||||
- Safe to run anytime
|
||||
|
||||
### Interactive Upgrade
|
||||
|
||||
```
|
||||
/upgrade
|
||||
```
|
||||
|
||||
- Step-by-step confirmation for each change
|
||||
- Shows before/after for modified files
|
||||
- Allows selective application of updates
|
||||
- Creates automatic backups
|
||||
|
||||
### Batch Upgrade (Advanced)
|
||||
|
||||
```
|
||||
/upgrade force
|
||||
```
|
||||
|
||||
- Applies all safe updates automatically
|
||||
- Still prompts for complex merges
|
||||
- Faster for users comfortable with the process
|
||||
- Full backup created before starting
|
||||
|
||||
## Safety Features
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
- Complete backup before any changes: `.backup/upgrade-[timestamp]/`
|
||||
- Individual file backups for each modification
|
||||
- Backup includes current git state and uncommitted changes
|
||||
|
||||
### Rollback Support
|
||||
|
||||
```
|
||||
# If upgrade causes issues:
|
||||
/rollback-upgrade [timestamp]
|
||||
# Restores from specific backup
|
||||
```
|
||||
|
||||
### Verification Steps
|
||||
|
||||
- Post-upgrade functionality testing
|
||||
- Command validation (runs test commands)
|
||||
- MCP server connectivity check
|
||||
- Git repository integrity verification
|
||||
|
||||
### Incremental Application
|
||||
|
||||
- Updates applied one file at a time
|
||||
- Validation after each critical change
|
||||
- Stops on first error with clear diagnostics
|
||||
- Easy to identify which change caused issues
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
### ⚠️ Selective Updates Problem
|
||||
|
||||
**Never cherry-pick files based only on release notes!** This leads to:
|
||||
|
||||
- Missing critical command updates
|
||||
- Incomplete feature implementations
|
||||
- Broken dependencies between files
|
||||
- Users not getting all improvements
|
||||
|
||||
**Always use `git diff HEAD upstream/main --name-only`** to get the complete
|
||||
list of changed files, then update ALL relevant files systematically.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Scenarios
|
||||
|
||||
- **No internet connection**: Graceful failure with offline options
|
||||
- **GitHub API rate limits**: Intelligent retry with backoff
|
||||
- **Merge conflicts**: Clear explanation and manual resolution options
|
||||
- **Permission issues**: Helpful guidance on fixing file permissions
|
||||
|
||||
### Recovery Options
|
||||
|
||||
- **Partial failure**: Continue from last successful step
|
||||
- **Complete failure**: Full rollback to pre-upgrade state
|
||||
- **Git conflicts**: Merge upstream changes with local commits
|
||||
- **Dependency issues**: Fallback to previous working versions
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Custom Merge Rules
|
||||
|
||||
Users can create `.upgrade-rules.json` to specify:
|
||||
|
||||
- Files to always skip
|
||||
- Custom merge preferences
|
||||
- Automatic approval for specific change types
|
||||
- Backup retention policies
|
||||
|
||||
### Integration with Git
|
||||
|
||||
- Commits each major change separately
|
||||
- Meaningful commit messages describing updates
|
||||
- Preserves user's branch structure
|
||||
- Handles git conflicts intelligently
|
||||
|
||||
### Selective Updates
|
||||
|
||||
```
|
||||
/upgrade commands-only # Update just commands
|
||||
/upgrade agents-only # Update just agents
|
||||
/upgrade scripts-only # Update just scripts
|
||||
/upgrade deps-only # Update just dependencies
|
||||
```
|
||||
|
||||
## CORRECT Implementation Example
|
||||
|
||||
**THIS is how the upgrade should work:**
|
||||
|
||||
```bash
|
||||
📄 File 1/3: .claude/commands/release.md
|
||||
|
||||
# Step 1: ALWAYS show the diff first
|
||||
Checking for differences...
|
||||
|
||||
--- .claude/commands/release.md
|
||||
+++ .tmp/claudesidian-upgrade/.claude/commands/release.md
|
||||
@@ -58,6 +58,11 @@
|
||||
|
||||
### Semantic Versioning (MAJOR.MINOR.PATCH)
|
||||
|
||||
+**Quick Decision Guide:**
|
||||
+- Can users do something they couldn't do before? → **MINOR**
|
||||
+- Did something that worked break? → **MAJOR** (if breaking) or **PATCH** (if fixing)
|
||||
+- Did something that worked get better? → **PATCH**
|
||||
+
|
||||
**MAJOR** (1.0.0 → 2.0.0):
|
||||
|
||||
# Step 2: Ask user what to do
|
||||
This file has updates available. What would you like to do?
|
||||
|
||||
1. Apply update (take upstream version)
|
||||
2. Keep your version (skip this update)
|
||||
3. View full diff again
|
||||
4. Try to merge changes (AI-assisted)
|
||||
|
||||
Your choice (1-4): 1
|
||||
|
||||
Applying update...
|
||||
[x] Updated .claude/commands/release.md
|
||||
```
|
||||
|
||||
**WRONG Implementation (what happened in the test):**
|
||||
|
||||
```bash
|
||||
📄 File 1/3: .claude/commands/release.md
|
||||
|
||||
# NO DIFF SHOWN - WRONG!
|
||||
# Just blindly overwrites:
|
||||
Bash(cat .tmp/claudesidian-upgrade/.claude/commands/release.md > .claude/commands/release.md)
|
||||
|
||||
# No user confirmation - WRONG!
|
||||
# Could lose customizations!
|
||||
```
|
||||
|
||||
## Example Session
|
||||
|
||||
```
|
||||
> /upgrade
|
||||
|
||||
🔍 Checking for updates...
|
||||
📦 Current version: 0.8.2
|
||||
🆕 Latest version: 0.8.3
|
||||
|
||||
💾 Creating backup to .backup/upgrade-2025-09-13-142030/
|
||||
|
||||
📋 Creating upgrade checklist...
|
||||
Checking system files only (not your personal notes)...
|
||||
Found 15 system files with updates available
|
||||
|
||||
Created .upgrade-checklist.md to track updates:
|
||||
|
||||
## Commands (8 files)
|
||||
[ ] .claude/commands/init-bootstrap.md
|
||||
[ ] .claude/commands/release.md
|
||||
[ ] .claude/commands/thinking-partner.md
|
||||
[ ] .claude/commands/upgrade.md
|
||||
[ ] .claude/commands/daily-review.md
|
||||
[ ] .claude/commands/inbox-processor.md
|
||||
[ ] .claude/commands/research-assistant.md
|
||||
[ ] .claude/commands/weekly-synthesis.md
|
||||
|
||||
## Settings (1 file)
|
||||
[ ] .claude/settings.json
|
||||
|
||||
## Core Files (3 files)
|
||||
[ ] package.json
|
||||
[ ] CHANGELOG.md
|
||||
[ ] README.md
|
||||
|
||||
## Scripts (3 files)
|
||||
[ ] .scripts/vault-stats.sh
|
||||
[ ] .scripts/firecrawl-scrape.sh
|
||||
[ ] .scripts/setup-mcp.sh
|
||||
|
||||
Starting file-by-file review...
|
||||
|
||||
📄 File 1/15: .claude/commands/init-bootstrap.md
|
||||
Status: No local changes detected
|
||||
Action: Direct update from upstream
|
||||
[x] Updated
|
||||
|
||||
📄 File 2/15: .claude/commands/release.md
|
||||
Status: No local changes detected
|
||||
Action: Direct update from upstream
|
||||
[x] Updated
|
||||
|
||||
📄 File 3/15: .claude/settings.json
|
||||
Status: Has local changes (your custom hooks)
|
||||
Showing diff...
|
||||
Action: Merge needed - preserving your hooks, adding new features
|
||||
[x] Merged
|
||||
|
||||
[... continues through all files ...]
|
||||
|
||||
🔍 **Verification Check**
|
||||
Re-checking for any missed system files...
|
||||
|
||||
✅ All system files successfully updated!
|
||||
No claudesidian system files remain out of sync with upstream.
|
||||
|
||||
🎉 Upgrade complete!
|
||||
📈 claudesidian 0.8.2 → 0.8.3
|
||||
|
||||
✅ Updated: 14 files
|
||||
⏭️ Skipped: 1 file (CLAUDE.md - user customization)
|
||||
✅ Verified: All system files match upstream
|
||||
|
||||
Summary of changes:
|
||||
- Fixed init-bootstrap vault selection
|
||||
- Improved SessionStart hooks
|
||||
- Enhanced user identification prompts
|
||||
- Updated all commands to latest versions
|
||||
```
|
||||
|
||||
### Example: Verification Catches Missed Files
|
||||
|
||||
```
|
||||
🔍 **Verification Check**
|
||||
Re-checking for any missed system files...
|
||||
|
||||
⚠️ Warning: 2 files appear to be missed (still marked pending in checklist):
|
||||
- .claude/commands/thinking-partner.md [ ]
|
||||
- .scripts/vault-stats.sh [ ]
|
||||
|
||||
These files haven't been processed yet.
|
||||
|
||||
Would you like to complete the upgrade for these files? (y/n) > y
|
||||
|
||||
📄 Completing upgrade for missed files...
|
||||
|
||||
📄 File: .claude/commands/thinking-partner.md
|
||||
Status: Reviewing diff...
|
||||
Action: Direct update from upstream
|
||||
[x] Updated
|
||||
|
||||
📄 File: .scripts/vault-stats.sh
|
||||
Status: Reviewing diff...
|
||||
Action: Direct update from upstream
|
||||
[x] Updated
|
||||
|
||||
✅ Verification complete - all system files now match upstream!
|
||||
```
|
||||
|
||||
### Example: Verification with User Customizations
|
||||
|
||||
```
|
||||
🔍 **Verification Check**
|
||||
Re-checking for any missed system files...
|
||||
|
||||
Files still differing from upstream:
|
||||
- .claude/commands/thinking-partner.md [x] ← Updated but user customized
|
||||
- package.json [x] ← Merged, kept user's custom scripts
|
||||
- .claude/commands/daily-review.md [ ] ← Not processed yet!
|
||||
|
||||
✅ 2 files intentionally preserve user customizations
|
||||
⚠️ 1 file appears to be missed (still pending)
|
||||
|
||||
Would you like to:
|
||||
1. Review the missed file (.claude/commands/daily-review.md)
|
||||
2. Skip verification (keep current state)
|
||||
3. See details about customized files
|
||||
|
||||
Choice (1/2/3) > 1
|
||||
|
||||
📄 File: .claude/commands/daily-review.md
|
||||
Status: Reviewing diff...
|
||||
Action: Direct update from upstream
|
||||
[x] Updated
|
||||
|
||||
✅ Verification complete!
|
||||
- All required updates applied
|
||||
- User customizations preserved where intended
|
||||
```
|
||||
|
||||
This intelligent upgrade system leverages Claude's semantic understanding to
|
||||
provide the smoothest possible upgrade experience while ensuring no user
|
||||
customizations are lost.
|
||||
@@ -1,4 +1,6 @@
|
||||
# Weekly Synthesis
|
||||
risk: medium
|
||||
writes: 00_Inbox/ weekly notes
|
||||
|
||||
Create a comprehensive synthesis of the week's work and thinking.
|
||||
|
||||
|
||||
@@ -1,23 +0,0 @@
|
||||
# Git Workflow
|
||||
|
||||
## Session Workflow
|
||||
```bash
|
||||
# Always start sessions with
|
||||
git pull
|
||||
|
||||
# After significant work
|
||||
git add . && git commit -m "vault backup: $(date)" && git push
|
||||
```
|
||||
|
||||
## Commit Format
|
||||
- Standard: `vault backup: YYYY-MM-DD HH:MM:SS`
|
||||
- Feature: `feat: description`
|
||||
- Fix: `fix: description`
|
||||
- Docs: `docs: description`
|
||||
|
||||
## Best Practices
|
||||
- Pull before starting work
|
||||
- Commit frequently (after significant changes)
|
||||
- Push at end of session
|
||||
- Use descriptive messages for non-backup commits
|
||||
- Never force push without approval
|
||||
@@ -1,19 +0,0 @@
|
||||
# Linking Strategy & Connections
|
||||
|
||||
## Core Principles
|
||||
- Use `[[wikilinks]]` for all internal connections
|
||||
- Link liberally - prefer over-linking to under-linking
|
||||
- Always check and update links after reorganizing files
|
||||
- Proactively suggest connections when relevant
|
||||
|
||||
## When to Create Links
|
||||
- User mentions existing topics/notes
|
||||
- New content relates to existing knowledge
|
||||
- Concepts connect across PARA categories
|
||||
- Creating connections aids discovery
|
||||
|
||||
## Link Maintenance
|
||||
- After moving files, verify all backlinks updated
|
||||
- Periodically check for broken links
|
||||
- Suggest creating MOCs (Maps of Content) for clustered topics
|
||||
- Identify orphaned notes (no connections)
|
||||
@@ -1,27 +0,0 @@
|
||||
# PARA Organization System
|
||||
|
||||
## Folder Structure
|
||||
```
|
||||
00_Inbox/ → Temporary capture, process weekly
|
||||
01_Projects/ → Time-bound work with deadlines
|
||||
02_Areas/ → Ongoing responsibilities
|
||||
03_Resources/ → Reference materials
|
||||
04_Archive/ → Completed items
|
||||
05_Attachments/ → Media files
|
||||
06_Metadata/ → Docs & templates
|
||||
```
|
||||
|
||||
## Quick Decision Tree
|
||||
- Has deadline? → 01_Projects/
|
||||
- Ongoing responsibility? → 02_Areas/
|
||||
- Reference material? → 03_Resources/
|
||||
- Unsure? → 00_Inbox/
|
||||
|
||||
## Organization Principles
|
||||
- Inbox is temporary - process weekly
|
||||
- One idea per note (atomic notes)
|
||||
- Flat structure over deep nesting (max 4 levels for new notes)
|
||||
- Use links not folders for relationships
|
||||
|
||||
## Clipper Boundary
|
||||
- `04_Archive/Inbox-Clippings/**` permanently uses the web clipper schema (`date`/`page-title`/`url`). Never migrate.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Data Safety & File Operations
|
||||
|
||||
## Core Principles
|
||||
- **Never delete without approval** - Always ask before removing content
|
||||
- **Preserve everything when merging** - Only remove verified exact duplicates
|
||||
- **Verify before moving** - Check destination exists, update all `[[wikilinks]]` after
|
||||
- **Read before writing** - Use Read tool before editing any file
|
||||
|
||||
## File Operations
|
||||
- Use `mv` not `cp` (avoid duplicates)
|
||||
- Never move numbered folders (00-06) from vault root
|
||||
- Get approval for bulk operations affecting 5+ files
|
||||
|
||||
When proposing bulk operations:
|
||||
- Explain what's changing and why
|
||||
- List files affected
|
||||
- Provide rollback approach
|
||||
@@ -1,24 +0,0 @@
|
||||
# Note Standards & Frontmatter
|
||||
|
||||
## Required Frontmatter
|
||||
```yaml
|
||||
---
|
||||
created: YYYY-MM-DD
|
||||
modified: YYYY-MM-DD
|
||||
tags: [specific, tags]
|
||||
status: draft|active|complete|archived
|
||||
---
|
||||
```
|
||||
|
||||
## File Naming
|
||||
- **Daily notes**: YYYY-MM-DD.md (e.g., 2026-01-08.md)
|
||||
- **Project notes**: Clear, descriptive names with context
|
||||
- **Resource notes**: Topic-based naming
|
||||
- **Avoid**: Special characters except hyphens and underscores
|
||||
|
||||
## Note Types
|
||||
- **Atomic Notes**: Single concept, highly linkable
|
||||
- **MOCs**: Topic hubs with curated links
|
||||
- **Daily Notes**: Journal entries, meeting notes, quick captures
|
||||
- **Project Notes**: Actionable items with clear outcomes
|
||||
- **Evergreen Notes**: Permanent, well-developed ideas
|
||||
@@ -1,129 +0,0 @@
|
||||
# Obsidian PKM Assistant
|
||||
|
||||
> Core principles only. See `06_Metadata/WORKFLOWS.md` for detailed procedures.
|
||||
|
||||
---
|
||||
|
||||
## Safety First
|
||||
|
||||
### Data Integrity
|
||||
- **Never delete without approval** - Always ask before removing content
|
||||
- **Preserve everything when merging** - Only remove verified exact duplicates
|
||||
- **Verify before moving** - Check destination exists, update all `[[wikilinks]]` after
|
||||
- **Read before writing** - Use Read tool before editing any file
|
||||
|
||||
### File Operations
|
||||
- Use `mv` not `cp` (avoid duplicates)
|
||||
- Never move numbered folders (00-06) from vault root
|
||||
- Get approval for bulk operations affecting 5+ files
|
||||
|
||||
---
|
||||
|
||||
## PARA Structure
|
||||
|
||||
```
|
||||
00_Inbox/ → Temporary capture, process weekly
|
||||
01_Projects/ → Time-bound work with deadlines
|
||||
02_Areas/ → Ongoing responsibilities
|
||||
03_Resources/ → Reference materials
|
||||
04_Archive/ → Completed items
|
||||
05_Attachments/ → Media files
|
||||
06_Metadata/ → Docs & templates
|
||||
```
|
||||
|
||||
**Quick Decision**: Deadline? → Projects | Ongoing? → Areas | Reference? → Resources | Unsure? → Inbox
|
||||
|
||||
---
|
||||
|
||||
## Git Essentials
|
||||
|
||||
```bash
|
||||
# Always start sessions with
|
||||
git pull
|
||||
|
||||
# After significant work
|
||||
git add . && git commit -m "vault backup: $(date)" && git push
|
||||
```
|
||||
|
||||
Commit format: `vault backup: YYYY-MM-DD HH:MM:SS`
|
||||
|
||||
---
|
||||
|
||||
## Memory Integration
|
||||
|
||||
Use Memvid MCP for persistent context across sessions:
|
||||
|
||||
### Core Workflow
|
||||
1. **Query first**: Always search memory at task start: `memvid_search`
|
||||
2. **Work**: Complete task using retrieved context
|
||||
3. **Write back**: Save decisions: `memvid_add_text` + `memvid_commit`
|
||||
|
||||
### What to Store
|
||||
- **DO**: User preferences, decisions, constraints, patterns, project context
|
||||
- **DON'T**: Secrets, credentials, errors, logs, temporary data
|
||||
|
||||
### Memory File Location
|
||||
- Default: `.claude/memory/memvid.mv2`
|
||||
- Project-specific: `.claude/memory/[project-name].mv2`
|
||||
|
||||
### Tagging Strategy
|
||||
Use consistent tags for retrieval:
|
||||
- `type:preference` - User preferences and settings
|
||||
- `type:decision` - Architectural and design decisions
|
||||
- `type:constraint` - Project limitations and requirements
|
||||
- `type:pattern` - Code patterns and conventions
|
||||
- `project:[name]` - Project-specific context
|
||||
- `area:[name]` - Area-specific information
|
||||
|
||||
### Quick Reference
|
||||
```
|
||||
Search: memvid_search(query, top_k=5)
|
||||
Add: memvid_add_text(content, tags={"type": "decision"})
|
||||
Commit: memvid_commit()
|
||||
List: memvid_list_contents(limit=20)
|
||||
Info: memvid_info()
|
||||
```
|
||||
|
||||
See `06_Metadata/WORKFLOWS.md#memvid-workflows` for detailed procedures.
|
||||
|
||||
---
|
||||
|
||||
## Note Standards
|
||||
|
||||
### Frontmatter
|
||||
```yaml
|
||||
---
|
||||
created: YYYY-MM-DD
|
||||
modified: YYYY-MM-DD
|
||||
tags: [specific, tags]
|
||||
status: draft|active|complete|archived
|
||||
---
|
||||
```
|
||||
|
||||
### Linking
|
||||
- Use `[[wikilinks]]` for internal connections
|
||||
- Link liberally, prefer over-linking
|
||||
- Check and update links after reorganizing
|
||||
|
||||
### Organization
|
||||
- Inbox is temporary - process weekly
|
||||
- One idea per note (atomic notes)
|
||||
- Flat structure over deep nesting (max 4 levels for new notes)
|
||||
- Use links not folders for relationships
|
||||
|
||||
---
|
||||
|
||||
## Work Approach
|
||||
|
||||
**Simple tasks** → Execute directly
|
||||
**Complex changes** → Propose plan first (affected files, steps, rollback)
|
||||
**Uncertain info** → Mark `[待确认]` and ask
|
||||
|
||||
For bulk operations, provide:
|
||||
- What's changing and why
|
||||
- Files affected
|
||||
- Rollback approach
|
||||
|
||||
---
|
||||
|
||||
**Detailed workflows, templates, troubleshooting**: → `06_Metadata/WORKFLOWS.md`
|
||||
+9
-32
@@ -3,42 +3,19 @@
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm run | grep daily-note)",
|
||||
"Edit(06_Metadata/Templates/Daily Note Template.md)",
|
||||
"Edit(06_Metadata/Reference/DAILY_NOTE_GUIDE.md)",
|
||||
"Edit(.obsidian/plugins/quickadd/data.json)",
|
||||
"Edit(04_Archive/Projects/Airport/Chengdu/Office Test Env.md)",
|
||||
"Bash(wc:*)",
|
||||
"Bash(find:*)",
|
||||
"Bash(git add:*)"
|
||||
],
|
||||
"deny": [],
|
||||
"ask": []
|
||||
},
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "[ -f FIRST_RUN ] && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"\\n\\n# 🚀 Welcome to Claudesidian!\\n\\n**This appears to be your first time using this vault.**\\n\\n## Quick Start\\n\\nRun the setup wizard:\\n\\n⬇\\n/init-bootstrap\\n⬆\\n\\n## What this will do:\\n\\n✅ Set up your personalized configuration\\n✅ Disconnect from the original repository\\n✅ Help you import any existing Obsidian vault\\n✅ Configure your preferred workflow\\n✅ Create your PARA folder structure\\n\\nThe setup wizard will guide you through everything!\\n\\n\"}}' || true"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "npm run check-updates --silent 2>/dev/null || true"
|
||||
}
|
||||
]
|
||||
}
|
||||
"deny": [
|
||||
"Edit(.obsidian/plugins/*/data.json)",
|
||||
"Edit(04_Archive/**)",
|
||||
"Bash(git push:*)",
|
||||
"Bash(git add .:*)"
|
||||
],
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-discovery.sh",
|
||||
"timeout": 5000,
|
||||
"type": "command"
|
||||
}
|
||||
]
|
||||
}
|
||||
"ask": [
|
||||
"Edit(.obsidian/**)"
|
||||
]
|
||||
}
|
||||
},
|
||||
"hooks": {}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user