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:
|
description:
|
||||||
Add or update YAML frontmatter properties to enhance note organization
|
Add or update YAML frontmatter properties to enhance note organization
|
||||||
|
|||||||
@@ -1,3 +1,6 @@
|
|||||||
|
risk: low
|
||||||
|
writes: .claude/sessions/
|
||||||
|
|
||||||
---
|
---
|
||||||
allowed-tools: Read
|
allowed-tools: Read
|
||||||
description: Summarize and compress conversation history to reduce token usage
|
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
|
allowed-tools: Write, Read, Bash(ls:*, mkdir:*), Edit
|
||||||
description: Create a new Claude Code slash command
|
description: Create a new Claude Code slash command
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
# Daily Review
|
# Daily Review
|
||||||
|
risk: medium
|
||||||
|
writes: 00_Inbox/ daily notes
|
||||||
|
|
||||||
Conduct an end-of-day review to capture progress and set up tomorrow.
|
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
|
allowed-tools: Read, Write, Edit
|
||||||
description: Remove AI-generated jargon and restore human voice to text
|
description: Remove AI-generated jargon and restore human voice to text
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
# download-attachment
|
# download-attachment
|
||||||
|
risk: low
|
||||||
|
writes: 05_Attachments/
|
||||||
|
|
||||||
Download files from URLs to attachments folder and organize them with
|
Download files from URLs to attachments folder and organize them with
|
||||||
descriptive names.
|
descriptive names.
|
||||||
|
|||||||
@@ -1,3 +1,6 @@
|
|||||||
|
risk: low
|
||||||
|
writes: none (generates text)
|
||||||
|
|
||||||
---
|
---
|
||||||
allowed-tools: Bash, AskUserQuestion
|
allowed-tools: Bash, AskUserQuestion
|
||||||
description: AI-generated git commit messages from staged changes
|
description: AI-generated git commit messages from staged changes
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
# Inbox Processor
|
# Inbox Processor
|
||||||
|
risk: medium
|
||||||
|
writes: 00_Inbox → 01-03
|
||||||
|
|
||||||
Help organize and process items in the 00_Inbox folder according to the PARA
|
Help organize and process items in the 00_Inbox folder according to the PARA
|
||||||
method.
|
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
|
name: pragmatic-review
|
||||||
description:
|
description:
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
# Pull Request Command
|
# Pull Request Command
|
||||||
|
risk: high
|
||||||
|
writes: git remote (push + PR)
|
||||||
|
|
||||||
Creates a new feature branch, commits changes, pushes to GitHub, and opens a
|
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.
|
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
|
name: release
|
||||||
description:
|
description:
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
# Research Assistant
|
# Research Assistant
|
||||||
|
risk: medium
|
||||||
|
writes: 03_Resources/
|
||||||
|
|
||||||
Conduct thorough research on topics by searching the vault and synthesizing
|
Conduct thorough research on topics by searching the vault and synthesizing
|
||||||
findings.
|
findings.
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
# Thinking Partner
|
# Thinking Partner
|
||||||
|
risk: low
|
||||||
|
writes: none (conversation)
|
||||||
|
|
||||||
You are a collaborative thinking partner specializing in helping people explore
|
You are a collaborative thinking partner specializing in helping people explore
|
||||||
complex problems. Your role is to facilitate thinking through careful
|
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
|
# Weekly Synthesis
|
||||||
|
risk: medium
|
||||||
|
writes: 00_Inbox/ weekly notes
|
||||||
|
|
||||||
Create a comprehensive synthesis of the week's work and thinking.
|
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": {
|
"permissions": {
|
||||||
"allow": [
|
"allow": [
|
||||||
"Bash(npm run | grep daily-note)",
|
"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(wc:*)",
|
||||||
"Bash(find:*)",
|
"Bash(find:*)",
|
||||||
"Bash(git add:*)"
|
"Bash(git add:*)"
|
||||||
],
|
],
|
||||||
"deny": [],
|
"deny": [
|
||||||
"ask": []
|
"Edit(.obsidian/plugins/*/data.json)",
|
||||||
},
|
"Edit(04_Archive/**)",
|
||||||
"hooks": {
|
"Bash(git push:*)",
|
||||||
"SessionStart": [
|
"Bash(git add .:*)"
|
||||||
{
|
|
||||||
"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"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
],
|
],
|
||||||
"UserPromptSubmit": [
|
"ask": [
|
||||||
{
|
"Edit(.obsidian/**)"
|
||||||
"hooks": [
|
|
||||||
{
|
|
||||||
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-discovery.sh",
|
|
||||||
"timeout": 5000,
|
|
||||||
"type": "command"
|
|
||||||
}
|
|
||||||
]
|
]
|
||||||
}
|
},
|
||||||
]
|
"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
|
**Purpose**: Single source of truth for AI agents operating in this Obsidian vault.
|
||||||
**Last Updated**: 2026-01-06
|
**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
|
```bash
|
||||||
# Lint & format (auto-fixes issues)
|
pnpm lint # Auto-fix before committing
|
||||||
pnpm lint # Run eslint + prettier with auto-fix
|
pnpm lint:check # Verify without changes
|
||||||
|
node .scripts/verify-vault.mjs # Secret scanner (CI runs this too)
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
- 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
|
### Python
|
||||||
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'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Formatting
|
- `snake_case` functions/variables, `UPPER_SNAKE_CASE` constants
|
||||||
|
- Type hints on function signatures
|
||||||
|
|
||||||
```javascript
|
### Config
|
||||||
// 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**:
|
|
||||||
|
|
||||||
- ESLint: `.config/eslint.config.js`
|
- ESLint: `.config/eslint.config.js`
|
||||||
- Prettier: `.config/.prettierrc.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
|
## Entry Points
|
||||||
- Organize knowledge using the PARA method
|
|
||||||
- Maintain version control with Git
|
|
||||||
- Access your vault from anywhere (including mobile)
|
|
||||||
|
|
||||||
## 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
|
## Scripts
|
||||||
- `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**
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone with your preferred folder name (replace 'my-vault' with any name you like)
|
pnpm lint # Lint + format (auto-fix)
|
||||||
git clone https://github.com/heyitsnoah/claudesidian.git my-vault
|
pnpm lint:check # Check only
|
||||||
cd my-vault
|
pnpm format # Prettier format
|
||||||
|
pnpm vault:stats # Vault statistics
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Option B: Download ZIP (no Git required)**
|
## CI
|
||||||
|
|
||||||
1. Click "Code" → "Download ZIP" on GitHub
|
GitHub Actions runs lint, format check, and secret scanning on every push/PR to main.
|
||||||
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._
|
|
||||||
|
|||||||
+3
-7
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "claudesidian",
|
"name": "my-vault",
|
||||||
"version": "0.14.2",
|
"version": "1.0.0",
|
||||||
"description": "Claude Code + Obsidian Starter Kit - AI-powered second brain",
|
"description": "Personal Obsidian vault with PARA methodology",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"setup": "pnpm install && echo '✅ Setup complete! Configure GEMINI_API_KEY for vision features'",
|
"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",
|
"attachments:update-links": "node .scripts/update-attachment-links.js",
|
||||||
"transcript:extract": ".scripts/transcript-extract.sh",
|
"transcript:extract": ".scripts/transcript-extract.sh",
|
||||||
"vault:stats": ".scripts/vault-stats.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"
|
"daily-note": "node .scripts/daily-note.js"
|
||||||
},
|
},
|
||||||
"keywords": [
|
"keywords": [
|
||||||
|
|||||||
Reference in New Issue
Block a user