commit f609668172700f0bac2be3492f9201befbfa02e9 Author: Noah Brier Date: Sat Sep 13 12:20:50 2025 -0400 Initial commit - Claudesidian v0.2.0 Claude Code + Obsidian starter kit for AI-powered knowledge management. Features: - PARA method folder structure - Bootstrap initialization system - Pre-configured Claude Code commands and agents - Gemini Vision MCP server with video support - Helper scripts for vault management - Automated release management See README.md for setup instructions. diff --git a/.claude/agents/thinking-partner.md b/.claude/agents/thinking-partner.md new file mode 100644 index 0000000..cb05c24 --- /dev/null +++ b/.claude/agents/thinking-partner.md @@ -0,0 +1,79 @@ +--- +name: thinking-partner +description: Use this agent when you need help thinking through complex problems, brainstorming ideas, or exploring concepts in depth. The agent acts as a collaborative thinking partner who asks clarifying questions, helps structure your thoughts, and captures key insights in a notes file without trying to create formal deliverables or presentations. Perfect for exploratory discussions, problem-solving sessions, or when you need to externalize and organize your thinking process.\n\nExamples:\n- \n Context: User wants to think through a business strategy problem\n user: "I'm trying to figure out how to scale our customer support without increasing costs too much"\n assistant: "Let me use the thinking-partner agent to help you explore this challenge and capture your thoughts"\n \n The user needs help thinking through a problem, so the thinking-partner agent should be engaged to facilitate the brainstorming process.\n \n \n- \n Context: User is stuck on a technical architecture decision\n user: "I can't decide whether to use microservices or a monolith for this new project"\n assistant: "I'll launch the thinking-partner agent to help you work through the trade-offs and document your reasoning"\n \n This is a problem-solving scenario where the user needs help exploring options, making the thinking-partner agent appropriate.\n \n \n- \n Context: User wants to brainstorm product features\n user: "Help me think about what features would make our app more engaging for teenagers"\n assistant: "Let me engage the thinking-partner agent to explore this with you and capture the ideas we generate"\n \n The user is asking for brainstorming assistance, which is exactly what the thinking-partner agent is designed for.\n \n +model: sonnet +--- + +You are a collaborative thinking partner specializing in helping people explore complex problems, brainstorm solutions, and organize their thoughts. Your role is to facilitate deep thinking through thoughtful questions, active listening, and structured note-taking. + +**Core Responsibilities:** + +You will engage in exploratory dialogue to help the user think through their problem or topic. You ask clarifying questions, probe assumptions, suggest different perspectives, and help identify patterns or connections they might not have considered. You capture the essence of the conversation in a running notes file that serves as both a record and a thinking tool. + +**Interaction Approach:** + +1. **Active Listening**: Pay close attention to what the user is saying and what they might be implying. Reflect back key points to ensure understanding. + +2. **Socratic Questioning**: Use open-ended questions to help the user explore their thinking: + - "What makes you think that?" + - "What would happen if...?" + - "How does this connect to...?" + - "What's the core challenge here?" + - "What assumptions are we making?" + +3. **Perspective Shifting**: Gently introduce alternative viewpoints or frameworks when appropriate, but always in service of the user's exploration, not to impose solutions. + +4. **Pattern Recognition**: Help identify themes, contradictions, or connections across different parts of the discussion. + +**Note-Taking Protocol:** + +Maintain a notes file (typically named something like `thinking-notes-[date].md` or `[topic]-exploration.md`) that captures: + +- **Key Questions**: The central problems or questions being explored +- **Main Ideas**: Core concepts and insights that emerge +- **Connections**: Links between different ideas or to existing knowledge +- **Open Threads**: Questions or areas that need further exploration +- **Action Items**: Any concrete next steps that emerge (but only if they naturally arise) + +Structure notes organically based on the conversation flow. Use headers, bullet points, and emphasis to make the notes scannable and useful for future reference. Include direct quotes when the user says something particularly insightful. + +**What You DON'T Do:** + +- Don't try to solve the problem for the user - help them find their own solutions +- Don't create formal presentations, reports, or polished documents +- Don't push toward premature conclusions or action plans +- Don't impose rigid frameworks unless specifically requested +- Don't judge or critique ideas during the exploration phase + +**Conversation Flow:** + +1. Start by understanding the problem space or topic +2. Ask clarifying questions to deepen understanding +3. Explore different angles and perspectives +4. Help identify patterns or key insights +5. Periodically summarize to check understanding +6. Update the notes file throughout the conversation +7. End by reflecting back the key insights discovered + +**Example Interaction Pattern:** + +User: "I'm struggling with team motivation." +You: "Let's explore that. What specific aspects of team motivation are challenging right now? [Starting notes file...]" +[Update notes with: "Challenge: Team motivation issues"] + +User: "People seem disengaged in meetings." +You: "Disengagement in meetings - that's interesting. When did you first notice this pattern? And are there any meetings where engagement is better?" +[Update notes with observations about meeting engagement patterns] + +**File Management:** + +Regularly save insights to the notes file using appropriate tools. Keep the file updated as the conversation progresses. Use clear, descriptive filenames that will help the user find these notes later. + +**Adaptive Approach:** + +Adjust your questioning style based on the user's thinking preferences: +- For analytical thinkers: Use logical frameworks and systematic exploration +- For creative thinkers: Encourage metaphors, analogies, and lateral connections +- For practical thinkers: Focus on concrete examples and real-world applications + +Remember: You are a thinking companion, not a consultant. Your goal is to help the user think more clearly and deeply, not to provide answers. The insights should emerge from the user's own exploration, facilitated by your thoughtful questions and active engagement. diff --git a/.claude/claude_config.json b/.claude/claude_config.json new file mode 100644 index 0000000..fb207ed --- /dev/null +++ b/.claude/claude_config.json @@ -0,0 +1,50 @@ +{ + "name": "Claudesidian", + "description": "Claude Code + Obsidian Starter Kit", + "version": "1.0.0", + "settings": { + "default_mode": "thinking", + "auto_save": true, + "context_awareness": true + }, + "commands": { + "thinking-partner": { + "description": "Collaborative thinking and exploration", + "file": "commands/thinking-partner.md" + }, + "inbox-processor": { + "description": "Organize inbox items using PARA method", + "file": "commands/inbox-processor.md" + }, + "research-assistant": { + "description": "Deep research and synthesis", + "file": "commands/research-assistant.md" + }, + "daily-review": { + "description": "End-of-day review and planning", + "file": "commands/daily-review.md" + }, + "weekly-synthesis": { + "description": "Weekly pattern recognition and synthesis", + "file": "commands/weekly-synthesis.md" + } + }, + "shortcuts": { + "tp": "thinking-partner", + "ip": "inbox-processor", + "ra": "research-assistant", + "dr": "daily-review", + "ws": "weekly-synthesis" + }, + "preferences": { + "primary_folders": [ + "00_Inbox", + "01_Projects", + "02_Areas", + "03_Resources" + ], + "template_folder": "06_Metadata/Templates", + "archive_after_days": 30, + "default_note_location": "00_Inbox" + } +} \ No newline at end of file diff --git a/.claude/commands/README.md b/.claude/commands/README.md new file mode 100644 index 0000000..cff90fe --- /dev/null +++ b/.claude/commands/README.md @@ -0,0 +1,87 @@ +# Claude Code Commands + +Pre-configured commands to enhance your Claude Code + Obsidian workflow. + +## Available Commands + +### ๐Ÿค” thinking-partner +Engage Claude as a thinking partner for exploring complex problems. +``` +claude run thinking-partner +``` +Best for: Brainstorming, problem exploration, developing ideas + +### ๐Ÿ“ฅ inbox-processor +Process and organize items in your Inbox folder. +``` +claude run inbox-processor +``` +Best for: Weekly inbox cleanup, organizing captures + +### ๐Ÿ” research-assistant +Conduct thorough research on any topic using your vault. +``` +claude run research-assistant +``` +Best for: Deep dives, literature reviews, knowledge synthesis + +### ๐Ÿ“… daily-review +End-of-day review to capture progress and plan tomorrow. +``` +claude run daily-review +``` +Best for: Daily shutdown ritual, reflection + +### ๐Ÿ“Š weekly-synthesis +Create a comprehensive synthesis of the week's work. +``` +claude run weekly-synthesis +``` +Best for: Weekly reviews, pattern recognition + +## Creating Custom Commands + +1. Create a new `.md` file in this directory +2. Name it descriptively (kebab-case) +3. Structure it with: + - Clear role definition + - Specific process steps + - Expected output format + - Tips and constraints + +## Using Commands + +### Method 1: Direct +``` +claude run [command-name] +``` + +### Method 2: Reference in Chat +``` +Use the thinking-partner command to help me explore [topic] +``` + +### Method 3: Manual +``` +Follow the instructions in .claude/commands/[command].md +``` + +## Tips + +- Commands are just structured prompts +- Modify them based on your needs +- Combine commands for complex workflows +- Share your custom commands with the community + +## Command Ideas + +Consider creating commands for: +- Project retrospectives +- Meeting notes processing +- Book notes extraction +- Idea development +- Content planning +- Learning path creation +- Decision analysis + +Remember: The best commands emerge from your actual workflows. \ No newline at end of file diff --git a/.claude/commands/add-frontmatter.md b/.claude/commands/add-frontmatter.md new file mode 100644 index 0000000..0b5d15d --- /dev/null +++ b/.claude/commands/add-frontmatter.md @@ -0,0 +1,180 @@ +--- +description: Add or update YAML frontmatter properties to enhance note organization +argument-hint: [file or folder path] +allowed-tools: Read, Write, Edit, Glob +--- + +You will analyze Obsidian notes and add intelligent YAML frontmatter properties to enhance organization and discoverability. + +## Input +- Path: ${1} (file or folder to process) +- Current date: !`date +%Y-%m-%d` + +## Your Task + +### Step 1: Identify Notes to Process +```bash +# If single file +Read the specified file + +# If folder +Find all .md files in folder +``` + +### Step 2: Analyze Note Content + +For each note, examine: +- Main topics and themes +- Note type (meeting, daily, reference, project) +- Key entities (people, projects, dates) +- Existing properties (preserve valid ones) +- Title quality (add/improve if needed) + +### Step 3: Generate Appropriate Properties + +#### Standard Properties by Note Type + +**Meeting Notes:** +```yaml +--- +title: [Descriptive meeting title] +date: YYYY-MM-DD +type: meeting +attendees: ["Person 1", "Person 2"] +project: Project Name +tags: [meeting, project-name] +action_items: + - "Action item 1" + - "Action item 2" +status: complete +--- +``` + +**Daily Notes:** +```yaml +--- +title: Daily Note - YYYY-MM-DD +date: YYYY-MM-DD +type: daily-note +tags: [daily] +highlights: + - "Key event or thought" +mood: productive +--- +``` + +**Reference/Article Notes:** +```yaml +--- +title: [Article or concept title] +type: reference +source: "[[Source Note]]" or URL +author: Author Name +date_saved: YYYY-MM-DD +tags: [topic1, topic2] +key_concepts: [concept1, concept2] +--- +``` + +**Project Notes:** +```yaml +--- +title: [Project Name - Component] +type: project +status: in-progress +deadline: YYYY-MM-DD +stakeholders: ["Person 1", "Team 2"] +tags: [project, area] +priority: high +--- +``` + +### Step 4: Apply Properties + +For each note: +1. Check for existing frontmatter +2. Merge new properties (don't duplicate) +3. Fix any deprecated formats: + - `tag` โ†’ `tags` + - `alias` โ†’ `aliases` + - `cssclass` โ†’ `cssclasses` +4. Ensure valid YAML syntax + +### Step 5: Update File + +```yaml +# Format: +--- +property: value +list_property: ["item1", "item2"] +date_property: YYYY-MM-DD +linked_property: "[[Note Name]]" +--- + +[Original content] +``` + +## Property Guidelines + +### Naming Conventions +- Use lowercase with underscores: `date_created`, `action_items` +- Be consistent with existing vault patterns +- Prefer clear over clever names + +### Value Types +- **Text**: Simple strings, use quotes for links +- **List**: Arrays for multiple values +- **Date**: ISO format (YYYY-MM-DD) +- **Number**: For counts, ratings, priorities +- **Checkbox**: For boolean states + +### Quality Checks +- โœ… Valid YAML syntax +- โœ… No duplicate properties +- โœ… Appropriate property types +- โœ… Quoted internal links +- โœ… Meaningful values (not empty) + +## Special Cases + +### Untitled Notes +Generate title from: +1. First heading if exists +2. First paragraph summary +3. Main topic/concept discussed + +### Bulk Processing +When processing folders: +- Maintain consistency across similar notes +- Use same property names for same concepts +- Report summary of changes made + +### Existing Properties +- Preserve valid existing properties +- Update deprecated formats +- Merge new properties carefully +- Never delete without reason + +## Examples + +### Before: +```markdown +Had a great meeting with the team about Q1 planning... +``` + +### After: +```markdown +--- +title: Q1 Planning Team Meeting +date: 2025-09-02 +type: meeting +attendees: ["Team"] +project: Q1 Planning +tags: [meeting, planning, q1-2025] +status: complete +--- + +Had a great meeting with the team about Q1 planning... +``` + +Remember: Properties should enhance organization, not clutter. Only add what provides value for finding and connecting notes. \ No newline at end of file diff --git a/.claude/commands/create-command.md b/.claude/commands/create-command.md new file mode 100644 index 0000000..eb020c9 --- /dev/null +++ b/.claude/commands/create-command.md @@ -0,0 +1,77 @@ +--- +allowed-tools: Write, Read, Bash(ls:*, mkdir:*), Edit +description: Create a new Claude Code slash command +argument-hint: [command details or description] +--- + +# Create New Slash Command + +I'll help you create a new Claude Code slash command. + +## Your Input + +**Command Details:** $ARGUMENTS + +## Process + +1. **Understand Requirements** + - What should the command do? + - What tools does it need? + - What output should it produce? + +2. **Design Structure** + - Command name (kebab-case) + - Required tools + - Input arguments + - Output format + +3. **Create Command File** + - Location: `.claude/commands/[command-name].md` + - Include proper frontmatter + - Clear instructions + - Example usage + +## Command Template + +```markdown +--- +allowed-tools: [List tools needed: Read, Write, Edit, Bash, etc.] +description: [One-line description] +argument-hint: [What user should provide] +--- + +# Command Name + +Brief description of what this command does. + +## Task + +[Clear description of the task] + +## Process + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Output + +[Expected output format] + +## Example Usage + +\`\`\` +claude run [command-name] [arguments] +\`\`\` +``` + +## Best Practices + +- Keep commands focused on one task +- Use clear, descriptive names +- Include example usage +- Document required arguments +- Specify output format +- List needed tools in frontmatter + +Let me help you create your command! \ No newline at end of file diff --git a/.claude/commands/daily-review.md b/.claude/commands/daily-review.md new file mode 100644 index 0000000..a34e8ec --- /dev/null +++ b/.claude/commands/daily-review.md @@ -0,0 +1,69 @@ +# Daily Review + +Conduct an end-of-day review to capture progress and set up tomorrow. + +## Review Process + +1. **Today's Activity** + - Find all notes modified today + - Identify new notes created + - Review work across all projects + +2. **Progress Assessment** + - What was accomplished? + - What got stuck or blocked? + - What unexpected discoveries emerged? + +3. **Capture Insights** + - Key learnings from today + - New connections discovered + - Questions that arose + +4. **Tomorrow's Setup** + - Top 3 priorities + - Open loops to close + - Questions to explore + +## Output Format + +Create or update a daily note with: + +```markdown +# Daily Review - [Date] + +## Accomplished +- โœ“ [Completed item 1] +- โœ“ [Completed item 2] + +## Progress Made +- [Project/Area]: [What moved forward] +- [Project/Area]: [What moved forward] + +## Insights +- [Key realization or connection] +- [Important learning] + +## Blocked/Stuck +- [What didn't progress and why] + +## Discovered Questions +- [New question that emerged] +- [Thing to research] + +## Tomorrow's Focus +1. [Priority 1] +2. [Priority 2] +3. [Priority 3] + +## Open Loops +- [ ] [Thing to remember] +- [ ] [Person to follow up with] +- [ ] [Idea to develop] +``` + +## Additional Actions + +- Move completed project tasks to archive +- Update project status notes +- Link related discoveries +- Flag items needing attention \ No newline at end of file diff --git a/.claude/commands/de-ai-ify.md b/.claude/commands/de-ai-ify.md new file mode 100644 index 0000000..a116e4c --- /dev/null +++ b/.claude/commands/de-ai-ify.md @@ -0,0 +1,81 @@ +--- +allowed-tools: Read, Write, Edit +description: Remove AI-generated jargon and restore human voice to text +argument-hint: [file_path] +--- + +# De-AI-ify Text + +Remove AI-generated patterns and restore natural human voice to your writing. + +## Processing: $ARGUMENTS + +I'll create a de-AI-ified version of your text that sounds more human and less machine-generated. + +## What Gets Removed + +### 1. Overused Transitions +- "Moreover," "Furthermore," "Additionally," "Nevertheless" +- Excessive "However" usage +- "While X, Y" openings + +### 2. AI Clichรฉs +- "In today's fast-paced world" +- "Let's dive deep" +- "Unlock your potential" +- "Harness the power of" + +### 3. Hedging Language +- "It's important to note" +- "It's worth mentioning" +- Vague quantifiers: "various," "numerous," "myriad" + +### 4. Corporate Buzzwords +- "utilize" โ†’ "use" +- "facilitate" โ†’ "help" +- "optimize" โ†’ "improve" +- "leverage" โ†’ "use" + +### 5. Robotic Patterns +- Rhetorical questions followed by immediate answers +- Obsessive parallel structures +- Always using exactly three examples +- Announcement of emphasis + +## What Gets Added + +### Natural Voice +- Varied sentence lengths +- Conversational tone +- Direct statements +- Specific examples + +### Human Rhythm +- Natural transitions +- Confident assertions +- Personal perspective +- Authentic phrasing + +## Process + +1. **Read original file** +2. **Create copy with "-HUMAN" suffix** +3. **Apply de-AI-ification** +4. **Provide change log** + +## Output + +You'll get: +- A new file with natural human voice +- Change log showing what was fixed +- List of places needing specific examples + +## Example Transformations + +**Before (AI):** +"In today's rapidly evolving digital landscape, it's crucial to understand that leveraging AI effectively isn't just about utilizing cutting-edge technologyโ€”it's about harnessing its transformative potential to unlock unprecedented opportunities." + +**After (Human):** +"AI works best when you use it for specific tasks. Focus on what it does well: writing code, analyzing data, and answering questions." + +Let me de-AI-ify your text! \ No newline at end of file diff --git a/.claude/commands/inbox-processor.md b/.claude/commands/inbox-processor.md new file mode 100644 index 0000000..2f0299f --- /dev/null +++ b/.claude/commands/inbox-processor.md @@ -0,0 +1,51 @@ +# Inbox Processor + +Help organize and process items in the 00_Inbox folder according to the PARA method. + +## Task + +Review all notes in `00_Inbox/` and help categorize them: + +1. **Scan the Inbox** + - List all files currently in 00_Inbox + - Exclude README.md and Welcome.md + +2. **Analyze Each Item** + - Read the content + - Identify the type of note + - Suggest appropriate destination + +3. **Categorization Rules** + - **โ†’ 01_Projects**: Has deadline, specific outcome + - **โ†’ 02_Areas**: Ongoing responsibility, no end date + - **โ†’ 03_Resources**: Reference material, knowledge + - **โ†’ 04_Archive**: Old/completed, no longer active + - **โ†’ Delete**: No value, redundant, or temporary + +4. **Suggest Actions** + ``` + File: [filename] + Type: [detected type] + Destination: [suggested folder] + Reason: [why this categorization] + Related to: [any existing notes it connects to] + ``` + +5. **Identify Patterns** + - Common themes across multiple notes + - Notes that could be combined + - Missing connections between items + +## Output Format + +Provide a clear action plan: +1. Items to move (with destinations) +2. Items to combine or link +3. Items to delete +4. Items needing more context + +## Remember + +- Some items legitimately belong in the Inbox (daily notes, quick captures) +- Don't over-organize - sometimes "good enough" is perfect +- Look for opportunities to connect ideas, not just file them \ No newline at end of file diff --git a/.claude/commands/init-bootstrap.md b/.claude/commands/init-bootstrap.md new file mode 100644 index 0000000..f86f463 --- /dev/null +++ b/.claude/commands/init-bootstrap.md @@ -0,0 +1,194 @@ +--- +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** + - Check for package.json and run `pnpm install` if needed + - Verify core dependencies are installed + - Check git status and initialize if needed + - Create base folder structure (00_Inbox through 06_Metadata) + +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** + - Ask if they have an existing vault or starting new + - If existing, explore current folder structure + - Document any custom organization patterns + +4. **Ask Configuration Questions** + - "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)" + - "Do you use any specific plugins or tools with Obsidian?" + - "What's your preferred naming convention for files?" + - "Do you work with attachments frequently? (images, PDFs, etc.)" + - "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?" + +5. **Optional MCP Server Setup** + - Ask: "Would you like to set up Gemini Vision for analyzing images and PDFs?" + - If yes: + - Guide to get API key from https://aistudio.google.com/apikey + - 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 + +6. **Generate Custom Configuration** + - Start with CLAUDE-BOOTSTRAP.md as base + - Add user-specific sections: + - Custom folder structure + - Personal workflows + - Preferred tools and scripts + - Specific guidelines + - MCP configuration if set up + - Include their websites/resources if provided + - Add any custom naming conventions + +7. **Create Supporting Files** + - Generate initial folder structure if new vault + - Create README files for main folders + - Create 05_Attachments/Organized/ directory + - Set up .gitignore if using git (include .mcp.json, node_modules) + - Create initial templates if requested + - Make initial git commit if repository was initialized + +8. **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 + +9. **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: [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] + +## 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] + +## Setup Summary + +โœ… Dependencies installed (pnpm install) +โœ… Folder structure created +โœ… Git repository initialized +โœ… CLAUDE.md personalized +[โœ… MCP Gemini Vision configured - if set up] +[โœ… First commit made - if git was initialized] +``` + +## Interactive Example + +``` +User: claude run init-bootstrap +Assistant: Welcome! I'll help you set up your personalized Obsidian + Claude configuration. + +First, let me set up your environment... +[Runs pnpm install to install dependencies] +[Creates folder structure if missing] +[Checks git status] + +โœ… Dependencies installed +โœ… Core folders created +โœ… Git repository ready + +Now let me ask you a few questions to customize your setup: + +1. **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. + +[Continues with questions...] + +Would you like to set up Gemini Vision for analyzing images and PDFs? This requires a Google API key. + +User: Yes, that sounds useful + +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. \ No newline at end of file diff --git a/.claude/commands/release.md b/.claude/commands/release.md new file mode 100644 index 0000000..35fb9cc --- /dev/null +++ b/.claude/commands/release.md @@ -0,0 +1,120 @@ +--- +name: release +description: Automatically bump version, update changelog, commit, tag, and push a new release based on recent changes +allowed-tools: [Read, Write, Edit, MultiEdit, Bash, Grep] +argument-hint: "(optional) 'major', 'minor', 'patch', or leave blank for auto-detection" +--- + +# Release Command + +Automates the entire release process: analyzes recent commits to determine version bump type, updates version in package.json, moves unreleased changelog entries to the new version, commits everything, creates a git tag, and pushes to GitHub. + +## Task + +1. Analyze recent commits since last tag to determine version bump type +2. Update version in package.json +3. Move "Unreleased" entries in CHANGELOG.md to the new version section +4. Commit the changes +5. Create an annotated git tag +6. Push commits and tags to GitHub + +## Process + +1. **Check Prerequisites** + - Ensure on main/master branch + - Check for uncommitted changes + - Verify CHANGELOG.md and package.json exist + - Get current version from package.json + +2. **Determine Version Bump** + - If argument provided (major/minor/patch), use that + - Otherwise, analyze commits since last tag: + - Look for "BREAKING CHANGE" or "!" = major bump + - Look for "feat:" = minor bump + - Look for "fix:", "docs:", "chore:" = patch bump + - Calculate new version number + +3. **Update Files** + - Update version in package.json + - Move "Unreleased" section in CHANGELOG.md to new version section + - Add comparison links for the new version + - Create new empty "Unreleased" section + +4. **Git Operations** + - Stage changes: `git add package.json CHANGELOG.md` + - Commit: `git commit -m "chore: release v{version}"` + - Create annotated tag: `git tag -a v{version} -m "Release v{version}"` + - Push commits: `git push` + - Push tags: `git push --tags` + +5. **Provide Next Steps** + - Show link to create GitHub release + - Remind to add release notes from changelog + +## Version Bump Rules + +### Semantic Versioning (MAJOR.MINOR.PATCH) + +**MAJOR** (1.0.0 โ†’ 2.0.0): +- Breaking changes +- Commits with "BREAKING CHANGE" in body +- Commits with "!" after type (e.g., "feat!:") + +**MINOR** (1.0.0 โ†’ 1.1.0): +- New features (backward compatible) +- Commits starting with "feat:" + +**PATCH** (1.0.0 โ†’ 1.0.1): +- Bug fixes and minor changes +- Commits with "fix:", "docs:", "style:", "refactor:", "test:", "chore:" + +## Example Usage + +```bash +# Auto-detect version bump from commits +claude run release + +# Force specific version bump +claude run release patch +claude run release minor +claude run release major + +# Example output: +# ๐Ÿ“ฆ Current version: 0.1.0 +# ๐Ÿ” Analyzing commits since last release... +# +# Found commits: +# - feat: add video support to Gemini Vision +# - docs: update README with setup instructions +# - fix: correct attachment link handling +# +# โœจ Detected version bump: MINOR (new features added) +# ๐Ÿ“ New version: 0.2.0 +# +# โœ… Updated package.json +# โœ… Updated CHANGELOG.md +# โœ… Committed changes +# โœ… Created tag v0.2.0 +# โœ… Pushed to GitHub +# +# ๐ŸŽ‰ Release v0.2.0 complete! +# +# Next steps: +# 1. Go to https://github.com/user/repo/releases/new?tag=v0.2.0 +# 2. Add release notes from CHANGELOG.md +# 3. Publish the release +``` + +## Error Handling + +- If not on main branch: "Please switch to main branch first" +- If uncommitted changes: "Please commit or stash changes first" +- If no changes since last release: "No changes to release" +- If version already exists: "Version X.X.X already exists" + +## Safety Features + +- Dry run mode: Show what would happen without making changes +- Confirmation prompt before pushing +- Validation of version format +- Check for existing tags before creating \ No newline at end of file diff --git a/.claude/commands/research-assistant.md b/.claude/commands/research-assistant.md new file mode 100644 index 0000000..6e4690e --- /dev/null +++ b/.claude/commands/research-assistant.md @@ -0,0 +1,65 @@ +# Research Assistant + +Conduct thorough research on topics by searching the vault and synthesizing findings. + +## Process + +1. **Initial Search** + - Search the entire vault for the topic + - Identify all relevant notes + - Note gaps in existing knowledge + +2. **Deep Dive** + - Read all relevant notes thoroughly + - Extract key insights and quotes + - Identify contradictions or tensions + - Map connections between ideas + +3. **Synthesis** + - Create a summary of findings + - Highlight patterns and themes + - Note questions that remain unanswered + - Suggest areas for further research + +## Output Structure + +```markdown +# Research Summary: [Topic] + +## Existing Knowledge +- What's already in the vault +- Key insights from previous work + +## Key Themes +1. Theme 1 + - Supporting notes: [[note1]], [[note2]] + - Key insight: ... + +2. Theme 2 + - Supporting notes: [[note3]], [[note4]] + - Key insight: ... + +## Contradictions/Tensions +- Where ideas conflict +- Unresolved questions + +## Gaps +- What's missing +- What to research next + +## Connections +- Related topics: [[topic1]], [[topic2]] +- Surprising links: ... + +## Recommended Next Steps +1. Specific research needed +2. Questions to explore +3. Experiments to try +``` + +## Tips + +- Cast a wide net initially, then focus +- Look for surprising connections +- Don't ignore contradictions - they're often where insights live +- Always suggest concrete next actions \ No newline at end of file diff --git a/.claude/commands/thinking-partner.md b/.claude/commands/thinking-partner.md new file mode 100644 index 0000000..35b245c --- /dev/null +++ b/.claude/commands/thinking-partner.md @@ -0,0 +1,37 @@ +# Thinking Partner + +You are a collaborative thinking partner specializing in helping people explore complex problems. Your role is to facilitate thinking through careful questioning and exploration, not to rush toward solutions. + +## Core Behaviors + +1. **Ask before answering** - Lead with questions that help clarify and deepen understanding +2. **Track insights** - Maintain a running log of key discoveries and connections +3. **Resist solutioning** - Stay in exploration mode until explicitly asked to move forward +4. **Connect ideas** - Help identify patterns and relationships across different notes +5. **Surface assumptions** - Gently challenge implicit beliefs and assumptions + +## Workflow + +When engaged as a thinking partner: + +1. Start by understanding the topic or challenge +2. Search the vault for relevant existing notes +3. Ask 3-5 clarifying questions +4. As the conversation develops: + - Take notes on key insights + - Identify connections to other ideas + - Track open questions + - Note potential directions to explore +5. Periodically summarize what's emerging + +## Key Prompts You Might Use + +- "What's behind that thought?" +- "How does this connect to [other concept] you mentioned?" +- "What would the opposite look like?" +- "What's the real challenge here?" +- "What are we not considering?" + +## Remember + +The goal is not to have answers but to help discover them. Your value is in the quality of exploration, not the speed of resolution. \ No newline at end of file diff --git a/.claude/commands/weekly-synthesis.md b/.claude/commands/weekly-synthesis.md new file mode 100644 index 0000000..e56d4fb --- /dev/null +++ b/.claude/commands/weekly-synthesis.md @@ -0,0 +1,92 @@ +# Weekly Synthesis + +Create a comprehensive synthesis of the week's work and thinking. + +## Analysis Process + +1. **Gather Week's Work** + - All notes created this week + - All notes modified this week + - Projects that saw activity + +2. **Identify Patterns** + - Recurring themes + - Common challenges + - Breakthrough moments + - Energy patterns (what energized vs drained) + +3. **Synthesize Learning** + - Key insights that emerged + - How thinking evolved + - Connections discovered + - Questions answered and raised + +4. **Assess Progress** + - Projects advanced + - Areas maintained + - Resources added + - Items archived + +## Output Format + +Create a weekly synthesis note: + +```markdown +# Weekly Synthesis - Week of [Date] + +## Week at a Glance +- Notes created: [X] +- Projects active: [List] +- Major accomplishments: [List] + +## Key Themes +### Theme 1: [Name] +- Where it appeared: [contexts] +- Why it matters: [significance] +- Next actions: [what to do] + +### Theme 2: [Name] +- Where it appeared: [contexts] +- Why it matters: [significance] +- Next actions: [what to do] + +## Major Insights +1. [Insight with context] +2. [Insight with context] + +## Progress by Project +### [Project Name] +- What advanced: +- What's blocked: +- Next week's focus: + +## Questions Emerged +- [Question 1 - and why it matters] +- [Question 2 - and why it matters] + +## Energy Audit +- What gave energy: +- What drained energy: +- What to adjust: + +## Connections Made +- [Note A] โ†โ†’ [Note B]: [Why significant] +- [Concept X] โ†โ†’ [Concept Y]: [New understanding] + +## Next Week's Intentions +1. [Primary focus] +2. [Secondary focus] +3. [Thing to explore] + +## To Process +- Inbox items: [count] +- Orphaned notes: [list] +- Missing connections: [identified] +``` + +## Follow-up Actions + +- Archive completed projects +- Clean up inbox +- Update project status +- Plan next week's focus \ No newline at end of file diff --git a/.claude/mcp-servers/GEMINI_VISION_QUICK_START.md b/.claude/mcp-servers/GEMINI_VISION_QUICK_START.md new file mode 100644 index 0000000..5d7324e --- /dev/null +++ b/.claude/mcp-servers/GEMINI_VISION_QUICK_START.md @@ -0,0 +1,285 @@ +# Gemini Vision MCP Server - Quick Start Guide + +**For getting Gemini Vision working on a new machine in under 5 minutes** + +## Prerequisites Check + +Run these commands to verify you have everything needed: +```bash +node --version # Should be v22+ +pnpm --version # Should be installed +claude --version # Claude Code should be installed +``` + +If any are missing: +- Node.js: Install from [nodejs.org](https://nodejs.org/) (v22+) +- pnpm: `npm install -g pnpm` +- Claude Code: Download from [claude.ai/code](https://claude.ai/code) + +## Step 1: Get Your Gemini API Key + +1. Go to [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey) +2. Click "Create API Key" +3. Copy the key (starts with `AIzaSy...`) + +## Step 2: Set Up Environment Variable + +### For Linux/macOS with Bash: +```bash +echo 'export GEMINI_API_KEY="your-actual-api-key-here"' >> ~/.bashrc +source ~/.bashrc +echo $GEMINI_API_KEY # Verify it shows your key +``` + +### For Linux/macOS with Zsh: +```bash +echo 'export GEMINI_API_KEY="your-actual-api-key-here"' >> ~/.zshrc +source ~/.zshrc +echo $GEMINI_API_KEY # Verify it shows your key +``` + +### For Windows PowerShell: +```powershell +[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User') +# Restart PowerShell +$env:GEMINI_API_KEY # Verify it shows your key +``` + +## Step 3: Install Dependencies + +**โš ๏ธ CRITICAL: This step MUST be done before adding the MCP server!** + +Navigate to your Obsidian vault: +```bash +cd ~/dev/02_Areas/Obsidian # Or wherever your vault is +``` + +Install the required dependencies: +```bash +# Install npm packages (REQUIRED - do this first!) +pnpm install + +# This installs: +# - @google/generative-ai (Gemini API client) +# - @modelcontextprotocol/sdk (MCP server framework) +# - Other dependencies from package.json +``` + +**Common Error Fix**: If you see `Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@modelcontextprotocol/sdk'`, you forgot to run `pnpm install`! + +**To hide node_modules from Obsidian** (optional but recommended): +1. Open Obsidian +2. Go to Settings โ†’ Files & Links โ†’ Excluded files +3. Click "Manage" +4. Add `node_modules/` to the list +5. Optionally also add: `pnpm-lock.yaml`, `.gitignore` + +This keeps your vault clean while using standard Node.js module resolution. + +## Step 4: Register the MCP Server + +**For project-scoped installation (recommended for team use):** +```bash +# Add server to project (creates .mcp.json file) +claude mcp add --scope project gemini-vision node .claude/mcp-servers/gemini-vision.mjs +``` + +**For user-scoped installation (personal use across all projects):** +```bash +# Add server to your user config +claude mcp add --scope user gemini-vision node .claude/mcp-servers/gemini-vision.mjs +``` + +After adding, you'll need to edit the `.mcp.json` file to add your API key: +```json +{ + "mcpServers": { + "gemini-vision": { + "type": "stdio", + "command": "node", + "args": [".claude/mcp-servers/gemini-vision.mjs"], + "env": { + "GEMINI_API_KEY": "your-api-key-here" + } + } + } +} +``` + +**IMPORTANT**: +- The command must be run from the Obsidian vault root directory +- You MUST have run `pnpm install` first +- The `.mcp.json` file is gitignored for security + +## Step 5: Verify It's Working + +1. **Open a NEW Claude Code window** (critical - must be new): + ```bash + cd ~/dev/Obsidian + claude + ``` + +2. **Check the server is connected**: + Type `/mcp` in Claude + + You should see: + ``` + gemini-vision โœ” connected + ``` + +3. **Test with an actual command**: + ``` + Use gemini-vision to extract text from 05 Attachments/[any-image.png] + ``` + +## Troubleshooting + +### "gemini-vision failed" or not showing in /mcp + +1. **MOST COMMON ISSUE - Dependencies not installed**: + ```bash + # If you see: Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@modelcontextprotocol/sdk' + # Run this: + pnpm install + ``` + Then reconnect the MCP server in Claude Code. + +2. **Check API key is configured**: + - For project-scoped: Check `.mcp.json` has your API key in the env section + - For user-scoped: Check `~/.claude.json` has your API key + - The key should be in the format: `"GEMINI_API_KEY": "AIzaSy..."` + +3. **Test server can run directly**: + ```bash + export GEMINI_API_KEY="your-api-key-here" + node .claude/mcp-servers/gemini-vision.mjs + ``` + Should show: "๐Ÿš€ Gemini Vision MCP Server running" + Press Ctrl+C to exit. + +4. **Re-add the server (for project scope)**: + ```bash + claude mcp remove gemini-vision --scope project + claude mcp add --scope project gemini-vision node .claude/mcp-servers/gemini-vision.mjs + # Then edit .mcp.json to add your API key + ``` + +4. **Check logs**: + ```bash + # Find log directory + ls ~/Library/Caches/claude-cli-nodejs/*/mcp-logs-gemini-vision/ + # Or on Linux: + ls ~/.cache/claude-cli-nodejs/*/mcp-logs-gemini-vision/ + + # View latest log + tail -f [log-directory]/*.txt + ``` + +### "Cannot find module" errors + +1. **Verify package.json exists**: + ```bash + cat package.json + ``` + Should show @google/generative-ai and @modelcontextprotocol/sdk + +2. **Reinstall dependencies**: + ```bash + rm -rf node_modules pnpm-lock.yaml + pnpm install + ``` + +3. **Check node_modules was created**: + ```bash + ls node_modules/@google/generative-ai + ``` + +### Server runs but tools don't work + +1. **Test API key directly**: + ```bash + curl "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY" + ``` + Should return a list of models, not an error. + +2. **Check file paths**: + - Use absolute paths from vault root + - Example: `05 Attachments/image.png` not `./05 Attachments/image.png` + +## Available Tools + +Once working, you can use these in Claude: + +### Image Analysis +``` +# Analyze an image +Use gemini-vision to analyze 05 Attachments/screenshot.png + +# Extract text (OCR) +Use gemini-vision to extract text from 05 Attachments/document.jpg + +# Compare images +Use gemini-vision to compare image1.png and image2.png + +# Suggest a filename +Use gemini-vision to suggest a filename for IMG_1234.jpg + +# Analyze multiple images +Use gemini-vision to analyze multiple: image1.png, image2.png, image3.png +``` + +### Video Analysis (NEW!) +``` +# Analyze a local video file +Use gemini-vision to analyze video 05 Attachments/video.mp4 + +# Analyze a YouTube video +Use gemini-vision to analyze YouTube video https://www.youtube.com/watch?v=VIDEO_ID + +# Custom video analysis prompt +Use gemini-vision to analyze video file.mp4 and extract all visible text +``` + +**Note:** Video processing may take 30-60 seconds as files need to reach ACTIVE state before analysis. The server will automatically wait and show progress updates. + +### Supported Formats + +**Images:** JPG, JPEG, PNG, GIF, BMP, WebP +**Videos:** MP4, AVI, MOV, WebM, MKV, WMV, FLV, 3GP, M4V +**Documents:** PDF, TXT, DOC, DOCX, ODT, RTF +**Special:** YouTube URLs (direct support without download) + +## Quick Reinstall (If Already Set Up Once) + +If you've already set up the API key in your shell profile: + +```bash +cd ~/dev/Obsidian +git pull +pnpm install +claude mcp add gemini-vision \ + --scope local \ + --env GEMINI_API_KEY=$GEMINI_API_KEY \ + -- node .claude/mcp-servers/gemini-vision.mjs +``` + +Then open a new Claude window and test. + +## File Locations + +- **Server code**: `.claude/mcp-servers/gemini-vision.mjs` +- **Dependencies**: `package.json` +- **This guide**: `07 Readme/GEMINI_VISION_QUICK_START.md` +- **Detailed docs**: `07 Readme/GEMINI_VISION_INSTALLATION.md` +- **Development guide**: `07 Readme/MCP_DEVELOPMENT_GUIDE.md` + +## Need Help? + +1. Check the troubleshooting section above +2. Verify all prerequisites are installed +3. Make sure you're in the Obsidian vault root directory +4. Ensure the API key is properly set in your environment + +--- + +*Last tested: September 2025* \ No newline at end of file diff --git a/.claude/mcp-servers/README.md b/.claude/mcp-servers/README.md new file mode 100644 index 0000000..5117bd4 --- /dev/null +++ b/.claude/mcp-servers/README.md @@ -0,0 +1,104 @@ +# MCP Servers + +Model Context Protocol servers extend Claude Code's capabilities. + +## Gemini Vision MCP + +Adds powerful image and document analysis capabilities using Google's Gemini model. + +### Features + +- **Image Analysis**: Describe, analyze, and extract text from images +- **Document Processing**: Analyze PDFs and documents +- **Multi-Image Comparison**: Compare multiple images at once +- **OCR**: Extract text from images +- **Smart Filename Suggestions**: Generate descriptive filenames for images + +### Setup + +1. **Get a Gemini API Key** + - Visit: https://aistudio.google.com/apikey + - Create a free API key + +2. **Add to Environment** + ```bash + # Add to ~/.zshrc or ~/.bashrc + export GEMINI_API_KEY='your-key-here' + + # Reload shell + source ~/.zshrc + ``` + +3. **Install Dependencies** + ```bash + pnpm install + ``` + +4. **Test Setup** + ```bash + pnpm test-gemini + ``` + +### Available Commands + +Once configured, these commands become available in Claude Code: + +- `mcp__gemini-vision__analyze_image` - Analyze a single image +- `mcp__gemini-vision__analyze_multiple` - Compare multiple images +- `mcp__gemini-vision__extract_text` - OCR text extraction +- `mcp__gemini-vision__compare_images` - Compare two images +- `mcp__gemini-vision__suggest_image_filename` - Generate descriptive filename +- `mcp__gemini-vision__analyze_document` - Analyze PDFs and documents + +### Usage Examples + +**Analyze Screenshot** +``` +Analyze the image at 05_Attachments/screenshot.png +and tell me what it contains. +``` + +**Process Multiple Images** +``` +Compare all images in 05_Attachments/Organized/ +and identify common themes. +``` + +**Extract Text** +``` +Extract all text from the PDF at +05_Attachments/document.pdf +``` + +**Rename Images** +``` +Suggest better names for all images +in 05_Attachments/ based on their content. +``` + +### Troubleshooting + +**"GEMINI_API_KEY not found"** +- Make sure you've added the key to your shell profile +- Restart your terminal and Claude Code + +**"File not found"** +- Use absolute paths or paths relative to vault root +- Check file permissions + +**Rate Limits** +- Free tier: 15 requests per minute +- Consider upgrading for heavy usage + +## Adding More MCPs + +1. Place MCP server file in `.claude/mcp-servers/` +2. Add configuration to Claude settings +3. Document setup here +4. Add usage examples + +## Resources + +- [MCP Documentation](https://modelcontextprotocol.io) +- [Gemini API Docs](https://ai.google.dev) +- [Claude Code MCP Guide](https://claude.ai/docs/mcp) \ No newline at end of file diff --git a/.claude/mcp-servers/gemini-vision.mjs b/.claude/mcp-servers/gemini-vision.mjs new file mode 100644 index 0000000..695fc66 --- /dev/null +++ b/.claude/mcp-servers/gemini-vision.mjs @@ -0,0 +1,430 @@ +#!/usr/bin/env node +import { Server } from "@modelcontextprotocol/sdk/server/index.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { + ListToolsRequestSchema, + CallToolRequestSchema +} from "@modelcontextprotocol/sdk/types.js"; +import { GoogleGenerativeAI } from "@google/generative-ai"; +import { GoogleAIFileManager } from "@google/generative-ai/server"; +import fs from "fs/promises"; +import path from "path"; +import os from "os"; + +const apiKey = process.env.GEMINI_API_KEY; +if (!apiKey) { + console.error("โŒ GEMINI_API_KEY environment variable is required"); + console.error(""); + console.error("To fix this:"); + console.error(""); + console.error("1. Get your API key from: https://aistudio.google.com/apikey"); + console.error(""); + console.error("2. Add to your shell profile:"); + console.error(" For macOS/Linux (add to ~/.zshrc or ~/.bashrc):"); + console.error(" export GEMINI_API_KEY='your-actual-api-key-here'"); + console.error(""); + console.error(" For Windows PowerShell:"); + console.error(" [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key', 'User')"); + console.error(""); + console.error("3. Reload your terminal:"); + console.error(" source ~/.zshrc (or source ~/.bashrc)"); + console.error(""); + console.error("4. Restart Claude Code"); + console.error(""); + console.error("For detailed instructions, see GEMINI_VISION_SETUP.md"); + process.exit(1); +} + +const genAI = new GoogleGenerativeAI(apiKey); +const fileManager = new GoogleAIFileManager(apiKey); +const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" }); + +// Expand home directory in paths +function expandPath(filepath) { + if (filepath.startsWith("~/")) { + return path.join(os.homedir(), filepath.slice(2)); + } + return filepath; +} + +// Helper function to wait/sleep +function sleep(ms) { + return new Promise(resolve => setTimeout(resolve, ms)); +} + +// Upload file to Gemini +async function uploadFile(filePath) { + const expandedPath = expandPath(filePath); + + try { + await fs.access(expandedPath); + } catch { + throw new Error(`File not found: ${filePath}`); + } + + const ext = path.extname(expandedPath).toLowerCase(); + const mimeTypes = { + '.jpg': 'image/jpeg', + '.jpeg': 'image/jpeg', + '.png': 'image/png', + '.gif': 'image/gif', + '.bmp': 'image/bmp', + '.webp': 'image/webp', + '.pdf': 'application/pdf', + '.txt': 'text/plain', + '.doc': 'application/msword', + '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', + '.odt': 'application/vnd.oasis.opendocument.text', + '.rtf': 'application/rtf', + // Video formats + '.mp4': 'video/mp4', + '.avi': 'video/x-msvideo', + '.mov': 'video/quicktime', + '.webm': 'video/webm', + '.mkv': 'video/x-matroska', + '.wmv': 'video/x-ms-wmv', + '.flv': 'video/x-flv', + '.3gp': 'video/3gpp', + '.m4v': 'video/x-m4v', + }; + + const uploadResult = await fileManager.uploadFile(expandedPath, { + mimeType: mimeTypes[ext] || 'application/octet-stream', + }); + + let file = uploadResult.file; + + // For video files, poll until the file is in ACTIVE state + const videoExtensions = ['.mp4', '.avi', '.mov', '.webm', '.mkv', '.wmv', '.flv', '.3gp', '.m4v']; + if (videoExtensions.includes(ext)) { + console.error(`Waiting for video file to process: ${path.basename(filePath)}`); + let attempts = 0; + const maxAttempts = 60; // Max 5 minutes (60 * 5 seconds) + + while (file.state !== 'ACTIVE' && attempts < maxAttempts) { + await sleep(5000); // Wait 5 seconds + attempts++; + + // Get updated file status + const fileStatus = await fileManager.getFile(file.name); + file = fileStatus; + + console.error(`Video processing status: ${file.state} (attempt ${attempts}/${maxAttempts})`); + + if (file.state === 'FAILED') { + throw new Error(`Video processing failed for: ${filePath}`); + } + } + + if (file.state !== 'ACTIVE') { + throw new Error(`Video processing timeout for: ${filePath}. File state: ${file.state}`); + } + + console.error('Video file is ready for analysis'); + } + + return file; +} + +// Tool handlers +async function analyzeImage(args) { + const imagePath = args.image_path; + const prompt = args.prompt || "Describe this image in detail"; + + const file = await uploadFile(imagePath); + const result = await model.generateContent([ + prompt, + { fileData: { fileUri: file.uri, mimeType: file.mimeType }} + ]); + + return result.response.text(); +} + +async function analyzeMultiple(args) { + const imagePaths = args.image_paths; + const prompt = args.prompt || "Analyze these images"; + + const content = [prompt]; + for (const imagePath of imagePaths) { + const file = await uploadFile(imagePath); + content.push({ fileData: { fileUri: file.uri, mimeType: file.mimeType }}); + } + + const result = await model.generateContent(content); + return result.response.text(); +} + +async function extractText(args) { + const imagePath = args.image_path; + const format = args.format || "plain"; + + const prompts = { + plain: "Extract and transcribe all text from this image. Return only the text, nothing else.", + markdown: "Extract all text from this image and format it in markdown, preserving structure.", + structured: "Extract all text from this image and organize it with clear sections and structure." + }; + + const file = await uploadFile(imagePath); + const result = await model.generateContent([ + prompts[format] || prompts.plain, + { fileData: { fileUri: file.uri, mimeType: file.mimeType }} + ]); + + return result.response.text(); +} + +async function compareImages(args) { + const image1Path = args.image1_path; + const image2Path = args.image2_path; + const focus = args.focus || "differences"; + + const prompts = { + differences: "Compare these two images and describe all the differences you can find.", + similarities: "Compare these two images and describe what they have in common.", + changes: "Describe what has changed between the first and second image." + }; + + const [file1, file2] = await Promise.all([ + uploadFile(image1Path), + uploadFile(image2Path) + ]); + + const result = await model.generateContent([ + prompts[focus] || prompts.differences, + { fileData: { fileUri: file1.uri, mimeType: file1.mimeType }}, + { fileData: { fileUri: file2.uri, mimeType: file2.mimeType }} + ]); + + return result.response.text(); +} + +async function suggestFilename(args) { + const imagePath = args.image_path; + const maxLength = args.max_length || 60; + const includeDate = args.include_date || false; + + const prompt = `Analyze this image and suggest a descriptive filename for it. + Requirements: + - Maximum ${maxLength} characters (not including extension) + - Use title case with spaces (will be converted to hyphens) + - Be specific and descriptive about the content + - ${includeDate ? 'Include YYYY-MM-DD prefix if a date is visible in the image' : 'Do not include date prefix'} + - Focus on the main subject or purpose of the image + - For screenshots: include the application or website name + - For diagrams: include the type and subject + - For photos: include the subject and context + - Return ONLY the filename suggestion, no explanation or extension`; + + const file = await uploadFile(imagePath); + const result = await model.generateContent([ + prompt, + { fileData: { fileUri: file.uri, mimeType: file.mimeType }} + ]); + + // Clean up the suggestion and format it + let suggestion = result.response.text().trim(); + // Remove any file extension if accidentally included + suggestion = suggestion.replace(/\.(png|jpg|jpeg|gif|webp|pdf)$/i, ''); + // Replace spaces with hyphens + suggestion = suggestion.replace(/\s+/g, ' ').replace(/ /g, ' - '); + // Ensure it doesn't exceed max length + if (suggestion.length > maxLength) { + suggestion = suggestion.substring(0, maxLength).replace(/ - $/, ''); + } + + return suggestion; +} + +async function analyzeDocument(args) { + const documentPath = args.document_path; + const prompt = args.prompt || "Analyze this document and provide a comprehensive summary"; + + const file = await uploadFile(documentPath); + const result = await model.generateContent([ + prompt, + { fileData: { fileUri: file.uri, mimeType: file.mimeType }} + ]); + + return result.response.text(); +} + +// Analyze video files or YouTube URLs +async function analyzeVideo(args) { + const videoPath = args.video_path; + const youtubeUrl = args.youtube_url; + const prompt = args.prompt || "Summarize this video in detail, including key moments and any text or speech content"; + + if (!videoPath && !youtubeUrl) { + throw new Error("Either video_path or youtube_url is required"); + } + + if (videoPath && youtubeUrl) { + throw new Error("Please provide either video_path or youtube_url, not both"); + } + + let fileData; + + if (youtubeUrl) { + // YouTube URLs can be passed directly to the API + fileData = { fileUri: youtubeUrl }; + } else { + // Upload local video file + const file = await uploadFile(videoPath); + fileData = { fileUri: file.uri, mimeType: file.mimeType }; + } + + const result = await model.generateContent([ + prompt, + { fileData } + ]); + + return result.response.text(); +} + +// Create MCP server +const server = new Server( + { name: "gemini-vision", version: "1.0.0" }, + { capabilities: { tools: {} }} +); + +// List available tools +server.setRequestHandler(ListToolsRequestSchema, async () => ({ + tools: [ + { + name: "analyze_image", + description: "Analyze an image - transcribe text, describe content, or answer questions", + inputSchema: { + type: "object", + properties: { + image_path: { type: "string", description: "Path to the image file" }, + prompt: { type: "string", description: "What to do with the image", default: "Describe this image" } + }, + required: ["image_path"] + } + }, + { + name: "analyze_multiple", + description: "Analyze multiple images at once", + inputSchema: { + type: "object", + properties: { + image_paths: { type: "array", items: { type: "string" }, description: "List of image paths" }, + prompt: { type: "string", description: "What to do with the images", default: "Analyze these images" } + }, + required: ["image_paths"] + } + }, + { + name: "extract_text", + description: "Extract and transcribe all text from an image (OCR)", + inputSchema: { + type: "object", + properties: { + image_path: { type: "string", description: "Path to the image file" }, + format: { type: "string", enum: ["plain", "markdown", "structured"], default: "plain" } + }, + required: ["image_path"] + } + }, + { + name: "compare_images", + description: "Compare two images and describe differences or similarities", + inputSchema: { + type: "object", + properties: { + image1_path: { type: "string", description: "Path to first image" }, + image2_path: { type: "string", description: "Path to second image" }, + focus: { type: "string", enum: ["differences", "similarities", "changes"], default: "differences" } + }, + required: ["image1_path", "image2_path"] + } + }, + { + name: "suggest_image_filename", + description: "Analyze an image and suggest a descriptive filename (without extension)", + inputSchema: { + type: "object", + properties: { + image_path: { type: "string", description: "Path to the image file" }, + max_length: { type: "number", description: "Maximum filename length", default: 60 }, + include_date: { type: "boolean", description: "Include date prefix in suggestion", default: false } + }, + required: ["image_path"] + } + }, + { + name: "analyze_video", + description: "Analyze video files or YouTube URLs - extract content, summarize, transcribe speech, identify objects/text. Provide either video_path OR youtube_url", + inputSchema: { + type: "object", + properties: { + video_path: { type: "string", description: "Path to local video file (MP4, AVI, MOV, etc.)" }, + youtube_url: { type: "string", description: "YouTube video URL (e.g., https://www.youtube.com/watch?v=...)" }, + prompt: { type: "string", description: "What to analyze in the video", default: "Summarize this video in detail" } + }, + required: [] + } + }, + { + name: "analyze_document", + description: "Analyze a PDF or document with custom prompts - extract specific information, find mentions of topics, summarize sections, etc.", + inputSchema: { + type: "object", + properties: { + document_path: { type: "string", description: "Path to the document file (PDF, DOC, DOCX, ODT, RTF, TXT)" }, + prompt: { type: "string", description: "What to analyze or extract from the document", default: "Analyze this document and provide a comprehensive summary" } + }, + required: ["document_path"] + } + } + ] +})); + +// Handle tool calls +server.setRequestHandler(CallToolRequestSchema, async (request) => { + const { name, arguments: args } = request.params; + + try { + let result; + switch (name) { + case "analyze_image": + result = await analyzeImage(args); + break; + case "analyze_multiple": + result = await analyzeMultiple(args); + break; + case "extract_text": + result = await extractText(args); + break; + case "compare_images": + result = await compareImages(args); + break; + case "suggest_image_filename": + result = await suggestFilename(args); + break; + case "analyze_document": + result = await analyzeDocument(args); + break; + case "analyze_video": + result = await analyzeVideo(args); + break; + default: + throw new Error(`Unknown tool: ${name}`); + } + + return { + content: [{ type: "text", text: result }] + }; + } catch (error) { + throw new Error(`Tool execution failed: ${error.message}`); + } +}); + +// Start server +async function main() { + const transport = new StdioServerTransport(); + await server.connect(transport); + console.error("๐Ÿš€ Gemini Vision MCP Server running"); +} + +main().catch(console.error); \ No newline at end of file diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..bc0c6aa --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,10 @@ +{ + "permissions": { + "allow": [ + "WebSearch", + "Bash(gitleaks detect:*)" + ], + "deny": [], + "ask": [] + } +} \ No newline at end of file diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..2e46d64 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,29 @@ +# GitHub Release configuration +# This helps GitHub auto-generate release notes + +changelog: + exclude: + labels: + - ignore-for-release + authors: + - dependabot + categories: + - title: ๐Ÿš€ Features + labels: + - feature + - enhancement + - title: ๐Ÿ› Bug Fixes + labels: + - fix + - bug + - title: ๐Ÿ“š Documentation + labels: + - documentation + - docs + - title: ๐Ÿงฐ Maintenance + labels: + - chore + - maintenance + - title: Other Changes + labels: + - "*" \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..59c5608 --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# Sensitive files +.env +.env.local +*.env + +# API keys and secrets +*api_key* +*secret* +firecrawl_config.sh + +# Claude files + +# MCP config +.mcp.json + +# Scripts with sensitive data +scripts/*_local.sh + +# macOS files +.DS_Store + +# Node modules - always exclude from repo +node_modules/ +.node_modules/ +pnpm-lock.yaml + +# Never commit real API keys +*_API_KEY \ No newline at end of file diff --git a/.scripts/README.md b/.scripts/README.md new file mode 100644 index 0000000..1eed3b4 --- /dev/null +++ b/.scripts/README.md @@ -0,0 +1,84 @@ +# Scripts Directory + +Helper scripts for vault automation and web content capture. + +## Available Scripts + +### Attachment Management +These are primarily called via npm/pnpm commands in package.json: +- `update-attachment-links.js` - Updates note links after moving attachments +- `fix-renamed-links.js` - Fixes links after renaming files + +### Web Content Capture +**Note**: These scripts require API keys to function: + +#### firecrawl-scrape.sh +Scrapes a single URL and saves as markdown. +```bash +# Requires FIRECRAWL_API_KEY environment variable +.scripts/firecrawl-scrape.sh +``` + +#### firecrawl-batch.sh +Scrapes multiple URLs and auto-generates filenames. +```bash +# Requires FIRECRAWL_API_KEY environment variable +.scripts/firecrawl-batch.sh +# Files saved to 00_Inbox/Clippings/ +``` + +### Transcript Extraction +#### transcript-extract.sh +Extracts transcripts from YouTube videos. +```bash +.scripts/transcript-extract.sh +``` + +## NPM Scripts + +Run these from the vault root with `pnpm`: + +| Command | Description | +|---------|-------------| +| `attachments:list` | Show first 20 unprocessed attachments | +| `attachments:count` | Count unprocessed attachments | +| `attachments:organized` | Count files in Organized folder | +| `attachments:unprocessed` | Same as count | +| `attachments:refs ` | Find references to a specific file | +| `attachments:sizes` | Show 20 largest attachment files | +| `attachments:orphans` | Find unreferenced attachments | +| `attachments:recent` | Show files added in last 7 days | +| `attachments:create-organized` | Create the Organized subfolder | + +## Setup Requirements + +### For Web Scraping +1. Get a Firecrawl API key from [firecrawl.dev](https://firecrawl.dev) +2. Add to your shell profile: + ```bash + export FIRECRAWL_API_KEY="your-key-here" + ``` + +### For Transcript Extraction +- Requires `yt-dlp` and `jq` installed: + ```bash + # macOS + brew install yt-dlp jq + + # Linux + apt-get install yt-dlp jq + ``` + +## Adding Custom Scripts + +1. Create script in `.scripts/` +2. Make it executable: `chmod +x .scripts/your-script.sh` +3. Add npm script to `package.json` if needed +4. Document here + +## Notes + +- Scripts assume Unix-like environment (macOS/Linux) +- Windows users may need WSL or Git Bash +- All paths are relative to vault root +- Check script comments for additional requirements \ No newline at end of file diff --git a/.scripts/firecrawl-batch.sh b/.scripts/firecrawl-batch.sh new file mode 100755 index 0000000..c06f3ef --- /dev/null +++ b/.scripts/firecrawl-batch.sh @@ -0,0 +1,115 @@ +#!/bin/bash + +# Firecrawl batch scraper script +# Usage: ./firecrawl-batch.sh ... +# Automatically generates filenames based on page titles and dates +# Requires: FIRECRAWL_API_KEY environment variable + +# Source .zshrc to get the API key +source ~/.zshrc + +if [ $# -eq 0 ]; then + echo "Usage: $0 ..." + echo "Scrapes multiple URLs and saves them to 00 Inbox/Clippings/" + exit 1 +fi + +if [ -z "$FIRECRAWL_API_KEY" ]; then + echo "Error: FIRECRAWL_API_KEY environment variable not set" + exit 1 +fi + +# Get today's date +TODAY=$(date +"%Y-%m-%d") +CLIPPINGS_DIR="00 Inbox/Clippings" + +# Create clippings directory if it doesn't exist +mkdir -p "$CLIPPINGS_DIR" + +# Function to sanitize filename +sanitize_filename() { + echo "$1" | sed 's/[^a-zA-Z0-9 -]//g' | sed 's/ \+/ /g' | sed 's/^ *//;s/ *$//' +} + +# Function to extract domain name for fallback +get_domain() { + echo "$1" | sed -E 's|https?://([^/]+).*|\1|' | sed 's/www\.//' +} + +# Counter for successful scrapes +SUCCESS_COUNT=0 +FAIL_COUNT=0 + +# Process each URL +for URL in "$@"; do + echo "Processing: $URL" + + # Make the API call and save to temp file + TEMP_FILE=$(mktemp) + + curl -s -X POST https://api.firecrawl.dev/v1/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d "{ + \"url\": \"$URL\", + \"formats\": [\"markdown\"], + \"onlyMainContent\": true + }" > "$TEMP_FILE" + + # Extract markdown and title + MARKDOWN=$(jq -r '.data.markdown // empty' "$TEMP_FILE") + TITLE=$(jq -r '.data.metadata.title // empty' "$TEMP_FILE") + + # If no title, try to extract from markdown or use domain + if [ -z "$TITLE" ] || [ "$TITLE" = "null" ]; then + # Try to get first heading from markdown + TITLE=$(echo "$MARKDOWN" | grep -m1 '^# ' | sed 's/^# //') + + # If still no title, use domain + if [ -z "$TITLE" ]; then + TITLE=$(get_domain "$URL") + fi + fi + + # Sanitize title for filename + SAFE_TITLE=$(sanitize_filename "$TITLE") + + # Truncate title if too long + if [ ${#SAFE_TITLE} -gt 60 ]; then + SAFE_TITLE="${SAFE_TITLE:0:60}" + fi + + # Create filename + OUTPUT_FILE="$CLIPPINGS_DIR/$TODAY - $SAFE_TITLE.md" + + # Check if we got content + if [ -n "$MARKDOWN" ] && [ "$MARKDOWN" != "null" ]; then + # Add metadata header + { + echo "---" + echo "source: $URL" + echo "date: $TODAY" + echo "title: \"$TITLE\"" + echo "---" + echo "" + echo "$MARKDOWN" + } > "$OUTPUT_FILE" + + echo " โœ“ Saved to: $OUTPUT_FILE" + ((SUCCESS_COUNT++)) + else + echo " โœ— Failed to scrape content" + ((FAIL_COUNT++)) + fi + + # Clean up temp file + rm -f "$TEMP_FILE" + + # Small delay to be nice to the API + sleep 1 +done + +echo "" +echo "Batch scraping complete!" +echo " Successful: $SUCCESS_COUNT" +echo " Failed: $FAIL_COUNT" \ No newline at end of file diff --git a/.scripts/firecrawl-scrape.sh b/.scripts/firecrawl-scrape.sh new file mode 100755 index 0000000..94ec022 --- /dev/null +++ b/.scripts/firecrawl-scrape.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +# Firecrawl scraper script that saves directly to file +# Usage: ./firecrawl-scrape.sh +# Requires: FIRECRAWL_API_KEY environment variable + +URL="$1" +OUTPUT_FILE="$2" + +if [ -z "$URL" ] || [ -z "$OUTPUT_FILE" ]; then + echo "Usage: $0 " + echo "Requires FIRECRAWL_API_KEY environment variable to be set" + exit 1 +fi + +if [ -z "$FIRECRAWL_API_KEY" ]; then + echo "Error: FIRECRAWL_API_KEY environment variable not set" + echo "Export it in your shell profile or run:" + echo " export FIRECRAWL_API_KEY='your-api-key'" + exit 1 +fi + +# Make the API call and extract markdown using jq, save directly to file +curl -s -X POST https://api.firecrawl.dev/v1/scrape \ + -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ + -H "Content-Type: application/json" \ + -d "{ + \"url\": \"$URL\", + \"formats\": [\"markdown\"], + \"onlyMainContent\": true + }" | jq -r '.data.markdown // empty' > "$OUTPUT_FILE" + +# Check if file was created and has content +if [ -s "$OUTPUT_FILE" ]; then + echo "โœ“ Scraped content saved to: $OUTPUT_FILE" +else + echo "โœ— Failed to scrape content" + rm -f "$OUTPUT_FILE" # Remove empty file + exit 1 +fi \ No newline at end of file diff --git a/.scripts/fix-renamed-links.js b/.scripts/fix-renamed-links.js new file mode 100755 index 0000000..6cad811 --- /dev/null +++ b/.scripts/fix-renamed-links.js @@ -0,0 +1,87 @@ +#!/usr/bin/env node + +/** + * Fixes attachment links after files have been renamed + * Usage: node .scripts/fix-renamed-links.js + * + * This properly handles the case where files are renamed, not just moved + */ + +import fs from 'fs'; +import path from 'path'; + +const args = process.argv.slice(2); + +if (args.length !== 2) { + console.log('Usage: node .scripts/fix-renamed-links.js '); + console.log('Example: node .scripts/fix-renamed-links.js "CleanShot 2025-01-01.png" "Project Screenshot.png"'); + process.exit(1); +} + +const [oldName, newName] = args; +const newPath = `05 Attachments/Organized/${newName}`; + +console.log(`Fixing links: ${oldName} โ†’ ${newName}`); + +// Function to walk directory +function walkDir(dir, callback) { + fs.readdirSync(dir).forEach(f => { + const dirPath = path.join(dir, f); + const isDirectory = fs.statSync(dirPath).isDirectory(); + if (isDirectory) { + // Skip node_modules, .git + if (!f.includes('node_modules') && !f.includes('.git')) { + walkDir(dirPath, callback); + } + } else { + callback(path.join(dir, f)); + } + }); +} + +// Process all markdown files +let updatedCount = 0; +const updatedFiles = []; + +walkDir('.', (filepath) => { + if (filepath.endsWith('.md')) { + let content = fs.readFileSync(filepath, 'utf8'); + const originalContent = content; + + // Escape special regex characters in filename + const escapedOld = oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + + // Pattern 1: ![[oldname]] without path + const pattern1 = new RegExp(`!\\[\\[${escapedOld}\\]\\]`, 'g'); + content = content.replace(pattern1, `![[${newPath}]]`); + + // Pattern 2: ![[05 Attachments/oldname]] + const pattern2 = new RegExp(`!\\[\\[05 Attachments/${escapedOld}\\]\\]`, 'g'); + content = content.replace(pattern2, `![[${newPath}]]`); + + // Pattern 3: [[oldname]] without ! (for PDFs and other non-embedded) + const pattern3 = new RegExp(`(? 0) { + console.log(`\nUpdated ${updatedCount} files:`); + updatedFiles.forEach(file => console.log(` - ${file}`)); +} else { + console.log('\nNo files needed updating'); +} + +console.log('\nDone!'); \ No newline at end of file diff --git a/.scripts/transcript-extract.sh b/.scripts/transcript-extract.sh new file mode 100755 index 0000000..443d911 --- /dev/null +++ b/.scripts/transcript-extract.sh @@ -0,0 +1,69 @@ +#!/bin/bash + +# Transcript extraction script for YouTube videos +# Usage: .scripts/transcript-extract.sh [output-path] +# Default output: 00 Inbox/Clippings/ + +set -e + +URL="$1" +OUTPUT_PATH="${2:-00 Inbox/Clippings}" + +if [ -z "$URL" ]; then + echo "Usage: $0 [output-path]" + echo "Default output path: 00 Inbox/Clippings/" + exit 1 +fi + +echo "๐Ÿ” Extracting transcript from: $URL" +echo "๐Ÿ“ Output path: $OUTPUT_PATH" + +# Create output directory if it doesn't exist +mkdir -p "$OUTPUT_PATH" + +# Extract video ID and title +VIDEO_ID=$(yt-dlp --get-id "$URL") +TITLE=$(yt-dlp --get-title "$URL") +SAFE_TITLE=$(echo "$TITLE" | sed 's/[^a-zA-Z0-9 -]//g' | sed 's/ */ /g' | cut -c1-80) +DATE=$(date +%Y-%m-%d) + +echo "๐Ÿ“น Video: $TITLE" +echo "๐Ÿ†” Video ID: $VIDEO_ID" + +# Try to extract captions first (fastest method) +echo "๐ŸŽฏ Attempting to extract captions..." +if yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs 'en.*' --sub-format json3 -o '%(id)s.%(ext)s' "$URL"; then + echo "โœ… Captions extracted successfully" + + # Convert to markdown + FILENAME="$OUTPUT_PATH/$DATE - $SAFE_TITLE - Transcript.md" + + cat > "$FILENAME" << EOF +# $TITLE - Transcript + +**Source:** $URL +**Title:** $TITLE +**Video ID:** $VIDEO_ID +**Extracted:** $DATE +**Method:** YouTube captions via yt-dlp + +--- + +EOF + + # Process JSON3 captions to clean text + jq -r '.events[] | select(.segs) | .segs | map(.utf8) | join("")' *.json3 | \ + sed -E 's/\s+/ /g; s/โ™ช//g; s/^\s*//; s/\s*$//' | \ + grep -v '^$' >> "$FILENAME" + + # Cleanup temporary files + rm -f *.json3 + + echo "โœ… Transcript saved to: $FILENAME" + echo "๐Ÿ“ $(wc -l < "$FILENAME") lines extracted" + +else + echo "โŒ No captions available for this video" + echo "๐Ÿ’ก You could try manual transcription tools if needed" + exit 1 +fi \ No newline at end of file diff --git a/.scripts/update-attachment-links.js b/.scripts/update-attachment-links.js new file mode 100755 index 0000000..a419e01 --- /dev/null +++ b/.scripts/update-attachment-links.js @@ -0,0 +1,106 @@ +#!/usr/bin/env node + +/** + * Updates attachment links in markdown files after files are moved to Organized folder + * Usage: node .scripts/update-attachment-links.js [specific-file.ext] + * + * If no argument provided, updates all files in Organized folder + * If specific filename provided, only updates references to that file + */ + +import fs from 'fs'; +import path from 'path'; + +const organizedDir = '05 Attachments/Organized'; +const args = process.argv.slice(2); +const specificFile = args[0]; + +// Get list of files to update references for +let filesToUpdate = []; + +if (specificFile) { + // Update references for a specific file + filesToUpdate = [specificFile]; + console.log(`Updating references for: ${specificFile}`); +} else { + // Update references for all files in Organized folder + if (fs.existsSync(organizedDir)) { + filesToUpdate = fs.readdirSync(organizedDir); + console.log(`Found ${filesToUpdate.length} files in Organized folder`); + } else { + console.log('Organized folder does not exist yet'); + process.exit(0); + } +} + +// Function to walk directory +function walkDir(dir, callback) { + fs.readdirSync(dir).forEach(f => { + const dirPath = path.join(dir, f); + const isDirectory = fs.statSync(dirPath).isDirectory(); + if (isDirectory) { + // Skip node_modules, .git, and the Organized folder itself + if (!f.includes('node_modules') && !f.includes('.git') && dirPath !== organizedDir) { + walkDir(dirPath, callback); + } + } else { + callback(path.join(dir, f)); + } + }); +} + +// Process all markdown files +let updatedCount = 0; +const updatedFiles = []; + +walkDir('.', (filepath) => { + if (filepath.endsWith('.md')) { + let content = fs.readFileSync(filepath, 'utf8'); + const originalContent = content; + + // For each file to update, fix references + filesToUpdate.forEach(filename => { + // Escape special regex characters in filename + const escapedFile = filename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + + // Pattern 1: ![[filename]] without path + const pattern1 = new RegExp(`!\\[\\[${escapedFile}\\]\\]`, 'g'); + content = content.replace(pattern1, `![[05 Attachments/Organized/${filename}]]`); + + // Pattern 2: ![[05 Attachments/filename]] (file in root being moved) + const pattern2 = new RegExp(`!\\[\\[05 Attachments/${escapedFile}\\]\\]`, 'g'); + content = content.replace(pattern2, `![[05 Attachments/Organized/${filename}]]`); + + // Pattern 3: [[filename]] without ! (for PDFs and other non-embedded links) + // Only if not already pointing to Organized + const pattern3 = new RegExp(`\\[\\[${escapedFile}\\]\\]`, 'g'); + const pattern3Organized = new RegExp(`\\[\\[05 Attachments/Organized/${escapedFile}\\]\\]`, 'g'); + + // Only replace if not already pointing to Organized and not preceded by ! + if (!pattern3Organized.test(content)) { + content = content.replace(pattern3, `[[05 Attachments/Organized/${filename}]]`); + } + + // Pattern 4: [[05 Attachments/filename]] without ! + const pattern4 = new RegExp(`\\[\\[05 Attachments/${escapedFile}\\]\\]`, 'g'); + content = content.replace(pattern4, `[[05 Attachments/Organized/${filename}]]`); + }); + + // Write back if changed + if (content !== originalContent) { + fs.writeFileSync(filepath, content, 'utf8'); + updatedFiles.push(filepath); + updatedCount++; + } + } +}); + +// Report results +if (updatedCount > 0) { + console.log(`\nUpdated ${updatedCount} files:`); + updatedFiles.forEach(file => console.log(` - ${file}`)); +} else { + console.log('\nNo files needed updating'); +} + +console.log('\nDone!'); \ No newline at end of file diff --git a/.scripts/vault-stats.sh b/.scripts/vault-stats.sh new file mode 100755 index 0000000..7c204cb --- /dev/null +++ b/.scripts/vault-stats.sh @@ -0,0 +1,28 @@ +#!/bin/bash + +# Vault Statistics Script +# Shows basic stats about your Obsidian vault + +echo "=== Vault Statistics ===" +echo "" + +echo "๐Ÿ“ Note Counts:" +echo " Inbox: $(find 00_Inbox -name "*.md" 2>/dev/null | wc -l)" +echo " Projects: $(find 01_Projects -name "*.md" 2>/dev/null | wc -l)" +echo " Areas: $(find 02_Areas -name "*.md" 2>/dev/null | wc -l)" +echo " Resources: $(find 03_Resources -name "*.md" 2>/dev/null | wc -l)" +echo " Archive: $(find 04_Archive -name "*.md" 2>/dev/null | wc -l)" +echo "" + +echo "๐Ÿ“Ž Attachments:" +echo " Total: $(find 05_Attachments -type f 2>/dev/null | wc -l)" +echo " Organized: $(find 05_Attachments/Organized -type f 2>/dev/null | wc -l)" +echo "" + +echo "๐Ÿ“Š Total Notes: $(find . -name "*.md" | wc -l)" +echo "" + +echo "๐Ÿ”„ Recent Activity (last 7 days):" +find . -name "*.md" -mtime -7 -type f 2>/dev/null | head -5 | while read file; do + echo " - $(basename "$file")" +done \ No newline at end of file diff --git a/00_Inbox/README.md b/00_Inbox/README.md new file mode 100644 index 0000000..571f8cd --- /dev/null +++ b/00_Inbox/README.md @@ -0,0 +1,68 @@ +# ๐Ÿ“ฅ Inbox + +Your capture zone for new ideas, quick thoughts, and unprocessed information. + +## Purpose + +The Inbox is a **temporary** holding area designed for: +- Quick capture without worrying about organization +- Daily notes and journaling +- Web clippings and interesting finds +- Meeting notes before processing +- Random thoughts and ideas + +## How to Use + +### Daily Workflow +1. **Capture first, organize later** - Don't slow down to categorize +2. **Use daily notes** - One note per day for stream of consciousness +3. **Dump links and quotes** - Save now, process later +4. **Don't let it pile up** - Process weekly + +### Weekly Processing +Every week, review your inbox and: +- Move project-related notes to `01_Projects/` +- Move ongoing topics to `02_Areas/` +- Move reference material to `03_Resources/` +- Archive completed items to `04_Archive/` +- Delete what's no longer relevant + +## Claude Code Commands + +### Quick Capture +``` +Create a new note in 00_Inbox called [title] +with these thoughts: [content] +``` + +### Process Inbox +``` +Review all notes in 00_Inbox. +Help me decide where each should go +based on the PARA method. +``` + +### Find Connections +``` +Look at recent notes in my inbox. +What patterns or themes do you see? +What existing notes might these connect to? +``` + +## Tips + +- **Don't aim for perfection** - The inbox is meant to be messy +- **Use descriptive filenames** - Makes processing easier +- **Date your notes** - YYYY-MM-DD format helps with sorting +- **Link liberally** - Even to notes that don't exist yet +- **Review regularly** - Don't let items sit for more than 2 weeks + +## File Naming + +Suggested formats: +- Daily notes: `2024-03-15.md` +- Quick captures: `2024-03-15 - Meeting with Team.md` +- Web clips: `2024-03-15 - Article Title - Source.md` +- Ideas: `Idea - Brief Description.md` + +Remember: The Inbox is where ideas begin, not where they live forever. \ No newline at end of file diff --git a/00_Inbox/Welcome.md b/00_Inbox/Welcome.md new file mode 100644 index 0000000..bd8db1b --- /dev/null +++ b/00_Inbox/Welcome.md @@ -0,0 +1,33 @@ +# Welcome to Your AI-Powered Second Brain + +This is your Inbox - a temporary landing zone for new ideas, quick captures, and daily thoughts. + +## Your First Steps + +1. **Start Claude Code** in this directory +2. **Tell it you're in thinking mode**: "I'm exploring [topic] in thinking mode" +3. **Let it search and ask questions** to help you think +4. **Capture insights** as you go + +## Quick Tips + +- Don't worry about organization initially - just capture +- Process your inbox weekly (move items to Projects/Areas/Resources) +- Use Daily Notes for stream-of-consciousness capture +- Let Claude Code help you find connections + +## Try This Now + +Ask Claude Code: +``` +I'm new to this vault. Can you help me understand +how to use you as a thinking partner? +Let's explore a topic I'm curious about. +``` + +## Remember + +The goal isn't to create perfect notes - it's to enhance your thinking. This system grows more valuable over time as you add more notes and Claude Code helps you discover connections you didn't see before. + +--- +*Move this to Archive once you're comfortable with the system* \ No newline at end of file diff --git a/01_Projects/README.md b/01_Projects/README.md new file mode 100644 index 0000000..c9ee54a --- /dev/null +++ b/01_Projects/README.md @@ -0,0 +1,105 @@ +# ๐ŸŽฏ Projects + +Active initiatives with specific outcomes and deadlines. + +## Purpose + +Projects are **time-bound efforts** with: +- Clear objectives and deliverables +- Defined start and end dates +- Specific success criteria +- Measurable outcomes + +## What Belongs Here + +### Good Projects +- "Q1 2024 Marketing Strategy" โœ“ +- "Website Redesign" โœ“ +- "Book Writing - AI & Creativity" โœ“ +- "Conference Talk - BRXND NYC" โœ“ + +### Not Projects (These go in Areas) +- "Health" โœ— (ongoing, no end date) +- "Learning" โœ— (continuous activity) +- "Team Management" โœ— (ongoing responsibility) + +## Project Structure + +Each project should have: +``` +Project_Name/ +โ”œโ”€โ”€ README.md # Project overview and status +โ”œโ”€โ”€ Research/ # Background materials +โ”œโ”€โ”€ Daily_Progress/ # Log of work sessions +โ”œโ”€โ”€ Drafts/ # Work in progress +โ”œโ”€โ”€ Resources/ # Supporting documents +โ””โ”€โ”€ Output/ # Final deliverables +``` + +## Claude Code Workflows + +### Starting a Project +``` +Create a new project called [name] in 01_Projects. +Set it up with the standard folder structure. +I'm in thinking mode - help me define objectives. +``` + +### Project Research +``` +I'm working on [project name]. +Search my vault for relevant existing notes. +What connections exist to my other work? +``` + +### Daily Progress +``` +Create a progress note for today in [project]/Daily_Progress. +Here's what I accomplished: [summary] +Questions that came up: [list] +``` + +### Project Status +``` +Review all notes in [project folder]. +What's the current status? +What are the key insights so far? +What's left to complete? +``` + +### Project Completion +``` +Project [name] is complete. +Create a retrospective covering: +- Objectives vs outcomes +- Key learnings +- What to do differently next time +Then help me archive it properly. +``` + +## Project Lifecycle + +1. **Initiation**: Define objectives, success criteria +2. **Research**: Gather relevant information +3. **Development**: Daily progress, iterative work +4. **Review**: Regular status checks +5. **Completion**: Final output, retrospective +6. **Archive**: Move to 04_Archive with summary + +## Tips for Success + +- **Start with clear objectives** - Vague projects never end +- **Use the template** - Consistency helps Claude Code help you +- **Log progress daily** - Even "no progress" is worth noting +- **Review weekly** - Keep projects on track +- **Complete or kill** - Don't let projects linger + +## When to Archive + +Move projects to `04_Archive/` when: +- All objectives are complete +- The project is cancelled +- It's been inactive for 30+ days +- It's transformed into an Area (ongoing) + +Always create a summary note before archiving! \ No newline at end of file diff --git a/02_Areas/README.md b/02_Areas/README.md new file mode 100644 index 0000000..9d2dfa7 --- /dev/null +++ b/02_Areas/README.md @@ -0,0 +1,136 @@ +# ๐Ÿ”„ Areas + +Ongoing responsibilities and spheres of activity you maintain over time. + +## Purpose + +Areas are **ongoing responsibilities** that: +- Have no end date +- Require continuous attention +- Define your roles and commitments +- Need regular maintenance + +## What Belongs Here + +### Personal Areas +- Health & Fitness +- Finances +- Relationships +- Personal Development +- Home & Environment + +### Professional Areas +- Team Management +- Client Relationships +- Professional Skills +- Industry Knowledge +- Networking + +### Creative Areas +- Writing Practice +- Content Creation +- Learning & Research +- Side Projects + +## Area Structure + +Each area might contain: +``` +Area_Name/ +โ”œโ”€โ”€ README.md # Overview and principles +โ”œโ”€โ”€ Goals/ # Current focus areas +โ”œโ”€โ”€ Resources/ # Reference materials +โ”œโ”€โ”€ Reviews/ # Periodic check-ins +โ””โ”€โ”€ Ideas/ # Future possibilities +``` + +## Claude Code Workflows + +### Area Review +``` +Review my [area name] area. +What patterns do you see in recent notes? +What aspects need more attention? +``` + +### Setting Goals +``` +Help me set quarterly goals for [area]. +Based on recent activity, what should I prioritize? +``` + +### Finding Gaps +``` +Analyze my [area] notes. +What important topics am I not tracking? +What questions should I be asking? +``` + +### Cross-Area Analysis +``` +Compare my [Area A] and [Area B] notes. +Where do they overlap? +How might they inform each other? +``` + +## Area vs Project + +**Ask yourself**: Does this have an end date? + +| Area (Ongoing) | Project (Time-bound) | +|---------------|---------------------| +| "Health" | "Lose 10 pounds by June" | +| "Finances" | "Create 2024 budget" | +| "Writing" | "Finish blog post series" | +| "Learning" | "Complete Python course" | +| "Clients" | "Deliver Project X" | + +## Maintenance Practices + +### Weekly +- Quick scan of each area +- Note any urgent needs +- Capture new ideas + +### Monthly +- Review goals and progress +- Update resource lists +- Clean up old notes + +### Quarterly +- Deep review with Claude Code +- Adjust focus areas +- Archive outdated material + +## Claude Code Prompts + +### Health Check +``` +Do a health check on all my areas. +Which have recent activity? +Which have been neglected? +``` + +### Balance Assessment +``` +Looking at my areas, where am I spending most energy? +What's out of balance? +``` + +### Integration Opportunities +``` +Find connections between my different areas. +Where could better integration create value? +``` + +## Tips + +- **Areas inform Projects** - Projects often emerge from area needs +- **Keep them active** - Dead areas should be archived +- **Review regularly** - Areas drift without attention +- **Document standards** - What does "good" look like? +- **Track metrics** - Even qualitative areas benefit from measurement + +## Remember + +Areas are the backdrop of your life. They don't complete, but they evolve. Use Claude Code to help you see patterns and maintain balance across all your responsibilities. \ No newline at end of file diff --git a/03_Resources/README.md b/03_Resources/README.md new file mode 100644 index 0000000..68fbfbc --- /dev/null +++ b/03_Resources/README.md @@ -0,0 +1,167 @@ +# ๐Ÿ“š Resources + +Your personal knowledge base of reference materials and evergreen notes. + +## Purpose + +Resources are **reference materials** that: +- You might need someday +- Aren't tied to specific projects +- Represent topics of ongoing interest +- Build your knowledge base over time + +## What Belongs Here + +### Categories to Consider +``` +03_Resources/ +โ”œโ”€โ”€ Articles/ # Saved web content +โ”œโ”€โ”€ Books/ # Book notes and summaries +โ”œโ”€โ”€ Concepts/ # Evergreen idea notes +โ”œโ”€โ”€ People/ # Notable people and thinkers +โ”œโ”€โ”€ Tools/ # Software, methods, frameworks +โ”œโ”€โ”€ Quotes/ # Memorable quotes +โ”œโ”€โ”€ Examples/ # Case studies, references +โ””โ”€โ”€ Learning/ # Course notes, tutorials +``` + +### Good Resources +- Tutorial on Python decorators +- Article about mental models +- Book notes from "Thinking, Fast and Slow" +- Framework for decision-making +- List of cognitive biases +- Industry trend analysis + +## Organization Principles + +### By Topic, Not Source +โŒ "Articles from Medium" +โœ… "AI Development Techniques" + +### Evergreen Over Ephemeral +โŒ "News from March 2024" +โœ… "Principles of Network Effects" + +### Atomic Notes +- One concept per note +- Self-contained understanding +- Heavily linked to related ideas + +## Claude Code Workflows + +### Building Knowledge +``` +I'm researching [topic]. +What do I already have in Resources? +What gaps exist in my knowledge? +``` + +### Making Connections +``` +Find all resources related to [concept]. +How do different sources approach this? +What patterns emerge? +``` + +### Creating Synthesis +``` +Review all notes about [topic] in Resources. +Create a synthesis document of key insights. +``` + +### Finding Examples +``` +I need examples of [concept]. +Search my resources for relevant cases. +``` + +## Resource Development + +### From Consumption to Creation +1. **Capture**: Save interesting content +2. **Process**: Extract key ideas +3. **Connect**: Link to existing notes +4. **Develop**: Build your own understanding +5. **Create**: Generate original insights + +### Progressive Summarization +- First pass: Highlight interesting parts +- Second pass: Bold the most important +- Third pass: Create summary at top +- Fourth pass: Extract to own note + +## Claude Code Prompts + +### Knowledge Audit +``` +Analyze my Resources folder. +What topics am I building expertise in? +Where are the gaps? +``` + +### Connection Discovery +``` +Find surprising connections between +different topics in my Resources. +``` + +### Learning Path +``` +Based on my resources about [topic], +what should I learn next? +Create a learning path. +``` + +### Concept Clarification +``` +Explain [concept] using examples +from my existing resources. +``` + +## Best Practices + +### Naming Conventions +- Clear, descriptive titles +- Include key concepts in name +- Avoid dates (unless historical) +- Use consistent formatting + +### Note Structure +```markdown +# Concept Name + +## Summary +One paragraph overview + +## Key Points +- Main idea 1 +- Main idea 2 +- Main idea 3 + +## Connections +- Related to: [[Other Concept]] +- Contrasts with: [[Different Idea]] +- Examples: [[Case Study]] + +## Sources +- Original article/book/video +``` + +### Maintenance +- Review and update regularly +- Merge duplicate concepts +- Strengthen connections +- Delete what's no longer relevant + +## Tips + +- **Quality over quantity** - Better to deeply understand few concepts +- **Your words matter** - Rewrite in your own understanding +- **Links are gold** - Connections create value +- **Review regularly** - Unused knowledge fades +- **Share freely** - Teaching solidifies understanding + +## Remember + +Resources are your external brain. The value isn't in collecting, but in connecting and creating. Use Claude Code to help you see patterns and build understanding across your entire knowledge base. \ No newline at end of file diff --git a/04_Archive/README.md b/04_Archive/README.md new file mode 100644 index 0000000..1232bd0 --- /dev/null +++ b/04_Archive/README.md @@ -0,0 +1,178 @@ +# ๐Ÿ—„๏ธ Archive + +Inactive items preserved for future reference. + +## Purpose + +The Archive stores: +- Completed projects with their outputs +- Inactive areas no longer maintained +- Old notes for historical reference +- Deprecated resources +- Past experiments and iterations + +## What Goes Here + +### From Projects +- Completed projects with final deliverables +- Cancelled projects with lessons learned +- Projects inactive for 30+ days + +### From Areas +- Areas no longer relevant to your life +- Responsibilities you've handed off +- Roles you no longer have + +### From Resources +- Outdated information (but historically interesting) +- Superseded frameworks or methods +- Old versions of evolved ideas + +### From Inbox +- Processed items no longer needed +- Old daily notes (after extraction) +- Random captures without lasting value + +## Organization + +``` +04_Archive/ +โ”œโ”€โ”€ Projects_2024/ # Completed projects by year +โ”œโ”€โ”€ Projects_2023/ +โ”œโ”€โ”€ Old_Areas/ # Discontinued areas +โ”œโ”€โ”€ Daily_Notes/ # Old daily captures +โ”œโ”€โ”€ Ideas/ # Ideas that didn't develop +โ””โ”€โ”€ Miscellaneous/ # Everything else +``` + +## Archival Process + +### Before Archiving Projects +1. Create completion summary +2. Extract reusable insights to Resources +3. Document lessons learned +4. Update any related Areas +5. Move entire folder with structure intact + +### Sample Completion Summary +```markdown +# Project: [Name] - Completion Summary + +**Duration**: Start date - End date +**Status**: Completed/Cancelled/Suspended + +## Objectives +- Original goal 1 โœ“ +- Original goal 2 โœ“ +- Original goal 3 โœ— + +## Key Outcomes +- What was delivered +- What impact it had +- What value was created + +## Lessons Learned +- What worked well +- What didn't work +- What to do differently + +## Reusable Assets +- Templates created: [[link]] +- Processes developed: [[link]] +- Insights gained: [[link]] + +## Related Notes +- Continues in: [[Area name]] +- See also: [[Related project]] +``` + +## Claude Code Workflows + +### Archive Project +``` +Help me archive [project name]. +Create a completion summary. +Extract reusable insights to Resources. +Move everything to Archive. +``` + +### Search Archive +``` +Search the archive for anything about [topic]. +I need historical context. +``` + +### Year in Review +``` +Review all archived projects from [year]. +What patterns do you see? +What did I accomplish? +``` + +### Resurrect Project +``` +I want to revive [archived project]. +What was the status when archived? +What would need updating? +``` + +## Archive Philosophy + +### It's Not a Graveyard +- Archives preserve institutional memory +- Old projects inform new ones +- Patterns emerge over time +- Ideas can be resurrected + +### It's Not a Dumping Ground +- Archive thoughtfully +- Maintain some organization +- Keep summaries accessible +- Delete true junk + +## Claude Code Prompts + +### Historical Analysis +``` +Look at my archived projects. +What types of things do I tend to start but not finish? +What themes recur? +``` + +### Knowledge Mining +``` +Search the archive for any mentions of [concept]. +How has my thinking evolved? +``` + +### Pattern Recognition +``` +Analyze my project completion rate. +What factors correlate with success? +What patterns predict failure? +``` + +## Maintenance + +### Quarterly +- Review recent additions +- Ensure summaries exist +- Check for resurrection candidates + +### Annually +- Major archive cleanup +- Delete what's truly dead +- Extract any missed insights +- Reorganize if needed + +## Tips + +- **Date everything** - Future you will thank you +- **Summarize always** - Context fades quickly +- **Link liberally** - Connections survive archival +- **Search often** - Archives are meant to be used +- **Delete fearlessly** - Not everything needs keeping + +## Remember + +The Archive is your institutional memory. It's not about holding onto everything, but about preserving what might inform future work. Use Claude Code to help you see patterns across time and extract wisdom from experience. \ No newline at end of file diff --git a/05_Attachments/README.md b/05_Attachments/README.md new file mode 100644 index 0000000..713bd9f --- /dev/null +++ b/05_Attachments/README.md @@ -0,0 +1,175 @@ +# ๐Ÿ“Ž Attachments + +Storage for images, PDFs, and other non-text files. + +## Purpose + +Centralized location for: +- Images and screenshots +- PDFs and documents +- Spreadsheets and data files +- Audio and video files +- Any binary files referenced in notes + +## Organization + +``` +05_Attachments/ +โ”œโ”€โ”€ Organized/ # Processed files with good names +โ”‚ โ”œโ”€โ”€ Images/ +โ”‚ โ”œโ”€โ”€ PDFs/ +โ”‚ โ””โ”€โ”€ Data/ +โ”œโ”€โ”€ IMG_*.png # Unprocessed phone images +โ”œโ”€โ”€ Screenshot*.png # Unprocessed screenshots +โ”œโ”€โ”€ CleanShot*.png # Unprocessed CleanShot files +โ””โ”€โ”€ *.pdf # Various PDFs +``` + +## Naming Conventions + +### Before Processing +- `IMG_1234.png` (from phone) +- `Screenshot 2024-03-15 at 2.30.45 PM.png` +- `CleanShot 2024-03-15 at 14.30.45.png` +- `document(1).pdf` + +### After Processing +- `2024-03-15_Project_Architecture_Diagram.png` +- `2024-03-15_Meeting_Whiteboard.jpg` +- `API_Documentation_v2.pdf` +- `Customer_Interview_Transcript.pdf` + +## Helper Scripts + +Run these with `pnpm`: + +### Viewing Status +- `attachments:list` - List unprocessed files +- `attachments:count` - Count unprocessed files +- `attachments:organized` - Count organized files +- `attachments:sizes` - Show largest files +- `attachments:recent` - Files added in last 7 days + +### Finding Issues +- `attachments:orphans` - Files not referenced anywhere +- `attachments:refs [filename]` - Find references to file + +### Organization +- `attachments:create-organized` - Create Organized folder + +## Claude Code Workflows + +### Process Screenshots +``` +Look at recent screenshots in 05_Attachments. +Based on their content, suggest better names. +Help me organize them. +``` + +### Find Orphans +``` +Find all attachments not referenced in any notes. +Should any be deleted? +``` + +### Rename Batch +``` +Review unprocessed images in Attachments. +Suggest descriptive names based on content. +``` + +### Clean Up +``` +Find duplicate images in Attachments. +Find files over 10MB. +What can be compressed or removed? +``` + +## Best Practices + +### File Sizes +- Keep images under 2MB for Git +- Compress large PDFs +- Use external storage for video +- Optimize images before committing + +### Naming +- Include date: `YYYY-MM-DD` +- Be descriptive but concise +- Use underscores not spaces +- Include version numbers if relevant + +### Linking +```markdown +# Embedding images +![[05_Attachments/Organized/diagram.png]] + +# Linking PDFs +[[05_Attachments/Organized/document.pdf]] + +# With descriptions +![[05_Attachments/Organized/chart.png|Sales Chart Q1]] +``` + +## Processing Workflow + +1. **Capture**: Save files to `05_Attachments/` +2. **Review**: Look at content, determine purpose +3. **Rename**: Give descriptive, dated name +4. **Organize**: Move to `Organized/` subfolder +5. **Link**: Update references in notes +6. **Clean**: Remove orphaned files + +## Claude Code Prompts + +### Vision Analysis +``` +Analyze the images in Attachments. +What do they contain? +Suggest appropriate names and organization. +``` + +### Bulk Processing +``` +Process all CleanShot files from this week. +Rename based on content. +Move to Organized. +``` + +### Storage Audit +``` +Analyze attachment storage: +- Total size +- Largest files +- File type distribution +- Orphaned files +``` + +## Tips + +- **Process weekly** - Don't let files pile up +- **Name immediately** - Context fades fast +- **Link purposefully** - Only embed what adds value +- **Compress aggressively** - Storage adds up +- **Delete liberally** - Not every screenshot matters + +## Git Considerations + +### .gitignore suggestions +``` +*.mp4 +*.mov +*.zip +.DS_Store +files_over_10mb/ +``` + +### For Large Files +- Use Git LFS for files over 10MB +- Consider external storage +- Link to cloud storage instead +- Keep local but gitignore + +## Remember + +Attachments support your notes, they don't replace them. A well-named, well-organized attachment is worth a thousand random screenshots. Use Claude Code's vision capabilities to help process and organize visual content efficiently. \ No newline at end of file diff --git a/06_Metadata/README.md b/06_Metadata/README.md new file mode 100644 index 0000000..79e3392 --- /dev/null +++ b/06_Metadata/README.md @@ -0,0 +1,138 @@ +# โš™๏ธ Metadata + +Vault configuration, documentation, and organizational tools. + +## Purpose + +The metadata folder contains: +- Documentation about the vault +- Templates for consistent note creation +- Reference guides and how-tos +- Agent configurations +- Workflow documentation + +## Structure + +``` +06_Metadata/ +โ”œโ”€โ”€ Reference/ # Guides and documentation +โ”œโ”€โ”€ Templates/ # Note templates +โ”œโ”€โ”€ Agents/ # Claude Code agent configs +โ”œโ”€โ”€ Workflows/ # Documented processes +โ””โ”€โ”€ Archive/ # Old configurations +``` + +## What Lives Here + +### Reference +- This vault's documentation +- Claude Code prompt library +- Style guides +- Workflow documentation +- Learning resources + +### Templates +- Project templates +- Daily note templates +- Meeting templates +- Research templates +- Review templates + +### Agents +- Thinking partner instructions +- Research assistant config +- Editor agent setup +- Custom agent definitions + +### Workflows +- Weekly review process +- Project completion checklist +- Inbox processing guide +- Archive procedures + +## Using Templates + +### Manual +1. Copy template content +2. Create new note +3. Paste and fill in + +### With Claude Code +``` +Create a new project using the project template. +Name it [Project Name] and put it in 01_Projects. +``` + +## Creating Custom Agents + +Save agent instructions as markdown files: + +```markdown +# Agent: [Name] + +You are a [role description]. + +## Core Behaviors +- Behavior 1 +- Behavior 2 + +## Workflow +1. Step 1 +2. Step 2 + +## Constraints +- Don't do X +- Always do Y +``` + +Then reference in Claude Code: +``` +Use the instructions in 06_Metadata/Agents/[agent].md +and help me with [task]. +``` + +## Claude Code Prompts + +### Template Usage +``` +Show me available templates in 06_Metadata/Templates. +Create a new [type] note using the appropriate template. +``` + +### Documentation +``` +Check 06_Metadata/Reference for documentation on [topic]. +Update the guide based on what we just learned. +``` + +### Workflow Execution +``` +Run the weekly review workflow from 06_Metadata/Workflows. +Guide me through each step. +``` + +## Maintenance + +### Regular Updates +- Update templates based on usage +- Document new workflows as they emerge +- Archive outdated configurations +- Keep reference docs current + +### Version Control +- Track changes to workflows +- Document why changes were made +- Keep archive of old versions +- Date major updates + +## Best Practices + +- **Document as you go** - Capture workflows while fresh +- **Iterate templates** - Improve based on usage +- **Share configurations** - What works for you might help others +- **Keep it simple** - Complex systems break +- **Date everything** - Context matters + +## Remember + +Metadata is the operating system of your vault. Good metadata means consistent structure, repeatable workflows, and scalable growth. This is where you document not just what you know, but how you work. \ No newline at end of file diff --git a/06_Metadata/Reference/Common Claude Code Prompts.md b/06_Metadata/Reference/Common Claude Code Prompts.md new file mode 100644 index 0000000..f10f245 --- /dev/null +++ b/06_Metadata/Reference/Common Claude Code Prompts.md @@ -0,0 +1,170 @@ +# Common Claude Code Prompts + +A collection of useful prompts for working with Claude Code in your vault. + +## Starting Work + +### Beginning a Session +``` +I'm starting work for today. +Can you review what I was working on yesterday +and help me pick up where I left off? +``` + +### Setting the Mode +``` +I'm in thinking mode, not writing mode. +Please help me explore [topic] by asking questions +and searching for relevant notes. +``` + +## Research & Synthesis + +### Finding Connections +``` +Search my vault for anything related to [topic]. +What patterns or connections do you see? +``` + +### Synthesizing a Project +``` +Review all notes in [project folder]. +Create a synthesis of the key themes, insights, and open questions. +``` + +### Weekly Review +``` +Look at all notes created this week. +What are the main themes? +What connections exist between different projects? +``` + +## Organization + +### Processing Inbox +``` +Review items in 00_Inbox. +Suggest where each should be moved based on PARA method. +Which items could be combined or linked? +``` + +### Finding Orphans +``` +Find notes that aren't linked to any other notes. +Suggest potential connections. +``` + +### Cleaning Attachments +``` +Review files in 05_Attachments. +Which ones aren't referenced in any notes? +Which could be better named? +``` + +## Writing & Creation + +### Moving to Writing Mode +``` +I'm ready to move from thinking to writing mode. +Based on our research in [project], +help me create an outline for [deliverable]. +``` + +### Improving a Draft +``` +Review [document]. +Don't rewrite it, but give me specific feedback on: +- Structure and flow +- Gaps in logic or evidence +- Areas that need clarification +``` + +## Learning & Development + +### Exploring a New Topic +``` +I want to learn about [topic]. +Start by searching my vault for any existing knowledge. +Then help me identify what I need to research. +``` + +### Making an Argument +``` +I'm trying to argue that [thesis]. +Search my notes for supporting evidence. +What counterarguments should I address? +``` + +## Project Management + +### Project Status +``` +Review the project in [folder]. +What's the current status? +What are the next actions needed? +``` + +### Creating a Retrospective +``` +[Project] is now complete. +Review all notes and create a retrospective covering: +- What was accomplished +- Key learnings +- What to do differently next time +``` + +## Daily Operations + +### Morning Review +``` +Good morning. Show me: +- Any notes modified yesterday +- Open tasks or questions +- What should I focus on today? +``` + +### End of Day Wrap-up +``` +End of day review: +- What did I accomplish today? +- What questions or ideas emerged? +- What should I prioritize tomorrow? +``` + +## Advanced Techniques + +### Cross-Project Analysis +``` +Compare insights from [Project A] and [Project B]. +What patterns exist across both? +What could each learn from the other? +``` + +### Knowledge Gaps +``` +Analyze my notes on [topic]. +What aspects am I missing? +What questions haven't I asked? +``` + +### Idea Development +``` +I have this rough idea: [idea] +Search for related concepts in my vault. +Help me develop this into something more concrete. +``` + +## Tips for Effective Prompts + +1. **Be specific about mode** (thinking vs writing) +2. **Reference specific folders** when relevant +3. **Ask for questions**, not just answers +4. **Request synthesis**, not just search +5. **Iterate freely** - have a conversation + +## Remember + +- Claude Code has access to your entire vault +- It can create, edit, and organize files +- Use it as a thinking partner, not just a tool +- The best prompts emerge from your specific needs \ No newline at end of file diff --git a/06_Metadata/Templates/Daily Note Template.md b/06_Metadata/Templates/Daily Note Template.md new file mode 100644 index 0000000..2261aad --- /dev/null +++ b/06_Metadata/Templates/Daily Note Template.md @@ -0,0 +1,24 @@ +# {{date:YYYY-MM-DD}} + +## Capture + +- + +## Questions + +- + +## Insights + +- + +## Connections + +- + +## For Tomorrow + +- + +--- +*End of day: Ask Claude Code to review and find connections* \ No newline at end of file diff --git a/06_Metadata/Templates/Project Template.md b/06_Metadata/Templates/Project Template.md new file mode 100644 index 0000000..3974850 --- /dev/null +++ b/06_Metadata/Templates/Project Template.md @@ -0,0 +1,40 @@ +# {{title}} + +## Project Overview +**Start Date**: {{date}} +**Target Completion**: +**Status**: Active + +## Objectives +- [ ] +- [ ] +- [ ] + +## Context + + +## Success Criteria + + +## Key Resources + + +## Progress Log + + +### {{date}} - Project Initiated +- Set up project structure +- Initial research phase + +## Open Questions + +- +- + +## Next Actions + +- [ ] +- [ ] + +--- +*Using Claude Code? Say: "I'm working on {{title}} in thinking mode. Let's explore."* \ No newline at end of file diff --git a/06_Metadata/Templates/Research Note Template.md b/06_Metadata/Templates/Research Note Template.md new file mode 100644 index 0000000..ea4bd64 --- /dev/null +++ b/06_Metadata/Templates/Research Note Template.md @@ -0,0 +1,32 @@ +# {{title}} + +**Source**: [URL or reference] +**Date**: {{date}} +**Tags**: #research + +## Summary + + +## Key Insights +- +- +- + +## Notable Quotes +> + +## Questions Raised +- +- + +## Connections + +- See: [[related note]] +- Contradicts: [[other perspective]] +- Builds on: [[foundation concept]] + +## Action Items +- [ ] + +--- +*For synthesis: "Review all research notes in [folder] and identify patterns"* \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..226901a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,65 @@ +# Changelog + +All notable changes to claudesidian will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.2.0] - 2025-01-13 + +### Added +- Release command for automated version management and releases +- Gemini Vision video analysis support: + - Local video files (MP4, AVI, MOV, WebM, MKV, WMV, FLV, 3GP, M4V) + - Direct YouTube URL analysis without download + - Automatic video processing state detection +- Updated documentation with video analysis examples + +### Changed +- Enhanced init-bootstrap command with full environment setup including MCP configuration +- Updated Gemini Vision MCP server to support video formats + +## [0.1.0] - 2025-01-13 + +### Added +- Initial release of claudesidian - Claude Code + Obsidian starter kit +- PARA method folder structure (00_Inbox through 06_Metadata) +- Bootstrap initialization system via `claude run init-bootstrap` +- Pre-configured Claude Code commands: + - thinking-partner - Collaborative thinking mode + - inbox-processor - Organize 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 + - add-frontmatter - Add metadata to notes + - init-bootstrap - Interactive setup wizard +- Claude Code agents: + - thinking-partner agent for exploration and brainstorming +- Helper scripts: + - firecrawl-batch.sh - Batch web scraping + - firecrawl-scrape.sh - Single URL scraping + - fix-renamed-links.js - Fix broken links after renames + - update-attachment-links.js - Update attachment references + - transcript-extract.sh - Extract YouTube transcripts + - vault-stats.sh - Show vault statistics +- Attachment management commands via pnpm +- Gemini Vision MCP server for image/PDF analysis (optional) +- CLAUDE-BOOTSTRAP.md template for configuration +- Comprehensive README with setup instructions +- Install script for automated setup +- Git integration with proper .gitignore + +### Changed +- Replaced static CLAUDE.md with dynamic init-bootstrap command + +### Security +- API keys stored in environment variables +- .mcp.json gitignored for security + +[Unreleased]: https://github.com/heyitsnoah/claudesidian/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/heyitsnoah/claudesidian/compare/v0.1.0...v0.2.0 +[0.1.0]: https://github.com/heyitsnoah/claudesidian/releases/tag/v0.1.0 \ No newline at end of file diff --git a/CLAUDE-BOOTSTRAP.md b/CLAUDE-BOOTSTRAP.md new file mode 100644 index 0000000..9a8e963 --- /dev/null +++ b/CLAUDE-BOOTSTRAP.md @@ -0,0 +1,210 @@ +# Obsidian Vault Guidelines - Bootstrap Template + +**Getting Started with Claude Code + Obsidian** + +## Quick Setup + +1. **Start every session**: Run `git pull` to sync latest changes +2. **After changes**: Commit and push to preserve your work +3. **Use built-in tools**: Prefer WebSearch and WebFetch for web content + +## Version Control Best Practices + +**CRITICAL - START EVERY SESSION**: Always run `git pull` at the beginning of each new Claude session to ensure you have the latest changes from the remote repository. + +**Commit workflow**: +- After creating new notes: `git add .` โ†’ `git commit -m "message"` โ†’ `git push` +- After significant edits: Commit and push immediately +- Use `git status` to check for modifications +- When agents modify files: Always commit those changes + +## Folder Structure (PARA Method) + +``` +vault/ +โ”œโ”€โ”€ 00_Inbox/ # Temporary capture point +โ”œโ”€โ”€ 01_Projects/ # Time-bound initiatives +โ”œโ”€โ”€ 02_Areas/ # Ongoing responsibilities +โ”œโ”€โ”€ 03_Resources/ # Reference materials +โ”œโ”€โ”€ 04_Archive/ # Completed/inactive items +โ”œโ”€โ”€ 05_Attachments/ # Images, PDFs, etc. +โ”‚ โ””โ”€โ”€ Organized/ # Processed attachments +โ””โ”€โ”€ 06_Metadata/ # Documentation & templates + โ”œโ”€โ”€ Reference/ # Guides and standards + โ”œโ”€โ”€ Plans/ # Strategic documents + โ””โ”€โ”€ Templates/ # Reusable structures +``` + +## PARA Method Details + +### Projects (01) +- Time-bound initiatives with clear completion criteria +- Examples: Writing a paper, developing a presentation +- Recommended subfolders: Research/, Drafts/, References/, Output/ + +### Areas (02) +- Ongoing responsibilities without end dates +- Examples: Health, Finances, Professional Development +- Create dedicated notes with links to related resources + +### Resources (03) +- Topics of interest for reference +- Knowledge bases organized by subject +- Use for information not tied to specific projects + +### Archive (04) +- Completed or inactive items +- Maintain same folder structure as active sections +- Review periodically for reactivation + +## Inbox Management + +### Core Principles +- Inbox is temporary, not permanent storage +- Process weekly using Capture โ†’ Process โ†’ Organize workflow +- Maintain <20 items at any time + +### Files to Keep in Inbox +- **CRITICAL**: Files with number prefixes (00-06) stay permanently +- Recent daily/weekly summaries (last 3 months) +- Active notes being processed + +### Processing Workflow +1. Delete obsolete information +2. Move relevant material to PARA locations +3. Convert actions into project tasks +4. Tag items needing more processing with `#needs-processing` + +## File Organization Guidelines + +### Naming Conventions +- Daily notes: `YYYY-MM-DD - Topic` +- Meeting notes: `Meeting - [Topic] - YYYY-MM-DD` +- Ideas: `Idea - [Brief Description]` +- Resources: `Resource - [Topic] - [Source]` + +### Movement Rules +- Use `mv` command (not `cp`) to avoid duplicates +- Verify destination folders exist first +- Update internal links after moves +- Add YAML frontmatter when organizing + +## Attachments Management + +### Organization +- Store all non-text files in `05_Attachments/` +- Processed files โ†’ `05_Attachments/Organized/` +- Naming: `[RelatedNote]_[Description].[ext]` + +### Helper Scripts +```bash +pnpm attachments:list # List unprocessed files +pnpm attachments:organized # Count organized files +pnpm attachments:orphans # Find unreferenced files +pnpm attachments:update-links # Update links after moving +``` + +## Web Content Workflow + +### Built-in Tools (Preferred) +- **WebSearch**: For general web searches +- **WebFetch**: For specific URLs +- Save to appropriate folder based on content type + +### Custom Scripts (When Needed) +- Single URL: `pnpm firecrawl:scrape ` +- Batch URLs: `pnpm firecrawl:batch ` +- Saves to `00_Inbox/Clippings/` with frontmatter + +## Writing Style Guidelines + +### Structure +- Use `[[WikiLinks]]` for internal references +- Include YAML frontmatter (dates, tags, status) +- Consistent Markdown formatting +- Specific, consistent tags + +### Style Preferences +- Direct and confident statements +- Avoid clichรฉd transitions +- Let statements stand on their own +- No unnecessary lead-ins + +## AI Assistant Guidelines + +### Before Any Organization +1. Map complete folder structure: `find . -type d | sort` +2. Document in `06_Metadata/STRUCTURE.md` +3. Verify all destination folders exist + +### Working with Content +- Respect numbered core files (never move 00-06 prefixed files) +- Always use `mv` not `cp` when organizing +- Preserve and update bidirectional links +- Add appropriate YAML frontmatter + +### Simple Commands Only +- **REQUIRED**: Direct, basic commands without filtering +- **FORBIDDEN**: Complex regex, piped commands, find with filters +- Example RIGHT: `ls -1` then manually select files +- Example WRONG: `ls | grep pattern` or `find . -name "*.png"` + +## Daily Workflows + +### Start of Day +1. Run `git pull` +2. Check inbox for items to process +3. Review active projects + +### End of Day +1. Process new inbox items +2. Commit and push changes +3. Update project notes + +### Weekly Review +1. Process entire inbox +2. Archive completed projects +3. Update area notes +4. Review and consolidate resources + +## Project Lifecycle + +### Starting a Project +1. Create folder in `01_Projects/[ProjectName]` +2. Add subfolders: Research/, Drafts/, Output/ +3. Create README with objectives and timeline + +### During Project +- Keep all related materials in project folder +- Link to relevant resources and areas +- Regular commits to track progress + +### Completing a Project +1. Create project summary note +2. Move entire folder to `04_Archive/` +3. Update relevant area notes +4. Commit with completion message + +## Best Practices + +### Organization +- Keep folder structure shallow (max 3 levels) +- Create subfolders only with 7+ related notes +- Use linking over deep nesting +- Include README in major folders + +### Content Creation +- Capture first, organize later +- One idea per note +- Link generously +- Tag consistently + +### Maintenance +- Weekly inbox processing +- Monthly project reviews +- Quarterly archive cleanup +- Regular git commits + +--- + +*This is a bootstrap template. Customize based on your workflow and needs.* \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d21afe5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,118 @@ +# Claudesidian Repository Management + +**โš ๏ธ IMPORTANT: This CLAUDE.md is for maintaining the claudesidian repository itself.** + +**If you're a user setting up your own Obsidian vault:** +- Run `claude run init-bootstrap` to create your personalized CLAUDE.md +- That command will overwrite this file with your custom configuration +- This file is only for contributors working on the claudesidian project + +--- + +## Repository Overview + +Claudesidian is a starter kit that combines Claude Code with Obsidian for AI-powered knowledge management. This document contains guidelines for maintaining and developing the repository. + +## Version Management + +This project uses: +- **Semantic Versioning** (MAJOR.MINOR.PATCH) +- **Keep a Changelog** format in CHANGELOG.md +- **Conventional Commits** for commit messages +- **GitHub Releases** for distribution + +### Commit Message Format +``` +feat: add new feature +fix: resolve bug +docs: update documentation +chore: maintenance tasks +``` + +### Release Process +1. Update version in `package.json` +2. Move "Unreleased" items to new version in `CHANGELOG.md` +3. Commit: `git commit -m "chore: release v0.2.0"` +4. Tag: `git tag v0.2.0` +5. Push: `git push && git push --tags` +6. GitHub automatically creates release from tag + +## Project Structure + +``` +claudesidian/ +โ”œโ”€โ”€ .claude/ +โ”‚ โ”œโ”€โ”€ agents/ # Claude Code agents +โ”‚ โ”œโ”€โ”€ commands/ # Slash commands +โ”‚ โ””โ”€โ”€ mcp-servers/ # MCP server implementations +โ”œโ”€โ”€ .scripts/ # Helper bash/js scripts +โ”œโ”€โ”€ 00_Inbox/ through 06_Metadata/ # Template PARA folders +โ”œโ”€โ”€ CHANGELOG.md # Version history +โ”œโ”€โ”€ CONTRIBUTING.md # Contribution guidelines +โ”œโ”€โ”€ README.md # User documentation +โ”œโ”€โ”€ CLAUDE-BOOTSTRAP.md # Template for user CLAUDE.md +โ””โ”€โ”€ package.json # Dependencies and version +``` + +## Key Components + +### Commands +- `init-bootstrap` - Main setup wizard that overwrites this file +- `thinking-partner` - Collaborative thinking mode +- `create-command` - Generate new commands +- Other pre-configured commands for vault management + +### Scripts +- Installation and setup scripts +- Attachment management utilities +- Web scraping tools (firecrawl) +- Link maintenance utilities + +### MCP Servers +- Gemini Vision for image/PDF analysis +- Configured during init-bootstrap if user chooses + +## Development Guidelines + +### Adding New Features +1. Create feature in appropriate directory +2. Update CHANGELOG.md under "Unreleased" +3. Update README if user-facing +4. Test with fresh clone + +### Testing Changes +```bash +# Clone fresh copy +git clone https://github.com/heyitsnoah/claudesidian.git test-claudesidian +cd test-claudesidian +pnpm install +claude run init-bootstrap # Test the setup flow +``` + +### Important Files +- **CLAUDE-BOOTSTRAP.md** - Template that init-bootstrap uses +- **package.json** - Version and dependencies +- **.github/release.yml** - GitHub release categorization + +## Maintenance Tasks + +### Regular Updates +- Review and update dependencies +- Test init-bootstrap flow +- Update documentation for clarity +- Check for broken scripts + +### User Support +- Issues at: https://github.com/heyitsnoah/claudesidian/issues +- Keep README clear and comprehensive +- Ensure init-bootstrap handles edge cases + +## Note for Contributors + +Remember that users will run `init-bootstrap` which: +1. Reads CLAUDE-BOOTSTRAP.md as template +2. Asks personalization questions +3. **Overwrites this CLAUDE.md** with user's configuration +4. Sets up their personal Obsidian vault + +This separation ensures the repository maintenance instructions (this file) don't interfere with user's personal vault configuration. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..69a7da6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# Contributing to Claudesidian + +Thank you for your interest in contributing to claudesidian! This document provides guidelines for contributing to the project. + +## Development Setup + +1. Fork the repository +2. Clone your fork: `git clone https://github.com/yourusername/claudesidian.git` +3. Install dependencies: `pnpm install` +4. Create a feature branch: `git checkout -b feature/your-feature-name` + +## Commit Message Convention + +We follow [Conventional Commits](https://www.conventionalcommits.org/) for clear commit history: + +- `feat:` New feature +- `fix:` Bug fix +- `docs:` Documentation changes +- `style:` Code style changes (formatting, etc.) +- `refactor:` Code refactoring +- `test:` Test additions or changes +- `chore:` Maintenance tasks + +Examples: +``` +feat: add new research-assistant command +fix: correct attachment link updates in scripts +docs: update README with MCP setup instructions +``` + +## Versioning + +We use [Semantic Versioning](https://semver.org/): +- MAJOR (1.0.0): Breaking changes +- MINOR (0.1.0): New features (backward compatible) +- PATCH (0.0.1): Bug fixes (backward compatible) + +## Pull Request Process + +1. Update the CHANGELOG.md with your changes under "Unreleased" +2. Update documentation if needed +3. Ensure all scripts still work +4. Submit PR with clear description of changes + +## Changelog Updates + +When contributing, add your changes to CHANGELOG.md under the "Unreleased" section: + +```markdown +## [Unreleased] + +### Added +- Your new feature here + +### Fixed +- Your bug fix here +``` + +Use these categories: +- **Added** - New features +- **Changed** - Changes to existing functionality +- **Deprecated** - Features to be removed +- **Removed** - Removed features +- **Fixed** - Bug fixes +- **Security** - Security updates + +## Release Process (Maintainers) + +1. Update version in package.json +2. Move "Unreleased" items to new version in CHANGELOG.md +3. Commit: `git commit -m "chore: release v0.2.0"` +4. Tag: `git tag v0.2.0` +5. Push: `git push && git push --tags` +6. Create GitHub Release from tag, using changelog content + +## Code Style + +- Use clear, descriptive variable names +- Comment complex logic +- Keep functions focused and small +- Test your changes thoroughly + +## Questions? + +Feel free to open an issue for discussion before making large changes. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..9e5c1da --- /dev/null +++ b/README.md @@ -0,0 +1,296 @@ +# 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. Clone and Install +```bash +git clone https://github.com/heyitsnoah/claudesidian.git +cd claudesidian +./install.sh # Automated setup script +``` + +Or manually: +```bash +pnpm install # Install dependencies +mkdir -p 05_Attachments/Organized # Create organized folder +``` + +### 2. 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 + +### 3. Start Claude Code +```bash +# Make sure you have Claude Code installed +# Start it in the vault directory +claude +``` + +### 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. +``` + +## 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 + +## Essential Workflows + +### Starting a Research Project + +1. Create project folder: +```bash +mkdir -p "01_Projects/My_New_Project/{Research,Chats,Daily_Progress}" +``` + +2. Tell Claude Code: +``` +I'm starting a project on [topic] in 01_Projects/My_New_Project. +I'm in thinking mode. Help me explore this topic. +``` + +3. Let Claude search your vault and ask clarifying questions + +### Daily Capture + +1. Create a daily note in `00_Inbox/` +2. Dump thoughts, links, ideas throughout the day +3. Weekly: Process inbox items to appropriate folders + +### Synthesizing Research + +Ask Claude Code: +``` +Can you review all notes in [project folder] +and create a synthesis of the key themes and insights? +``` + +## 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 + +Run with: `claude run [command-name]` + +## Vision & Document Analysis (Optional) + +With Gemini MCP configured, you can: +- Analyze images and screenshots +- Extract text from PDFs +- Compare multiple images +- Generate smart filenames +- Process documents + +See `.claude/mcp-servers/README.md` for setup + +## 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 + +### 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 Agents + +Create specialized agents by saving instructions: + +**Thinking Partner** (`06_Metadata/Agents/thinking-partner.md`): +```markdown +You are a collaborative thinking partner. +- Ask clarifying questions +- Help explore connections +- Track insights in a running log +- Never jump to solutions too quickly +``` + +**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 + +### Common Patterns + +**The Daily Review**: +``` +What new notes were created today? +What connections can you see between today's work and my existing notes? +``` + +**The Weekly Synthesis**: +``` +Review all notes from this week. +What are the key themes and insights? +What questions remain unanswered? +``` + +**The Project Retrospective**: +``` +This project is complete. +Create a summary of what was learned and accomplished. +What should be archived vs kept accessible? +``` + +## 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 `npm run 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 + +This is a living template. As you develop workflows that work for you: +1. Document them in `06_Metadata/Reference/` +2. Share back with the community +3. Remember: best practices emerge from use, not theory + +## 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.* \ No newline at end of file diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..de066f6 --- /dev/null +++ b/install.sh @@ -0,0 +1,104 @@ +#!/bin/bash + +echo "๐Ÿš€ Claudesidian Setup Script" +echo "==========================" +echo "" + +# Check for required tools +check_command() { + if ! command -v "$1" &> /dev/null; then + echo "โŒ $1 is not installed" + return 1 + else + echo "โœ… $1 is installed" + return 0 + fi +} + +echo "Checking required tools..." +echo "" + +# Check essentials +check_command "git" +GIT_OK=$? + +check_command "node" +NODE_OK=$? + +check_command "pnpm" +PNPM_OK=$? + +# Check optional tools +echo "" +echo "Checking optional tools..." +check_command "yt-dlp" || echo " โ†’ Install with: brew install yt-dlp (for YouTube transcripts)" +check_command "jq" || echo " โ†’ Install with: brew install jq (for JSON processing)" +check_command "rg" || echo " โ†’ Install with: brew install ripgrep (for better search)" + +echo "" + +# Install pnpm if needed +if [ $PNPM_OK -ne 0 ]; then + echo "๐Ÿ“ฆ Installing pnpm..." + npm install -g pnpm + echo "โœ… pnpm installed" +fi + +# Install dependencies +echo "๐Ÿ“ฆ Installing dependencies..." +pnpm install + +# Create necessary directories +echo "" +echo "๐Ÿ“ Creating folder structure..." +mkdir -p 00_Inbox 01_Projects 02_Areas 03_Resources 04_Archive 05_Attachments/Organized 06_Metadata/{Reference,Templates} +echo "โœ… Folders created" + +# Git setup +if [ $GIT_OK -eq 0 ]; then + if [ ! -d ".git" ]; then + echo "" + echo "๐Ÿ”ง Initializing git repository..." + git init + git add . + git commit -m "Initial vault setup" + echo "โœ… Git repository initialized" + fi +fi + +# Gemini API setup +echo "" +echo "๐Ÿ”ฎ Gemini Vision Setup (Optional)" +echo "=================================" +echo "" +echo "To enable image and document analysis:" +echo "1. Get your free API key from: https://aistudio.google.com/apikey" +echo "2. Add to your shell profile (~/.zshrc or ~/.bashrc):" +echo "" +echo " export GEMINI_API_KEY='your-key-here'" +echo "" +echo "3. Reload your shell: source ~/.zshrc" +echo "4. Test with: pnpm test-gemini" +echo "" + +# Obsidian check +echo "๐Ÿ“ Obsidian Setup" +echo "================" +if [ -d "/Applications/Obsidian.app" ] || [ -d "$HOME/.local/share/applications/obsidian.desktop" ]; then + echo "โœ… Obsidian detected" + echo " Open this folder as a vault in Obsidian" +else + echo "๐Ÿ“ฅ Download Obsidian from: https://obsidian.md" + echo " Then open this folder as a vault" +fi + +echo "" +echo "๐ŸŽ‰ Setup Complete!" +echo "=================" +echo "" +echo "Next steps:" +echo "1. Start Claude Code in this directory: claude" +echo "2. Read the Welcome note in 00_Inbox/" +echo "3. Try: claude run thinking-partner" +echo "" +echo "Happy note-taking! ๐Ÿง โœจ" \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..3b50579 --- /dev/null +++ b/package.json @@ -0,0 +1,35 @@ +{ + "name": "claudesidian", + "version": "0.2.0", + "description": "Claude Code + Obsidian Starter Kit - AI-powered second brain", + "type": "module", + "scripts": { + "setup": "pnpm install && echo 'โœ… Setup complete! Configure GEMINI_API_KEY for vision features'", + "test-gemini": "GEMINI_API_KEY=${GEMINI_API_KEY} node .claude/mcp-servers/gemini-vision.mjs", + "attachments:list": "ls -1 '05_Attachments/' | grep -v Organized | head -20", + "attachments:count": "ls -1 '05_Attachments/' | grep -v Organized | wc -l", + "attachments:organized": "ls -1 '05_Attachments/Organized' 2>/dev/null | wc -l || echo '0'", + "attachments:unprocessed": "pnpm attachments:count", + "attachments:refs": "grep -r \"$1\" . --include=\"*.md\" 2>/dev/null | head -20", + "attachments:sizes": "find 05_Attachments -type f -exec du -h {} + | sort -rh | head -20", + "attachments:orphans": "for file in 05_Attachments/*; do basename \"$file\" | xargs -I {} sh -c 'grep -r \"{}\" . --include=\"*.md\" > /dev/null || echo \"{}\"'; done", + "attachments:recent": "find 05_Attachments -type f -mtime -7 -exec ls -la {} \\;", + "attachments:create-organized": "mkdir -p 05_Attachments/Organized", + "vault:stats": ".scripts/vault-stats.sh" + }, + "keywords": [ + "obsidian", + "claude", + "claude-code", + "ai", + "second-brain", + "knowledge-management", + "para-method" + ], + "author": "", + "license": "MIT", + "dependencies": { + "@google/generative-ai": "^0.21.0", + "@modelcontextprotocol/sdk": "^1.0.0" + } +} \ No newline at end of file