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": {}
|
||||
}
|
||||
|
||||
Vendored
-11
@@ -1,11 +0,0 @@
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 |
|
||||
</claude-mem-context>
|
||||
Vendored
-7
@@ -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,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,14 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1213 | 10:29 AM | 🔵 | Vault underwent formal review and improvement planning in February 2026 | ~630 |
|
||||
</claude-mem-context>
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1214 | 10:29 AM | 🔵 | Inconsistent frontmatter usage and exposed credentials in vault | ~384 |
|
||||
| #1206 | 10:25 AM | 🔵 | Personal vault structure and content patterns | ~372 |
|
||||
</claude-mem-context>
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1214 | 10:29 AM | 🔵 | Inconsistent frontmatter usage and exposed credentials in vault | ~384 |
|
||||
</claude-mem-context>
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
created: 2026-02-25
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 |
|
||||
| #1214 | " | 🔵 | Inconsistent frontmatter usage and exposed credentials in vault | ~384 |
|
||||
</claude-mem-context>
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
created: 2026-02-25
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 |
|
||||
| #1206 | 10:25 AM | 🔵 | Personal vault structure and content patterns | ~372 |
|
||||
</claude-mem-context>
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 |
|
||||
</claude-mem-context>
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 |
|
||||
</claude-mem-context>
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1216 | 10:29 AM | 🔵 | Dataview queries contain broken paths from previous folder structure reorganization | ~503 |
|
||||
</claude-mem-context>
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
created: 2026-01-26
|
||||
---
|
||||
<claude-mem-context>
|
||||
# Recent Activity
|
||||
|
||||
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
|
||||
|
||||
### Feb 25, 2026
|
||||
|
||||
| ID | Time | T | Title | Read |
|
||||
|----|------|---|-------|------|
|
||||
| #1206 | 10:25 AM | 🔵 | Personal vault structure and content patterns | ~372 |
|
||||
</claude-mem-context>
|
||||
@@ -1,176 +1,105 @@
|
||||
# Agent Coding Guidelines
|
||||
# AGENTS.md — Vault Operations Manual
|
||||
|
||||
**Purpose**: Code style and workflow for agentic coding assistants in this vault
|
||||
**Last Updated**: 2026-01-06
|
||||
**Purpose**: Single source of truth for AI agents operating in this Obsidian vault.
|
||||
**Last Updated**: 2026-09-26
|
||||
|
||||
---
|
||||
|
||||
## Build & Lint Commands
|
||||
## Directory Structure (PARA)
|
||||
|
||||
```
|
||||
00_Inbox/ Temporary capture, process weekly
|
||||
01_Projects/ Time-bound work with deadlines
|
||||
02_Areas/ Ongoing responsibilities (Health, Finance, etc.)
|
||||
03_Resources/ Reference materials and knowledge base
|
||||
04_Archive/ Completed items and clippings
|
||||
05_Attachments/ Media files (images, PDFs)
|
||||
06_Metadata/ Templates and reference docs (8 files)
|
||||
|
||||
.claude/ Agent config, commands, hooks
|
||||
.config/ ESLint, Prettier, TypeScript config
|
||||
.scripts/ Utility scripts (JS/Python)
|
||||
.github/ CI workflows
|
||||
.obsidian/ Obsidian app config (do not rewrite)
|
||||
```
|
||||
|
||||
## Permission Table
|
||||
|
||||
| Path | Rule |
|
||||
|---|---|
|
||||
| `00_Inbox/` | Free to create and edit |
|
||||
| `01_Projects/` | Edit on request |
|
||||
| `03_Resources/` | Edit on request |
|
||||
| `02_Areas/` | **Ask before editing** |
|
||||
| `04_Archive/` | **Never rewrite** — read-only historical record |
|
||||
| `06_Metadata/Templates/` | **Never rewrite** — wired to Obsidian plugins |
|
||||
| `.obsidian/` | **Never rewrite** — app config |
|
||||
| `.obsidian/plugins/*/data.json` | **Hard deny** — may contain secrets |
|
||||
| Credential files (see .gitignore) | **Never read or write** |
|
||||
|
||||
## Frontmatter Conventions
|
||||
|
||||
Active notes (00–03) use these core keys:
|
||||
- `created` (required) — ISO date `YYYY-MM-DD`
|
||||
- `status` — one of: `draft`, `active`, `done`, `archived`
|
||||
- `tags`, `type`, `updated` — optional
|
||||
|
||||
Content keys (never delete): `title`, `description`, `source`, `date`, `author`, `published`, `aliases`
|
||||
|
||||
**Clipper boundary**: `04_Archive/Inbox-Clippings/**` permanently uses the web clipper schema (`date`/`page-title`/`url`). Never migrate.
|
||||
|
||||
## Safety Rules
|
||||
|
||||
1. **Read before writing** — always read a file before editing it
|
||||
2. **Never delete without approval** — ask before removing content
|
||||
3. **Preserve everything when merging** — only remove verified exact duplicates
|
||||
4. **Verify before moving** — check destination exists, update all `[[wikilinks]]` after move
|
||||
5. **Never move numbered folders** (00–06) from vault root
|
||||
6. **Get approval for bulk operations** affecting 5+ files
|
||||
7. **Never commit secrets** — run `.scripts/verify-vault.mjs` before pushing
|
||||
|
||||
## Git Workflow
|
||||
|
||||
```bash
|
||||
# Lint & format (auto-fixes issues)
|
||||
pnpm lint # Run eslint + prettier with auto-fix
|
||||
|
||||
# Check only (no fixes)
|
||||
pnpm lint:check # Verify code style compliance
|
||||
|
||||
# Format only
|
||||
pnpm format # Prettier format all files
|
||||
pnpm format:check # Check formatting without changes
|
||||
|
||||
# Run scripts directly (no test framework configured)
|
||||
node .scripts/update-attachment-links.js
|
||||
GEMINI_API_KEY=xxx node .claude/mcp-servers/gemini-vision.mjs
|
||||
python3 .scripts/rename-chinese-to-english.py
|
||||
pnpm lint # Auto-fix before committing
|
||||
pnpm lint:check # Verify without changes
|
||||
node .scripts/verify-vault.mjs # Secret scanner (CI runs this too)
|
||||
```
|
||||
|
||||
- Commit after each work session with descriptive messages
|
||||
- Pull before starting work
|
||||
- Never force-push to main
|
||||
|
||||
## 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
|
||||
- Link liberally, prefer over-linking
|
||||
|
||||
## Work Approach
|
||||
|
||||
- **Simple tasks** — execute directly
|
||||
- **Complex changes** — propose plan first (affected files, steps, rollback)
|
||||
|
||||
---
|
||||
|
||||
## Code Style Guidelines
|
||||
## Scripts — Code Style
|
||||
|
||||
### TypeScript/JavaScript
|
||||
### JavaScript/TypeScript
|
||||
|
||||
#### Imports
|
||||
- Single quotes, semicolons, `node:` prefix for built-in imports
|
||||
- `camelCase` functions/variables, `UPPER_SNAKE_CASE` constants, `PascalCase` classes
|
||||
- Prefix unused params with `_`
|
||||
- Handle errors in async functions, check env vars early
|
||||
|
||||
```javascript
|
||||
import type { Server } from '@modelcontextprotocol/sdk/server/index.js'
|
||||
import { readFile } from 'node:fs/promises'
|
||||
import path from 'node:path'
|
||||
import fs from 'node:fs'
|
||||
```
|
||||
### Python
|
||||
|
||||
#### Formatting
|
||||
- `snake_case` functions/variables, `UPPER_SNAKE_CASE` constants
|
||||
- Type hints on function signatures
|
||||
|
||||
```javascript
|
||||
// Single quotes for strings, use semicolons
|
||||
const value = 'string'
|
||||
const obj = { name, value }
|
||||
const msg = `Hello ${name}`
|
||||
```
|
||||
|
||||
#### Error Handling
|
||||
|
||||
```javascript
|
||||
// Always handle errors in async functions
|
||||
try {
|
||||
await fs.access(filePath)
|
||||
} catch {
|
||||
throw new Error(`File not found: ${filePath}`)
|
||||
}
|
||||
|
||||
// Check environment variables early
|
||||
if (!process.env.API_KEY) {
|
||||
console.error('❌ API_KEY environment variable is required')
|
||||
process.exit(1)
|
||||
}
|
||||
```
|
||||
|
||||
#### Naming Conventions
|
||||
|
||||
```javascript
|
||||
function analyzeImage(args) {} // camelCase
|
||||
const MAX_ATTEMPTS = 60 // UPPER_SNAKE_CASE
|
||||
const imagePath = 'path/to/file.png' // camelCase
|
||||
class ImageAnalyzer {} // PascalCase
|
||||
function process(data, _unused) {} // Prefix unused with _
|
||||
```
|
||||
|
||||
### Python Scripts
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
from pathlib import Path
|
||||
from typing import List, Dict
|
||||
|
||||
path = Path('05_Attachments/Organized')
|
||||
|
||||
def process_files(files: List[str]) -> Dict[str, str]:
|
||||
"""Process list of files."""
|
||||
return {f: f for f in files}
|
||||
|
||||
file_path = 'path/to/file.md' # snake_case
|
||||
MAX_RETRIES = 3 # UPPER_SNAKE_CASE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Organization
|
||||
|
||||
```bash
|
||||
.claude/mcp-servers/ # MCP server implementations
|
||||
.scripts/ # Utility scripts (JS/Python)
|
||||
.config/ # Config files (eslint, prettier, tsconfig)
|
||||
```
|
||||
|
||||
### Script Structure
|
||||
|
||||
```javascript
|
||||
#!/usr/bin/env node
|
||||
|
||||
import fs from 'node:fs'
|
||||
|
||||
const args = process.argv.slice(2)
|
||||
if (args.length !== 1) {
|
||||
console.log('Usage: node script.js <arg>')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
async function main() {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
main().catch(console.error)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### File Walking
|
||||
|
||||
```javascript
|
||||
function walkDir(dir, callback) {
|
||||
fs.readdirSync(dir).forEach((f) => {
|
||||
const dirPath = path.join(dir, f)
|
||||
const isDirectory = fs.statSync(dirPath).isDirectory()
|
||||
if (isDirectory && !f.includes('node_modules') && !f.includes('.git')) {
|
||||
walkDir(dirPath, callback)
|
||||
} else if (!isDirectory) {
|
||||
callback(dirPath)
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Processing Files
|
||||
|
||||
```javascript
|
||||
walkDir('.', (filepath) => {
|
||||
if (filepath.endsWith('.md')) {
|
||||
let content = fs.readFileSync(filepath, 'utf8')
|
||||
// Process content
|
||||
if (content !== originalContent) {
|
||||
fs.writeFileSync(filepath, content, 'utf8')
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Before Making Changes
|
||||
|
||||
1. Read existing files to understand patterns
|
||||
2. Check package.json for available scripts/dependencies
|
||||
3. Run lint before committing: `pnpm lint`
|
||||
4. Test changes by running scripts directly
|
||||
5. Commit with descriptive message after verification
|
||||
|
||||
---
|
||||
|
||||
**Resources**:
|
||||
### Config
|
||||
|
||||
- ESLint: `.config/eslint.config.js`
|
||||
- Prettier: `.config/.prettierrc.js`
|
||||
|
||||
@@ -1,477 +1,34 @@
|
||||
# Claudesidian: Claude Code + Obsidian Starter Kit
|
||||
# My Obsidian Vault
|
||||
|
||||
Turn your Obsidian vault into an AI-powered second brain using Claude Code.
|
||||
Personal knowledge base using the PARA method, version-controlled with Git.
|
||||
|
||||
## What is this?
|
||||
## Structure
|
||||
|
||||
This is a pre-configured Obsidian vault structure designed to work seamlessly
|
||||
with Claude Code, enabling you to:
|
||||
```
|
||||
00_Inbox/ Capture → process weekly
|
||||
01_Projects/ Time-bound work
|
||||
02_Areas/ Ongoing responsibilities
|
||||
03_Resources/ Reference materials
|
||||
04_Archive/ Completed items & clippings
|
||||
05_Attachments/ Media files
|
||||
06_Metadata/ Templates & reference docs
|
||||
```
|
||||
|
||||
- Use AI as a thinking partner, not just a writing assistant
|
||||
- Organize knowledge using the PARA method
|
||||
- Maintain version control with Git
|
||||
- Access your vault from anywhere (including mobile)
|
||||
## Entry Points
|
||||
|
||||
## Authoritative Entry Points
|
||||
- `AGENTS.md` — operations manual for AI agents (permission table, safety rules, code style)
|
||||
- `06_Metadata/Reference/PARA_METHOD.md` — PARA methodology reference
|
||||
- `06_Metadata/Reference/GIT_WORKFLOW.md` — git workflow guide
|
||||
|
||||
- `README.md` = Project entry point and navigation
|
||||
- `06_Metadata/QUICK_REFERENCE.md` = One-page quick reference
|
||||
- `06_Metadata/WORKFLOWS.md` = Detailed workflows and rules
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Get the Starter Kit
|
||||
|
||||
**Option A: Clone with Git**
|
||||
## Scripts
|
||||
|
||||
```bash
|
||||
# Clone with your preferred folder name (replace 'my-vault' with any name you like)
|
||||
git clone https://github.com/heyitsnoah/claudesidian.git my-vault
|
||||
cd my-vault
|
||||
|
||||
# Examples:
|
||||
# git clone https://github.com/heyitsnoah/claudesidian.git obsidian-notes
|
||||
# git clone https://github.com/heyitsnoah/claudesidian.git knowledge-base
|
||||
# git clone https://github.com/heyitsnoah/claudesidian.git second-brain
|
||||
pnpm lint # Lint + format (auto-fix)
|
||||
pnpm lint:check # Check only
|
||||
pnpm format # Prettier format
|
||||
pnpm vault:stats # Vault statistics
|
||||
```
|
||||
|
||||
**Option B: Download ZIP (no Git required)**
|
||||
## CI
|
||||
|
||||
1. Click "Code" → "Download ZIP" on GitHub
|
||||
2. Extract to your desired location
|
||||
3. Open the folder in Claude Code
|
||||
|
||||
### 2. Run the Setup Wizard
|
||||
|
||||
```bash
|
||||
# Start Claude Code in the directory
|
||||
claude
|
||||
|
||||
# Run the interactive setup wizard (in Claude Code)
|
||||
/init-bootstrap
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Install dependencies automatically
|
||||
- Disconnect from the original claudesidian repository
|
||||
- **Intelligently analyze** your existing vault structure and patterns
|
||||
- **Import your existing Obsidian vault** safely to OLD_VAULT/ (if you have one)
|
||||
- **Research your public work** for personalized context (with your permission)
|
||||
- Ask you about your workflow preferences
|
||||
- Create a personalized CLAUDE.md configuration
|
||||
- Set up your folder structure
|
||||
- Optionally configure Gemini Vision for image/video analysis
|
||||
- Optionally configure Firecrawl for web research
|
||||
- Initialize Git for version control
|
||||
|
||||
### 3. Open in Obsidian (Optional but Recommended)
|
||||
|
||||
- Download [Obsidian](https://obsidian.md)
|
||||
- Open vault from the claudesidian folder
|
||||
- This gives you a visual interface alongside Claude Code
|
||||
|
||||
### 4. Your First Session
|
||||
|
||||
Tell Claude Code:
|
||||
|
||||
```
|
||||
I'm starting a new project about [topic].
|
||||
I'm in thinking mode, not writing mode.
|
||||
Please search my vault for any relevant existing notes,
|
||||
then help me explore this topic by asking questions.
|
||||
```
|
||||
|
||||
Or use one of the pre-configured commands (in Claude Code):
|
||||
|
||||
```
|
||||
/thinking-partner # For collaborative exploration
|
||||
/daily-review # For end-of-day reflection
|
||||
/research-assistant # For deep dives into topics
|
||||
```
|
||||
|
||||
## Folder Structure
|
||||
|
||||
```
|
||||
claudesidian/
|
||||
├── 00_Inbox/ # Temporary capture point for new ideas
|
||||
├── 01_Projects/ # Active, time-bound initiatives
|
||||
├── 02_Areas/ # Ongoing responsibilities
|
||||
├── 03_Resources/ # Reference materials and knowledge base
|
||||
├── 04_Archive/ # Completed projects and inactive items
|
||||
├── 05_Attachments/ # Images, PDFs, and other files
|
||||
├── 06_Metadata/ # Vault configuration and templates
|
||||
│ ├── Reference/ # Documentation and guides
|
||||
│ └── Templates/ # Reusable note templates
|
||||
└── .scripts/ # Helper scripts for automation
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Thinking Mode vs Writing Mode
|
||||
|
||||
**Thinking Mode** (Research & Exploration):
|
||||
|
||||
- Claude asks questions to understand your goals
|
||||
- Searches existing notes for relevant content
|
||||
- Helps make connections between ideas
|
||||
- Maintains a log of insights and progress
|
||||
|
||||
**Writing Mode** (Content Creation):
|
||||
|
||||
- Generates drafts based on your research
|
||||
- Helps structure and edit content
|
||||
- Creates final deliverables
|
||||
|
||||
### The PARA Method
|
||||
|
||||
**Projects**: Have a deadline and specific outcome
|
||||
|
||||
- Example: "Q4 2025 Marketing Strategy"
|
||||
- Create a folder in `01_Projects/`
|
||||
|
||||
**Areas**: Ongoing without an end date
|
||||
|
||||
- Example: "Health", "Finances", "Team Management"
|
||||
- Lives in `02_Areas/`
|
||||
|
||||
**Resources**: Topics of ongoing interest
|
||||
|
||||
- Example: "AI Research", "Writing Tips"
|
||||
- Store in `03_Resources/`
|
||||
|
||||
**Archive**: Inactive items
|
||||
|
||||
- Completed projects with their outputs
|
||||
- Old notes no longer relevant
|
||||
|
||||
## Claude Code Commands
|
||||
|
||||
Pre-configured AI assistants ready to use:
|
||||
|
||||
- `thinking-partner` - Explore ideas through questions
|
||||
- `inbox-processor` - Organize your captures
|
||||
- `research-assistant` - Deep dive into topics
|
||||
- `daily-review` - End of day reflection
|
||||
- `weekly-synthesis` - Find patterns in your week
|
||||
- `create-command` - Build new custom commands
|
||||
- `de-ai-ify` - Remove AI writing patterns from text
|
||||
- `upgrade` - Update to the latest claudesidian version
|
||||
- `init-bootstrap` - Re-run the setup wizard
|
||||
- `install-claudesidian-command` - Install shell command to launch vault from
|
||||
anywhere
|
||||
|
||||
Run with: `/[command-name]` in Claude Code
|
||||
|
||||
### Staying Updated with `/upgrade`
|
||||
|
||||
Claudesidian automatically checks for updates when you start Claude Code and
|
||||
will remind you to run `/upgrade` when new features are available.
|
||||
|
||||
The upgrade command intelligently merges new features while preserving your
|
||||
customizations:
|
||||
|
||||
```bash
|
||||
# Preview what would be updated (recommended first)
|
||||
/upgrade check
|
||||
|
||||
# Run the interactive upgrade
|
||||
/upgrade
|
||||
|
||||
# Skip confirmations for safe updates (advanced)
|
||||
/upgrade force
|
||||
```
|
||||
|
||||
**What the upgrade does:**
|
||||
|
||||
- Creates a timestamped backup before making any changes
|
||||
- Shows you diffs for each file before updating
|
||||
- Preserves your personal notes and customizations
|
||||
- Only updates system files (commands, agents, scripts)
|
||||
- Never touches your content folders (00_Inbox, 01_Projects, etc.)
|
||||
- Provides rollback capability if needed
|
||||
|
||||
**Safety features:**
|
||||
|
||||
- All your personal content is protected
|
||||
- Complete backup created in `.backup/upgrade-[timestamp]/`
|
||||
- File-by-file review and confirmation
|
||||
- Progress tracked in `.upgrade-checklist.md`
|
||||
- Can be stopped and resumed at any time
|
||||
|
||||
## Vision & Document Analysis (Optional)
|
||||
|
||||
With [Google Gemini](https://ai.google.dev/) MCP configured, Claude Code can
|
||||
process your attachments directly without having to describe them. This means:
|
||||
|
||||
- **Direct image analysis**: Claude sees the actual image, not your description
|
||||
- **PDF text extraction**: Full document text without copy-pasting
|
||||
- **Bulk processing**: Analyze multiple screenshots or documents at once
|
||||
- **Smart organization**: Auto-generate filenames based on image content
|
||||
- **Comparison tasks**: Compare before/after screenshots, designs, etc.
|
||||
|
||||
**Why this matters**: Instead of describing "a screenshot showing an error
|
||||
message", Claude Code directly sees and reads the error. Perfect for debugging
|
||||
UI issues, analyzing charts, or processing scanned documents.
|
||||
|
||||
**Getting a Gemini API key:**
|
||||
|
||||
1. Visit [Google AI Studio](https://aistudio.google.com)
|
||||
2. Sign in with your Google account
|
||||
3. Click "Get API key" in the left sidebar
|
||||
4. Create a new API key (it's free!)
|
||||
5. Set it in your environment: `export GEMINI_API_KEY="your-key-here"`
|
||||
|
||||
See `.claude/mcp-servers/README.md` for full setup instructions
|
||||
|
||||
## Web Research (Optional)
|
||||
|
||||
With [Firecrawl](https://www.firecrawl.dev/) configured, our helper scripts
|
||||
fetch and save full web content directly to your vault. This means:
|
||||
|
||||
- **Full text capture**: Scripts pipe complete article text to files, not
|
||||
summaries
|
||||
- **Context preservation**: Claude doesn't need to hold web content in memory
|
||||
- **Batch processing**: Save multiple articles at once with `firecrawl-batch.sh`
|
||||
- **Clean markdown**: Web pages converted to readable, searchable markdown
|
||||
- **Permanent archive**: Your research stays in your vault forever
|
||||
|
||||
**Why this matters**: Instead of Claude reading a webpage and summarizing it
|
||||
(losing detail), the scripts save the FULL text. Claude can then search and
|
||||
analyze thousands of saved articles without hitting context limits. Perfect for
|
||||
research projects, documentation archives, or building a knowledge base.
|
||||
|
||||
**Example workflow:**
|
||||
|
||||
```bash
|
||||
# Save a single article
|
||||
pnpm firecrawl:scrape -- "https://example.com/article" "03_Resources/Articles"
|
||||
|
||||
# Batch save multiple URLs
|
||||
pnpm firecrawl:batch -- urls.txt "03_Resources/Research"
|
||||
```
|
||||
|
||||
**Getting a Firecrawl API key:**
|
||||
|
||||
1. Visit [Firecrawl](https://www.firecrawl.dev) and sign up
|
||||
2. Get 300 free credits to start (open-source, can self-host)
|
||||
3. Go to your dashboard to find your API key
|
||||
4. Copy the key (format: `fc-xxxxx...`)
|
||||
5. Set it in your environment: `export FIRECRAWL_API_KEY="fc-your-key-here"`
|
||||
|
||||
## Helper Scripts
|
||||
|
||||
Run these with `pnpm`:
|
||||
|
||||
- `attachments:list` - Show unprocessed attachments
|
||||
- `attachments:organized` - Count organized files
|
||||
- `attachments:sizes` - Find large files
|
||||
- `attachments:orphans` - Find unreferenced attachments
|
||||
- `vault:stats` - Show vault statistics
|
||||
|
||||
If you do not have `pnpm` installed, use `npm run <script>` as a fallback.
|
||||
|
||||
## Paths
|
||||
|
||||
**New User Path**:
|
||||
- Start at `README.md`
|
||||
- Use `06_Metadata/QUICK_REFERENCE.md` for daily use
|
||||
- Read `06_Metadata/WORKFLOWS.md` for full rules and workflows
|
||||
|
||||
**Maintainer Path**:
|
||||
- Review `README.md` entry points and changes
|
||||
- Validate `06_Metadata/QUICK_REFERENCE.md` for daily command accuracy
|
||||
- Update `06_Metadata/WORKFLOWS.md` for rule changes
|
||||
|
||||
## Advanced Setup
|
||||
|
||||
### Quick Launch from Anywhere
|
||||
|
||||
Install a shell command to launch your vault from any directory:
|
||||
|
||||
```bash
|
||||
# In Claude Code, run:
|
||||
/install-claudesidian-command
|
||||
```
|
||||
|
||||
This creates a `claudesidian` alias that:
|
||||
|
||||
- Changes to your vault directory automatically
|
||||
- Tries to resume your existing session (if one exists)
|
||||
- Falls back to starting a new session
|
||||
- Returns to your original directory when done
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# From anywhere in your terminal:
|
||||
claudesidian
|
||||
|
||||
# It will automatically resume your last session or start a new one
|
||||
```
|
||||
|
||||
The command is added to your shell config (~/.zshrc, ~/.bashrc, etc.) so it
|
||||
persists across terminal sessions.
|
||||
|
||||
### Git Integration
|
||||
|
||||
Initialize Git for version control:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial vault setup"
|
||||
git remote add origin your-repo-url
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
Best practices:
|
||||
|
||||
- Commit after each work session
|
||||
- Use descriptive commit messages
|
||||
- Pull before starting work
|
||||
|
||||
### Mobile Access
|
||||
|
||||
1. Set up a small server (mini PC, cloud VPS, or home server)
|
||||
2. Install Tailscale for secure VPN access
|
||||
3. Clone your vault to the server
|
||||
4. Use Termius or similar SSH client on mobile
|
||||
5. Run Claude Code remotely
|
||||
|
||||
### Custom Commands
|
||||
|
||||
Create specialized commands by saving instructions in `.claude/commands/`:
|
||||
|
||||
**Research Assistant** (`06_Metadata/Agents/research-assistant.md`):
|
||||
|
||||
```markdown
|
||||
You are a research assistant.
|
||||
|
||||
- Search the vault for relevant information
|
||||
- Synthesize findings from multiple sources
|
||||
- Identify gaps in knowledge
|
||||
- Suggest areas for further exploration
|
||||
```
|
||||
|
||||
## Tips & Best Practices
|
||||
|
||||
### From Experience
|
||||
|
||||
1. **Start in thinking mode**: Resist the urge to generate content immediately
|
||||
2. **Be a token maximalist**: More context = better results
|
||||
3. **Save everything**: Capture chats, fragments, partial thoughts
|
||||
4. **Trust but verify**: Always read AI-generated content
|
||||
5. **Break your flow**: AI helps you resume easily
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Claude Code can't find my notes
|
||||
|
||||
- Make sure you're running Claude Code from the vault root directory
|
||||
- Check file permissions
|
||||
- Verify markdown files have `.md` extension
|
||||
|
||||
### Git conflicts
|
||||
|
||||
- Always pull before starting work
|
||||
- Commit frequently with clear messages
|
||||
- Use branches for experimental changes
|
||||
|
||||
### Attachment management
|
||||
|
||||
- Run `pnpm attachments:create-organized` to set up folders
|
||||
- Use helper scripts to find orphaned files
|
||||
- Keep attachments under 10MB for Git
|
||||
|
||||
## Philosophy
|
||||
|
||||
This setup is based on key principles:
|
||||
|
||||
1. **AI amplifies thinking, not just writing**
|
||||
2. **Local files = full control**
|
||||
3. **Structure enables creativity**
|
||||
4. **Iteration beats perfection**
|
||||
5. **The goal is insight, not just information**
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions from the community! This is a living template that gets
|
||||
better with everyone's input.
|
||||
|
||||
### How to Contribute
|
||||
|
||||
1. **Fork the repository** on GitHub
|
||||
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
|
||||
3. **Make your changes**
|
||||
4. **Test your changes** to ensure everything works
|
||||
5. **Commit your changes** (`git commit -m 'Add amazing feature'`)
|
||||
6. **Push to the branch** (`git push origin feature/amazing-feature`)
|
||||
7. **Open a Pull Request** with a clear description of what you've done
|
||||
|
||||
### What We're Looking For
|
||||
|
||||
- **New commands**: Useful Claude Code commands for common workflows
|
||||
- **New agents**: Specialized agents for specific tasks
|
||||
- **Documentation improvements**: Better explanations, examples, or guides
|
||||
- **Bug fixes**: Found something broken? Fix it!
|
||||
- **Workflow templates**: Share your productive workflows
|
||||
- **Helper scripts**: Automation tools that make vault management easier
|
||||
- **Integration guides**: Connect Claudesidian with other tools
|
||||
- **Core updates**: Improvements to the upgrade system, setup wizard, or other
|
||||
core features
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Keep commands focused and single-purpose
|
||||
- Write clear documentation with examples
|
||||
- Test thoroughly before submitting
|
||||
- Follow existing code style and structure
|
||||
- Update the 06_Metadata/CHANGELOG.md with your changes
|
||||
- **AI-generated content is welcome, but you MUST carefully read and review
|
||||
everything before submitting** - never submit code you don't understand
|
||||
|
||||
### Getting Updates
|
||||
|
||||
When new features are contributed and merged, users can easily get them with:
|
||||
|
||||
```bash
|
||||
/upgrade
|
||||
```
|
||||
|
||||
The upgrade command intelligently merges new features while preserving your
|
||||
personal customizations, making it easy to benefit from community contributions
|
||||
without losing your work.
|
||||
|
||||
### Questions or Ideas?
|
||||
|
||||
- Open an issue to discuss major changes before starting work
|
||||
- Join discussions in existing issues
|
||||
- Share your use cases - they help us understand needs better
|
||||
|
||||
Remember: best practices emerge from use, not theory. Your real-world experience
|
||||
makes this better for everyone!
|
||||
|
||||
## Resources
|
||||
|
||||
- [Obsidian Documentation](https://help.obsidian.md)
|
||||
- [PARA Method](https://fortelabs.com/blog/para/)
|
||||
- [Claude Code Documentation](https://claude.ai/docs)
|
||||
|
||||
## Inspiration
|
||||
|
||||
This starter kit was inspired by the workflows discussed in:
|
||||
|
||||
- [How to Use Claude Code as a Second Brain](https://every.to/podcast/how-to-use-claude-code-as-a-thinking-partner) -
|
||||
Noah Brier's interview with Dan Shipper
|
||||
- Built by the team at [Alephic](https://alephic.com) - an AI-first strategy and
|
||||
software partner that helps organizations solve complex challenges through
|
||||
custom AI systems
|
||||
|
||||
## License
|
||||
|
||||
MIT - Use this however you want. Make it your own.
|
||||
|
||||
---
|
||||
|
||||
_Remember: The bicycle feels wobbly at first, then you forget it was ever hard._
|
||||
GitHub Actions runs lint, format check, and secret scanning on every push/PR to main.
|
||||
|
||||
+3
-7
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "claudesidian",
|
||||
"version": "0.14.2",
|
||||
"description": "Claude Code + Obsidian Starter Kit - AI-powered second brain",
|
||||
"name": "my-vault",
|
||||
"version": "1.0.0",
|
||||
"description": "Personal Obsidian vault with PARA methodology",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"setup": "pnpm install && echo '✅ Setup complete! Configure GEMINI_API_KEY for vision features'",
|
||||
@@ -22,10 +22,6 @@
|
||||
"attachments:update-links": "node .scripts/update-attachment-links.js",
|
||||
"transcript:extract": ".scripts/transcript-extract.sh",
|
||||
"vault:stats": ".scripts/vault-stats.sh",
|
||||
"check-updates": "REMOTE=$(curl -s https://raw.githubusercontent.com/heyitsnoah/claudesidian/main/package.json | grep version | head -1 | sed 's/.*: \"\\(.*\\)\".*/\\1/') && LOCAL=$(grep version package.json | head -1 | sed 's/.*: \"\\(.*\\)\".*/\\1/') && if [ \"$LOCAL\" != \"$REMOTE\" ]; then echo -e \"📦 Update available! Latest: $REMOTE (you have: $LOCAL)\\n\\n⬇\\n/upgrade\\n⬆\\n\\n## What will this do\\n\\n✅ Update to the latest version of Claudesidian\\n✅ Get new features and improvements\\n✅ Preserve your vault content and settings\\n\\n\"; fi",
|
||||
"firecrawl:scrape": ".scripts/firecrawl-scrape.sh",
|
||||
"firecrawl:batch": ".scripts/firecrawl-batch.sh",
|
||||
"firecrawl:setup": "source .scripts/setup-firecrawl-env.sh",
|
||||
"daily-note": "node .scripts/daily-note.js"
|
||||
},
|
||||
"keywords": [
|
||||
|
||||
Reference in New Issue
Block a user