Claudesidian: Claude Code + Obsidian Starter Kit

Turn your Obsidian vault into an AI-powered second brain using Claude Code.

What is this?

This is a pre-configured Obsidian vault structure designed to work seamlessly with Claude Code, enabling you to:

• Use AI as a thinking partner, not just a writing assistant
• Organize knowledge using the PARA method
• Maintain version control with Git
• Access your vault from anywhere (including mobile)

Quick Start

1. Get the Starter Kit

Option A: Clone with Git

# Clone with your preferred folder name (replace 'my-vault' with any name you like)
git clone https://github.com/heyitsnoah/claudesidian.git my-vault
cd my-vault

# Examples:
# git clone https://github.com/heyitsnoah/claudesidian.git obsidian-notes
# git clone https://github.com/heyitsnoah/claudesidian.git knowledge-base
# git clone https://github.com/heyitsnoah/claudesidian.git second-brain

Option B: Download ZIP (no Git required)

1. Click "Code" → "Download ZIP" on GitHub
2. Extract to your desired location
3. Open the folder in Claude Code

2. Run the Setup Wizard

# 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
• 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:

# 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 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
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 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:

# Save a single article
npm run firecrawl:scrape -- "https://example.com/article" "03_Resources/Articles"

# Batch save multiple URLs
npm run firecrawl:batch -- urls.txt "03_Resources/Research"

Getting a Firecrawl API key:

1. Visit Firecrawl 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

Advanced Setup

Quick Launch from Anywhere

Install a shell command to launch your vault from any directory:

# 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:

# 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:

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):

You are a research assistant.

- Search the vault for rel