Obsidian GitHub Integration Setup Guide

The Obsidian GitHub integration enables Benny Chat to access and search your Obsidian vault hosted on GitHub. This allows the assistant to reference your personal notes, documentation, and knowledge base during conversations.

Prerequisites

Before you begin, make sure you have:

• An Obsidian vault with your notes
• A GitHub account
• GitHub Desktop (recommended) or Git installed

Step 1: Create a GitHub Repository for Your Obsidian Vault

1. Go to GitHub and sign in
2. Click the "+" icon in the top right and select "New repository"
3. Name your repository (e.g., "my-obsidian-vault")
4. Choose Private if you want to keep your notes private
5. Don't initialize with README, .gitignore, or license
6. Click "Create repository"

Step 2: Upload Your Obsidian Vault to GitHub

Option A: Using GitHub Desktop (Recommended)

1. Download and install GitHub Desktop
2. Sign in with your GitHub account
3. Click "Add" → "Add Existing Repository"
4. Navigate to your Obsidian vault folder (even if it's in iCloud)
5. If prompted to create a repository, click "Create Repository"
6. In GitHub Desktop, click "Publish repository"
7. Ensure the repository name matches what you created on GitHub
8. Keep "Keep this code private" checked if desired
9. Click "Publish repository"

Option B: Using Command Line

1. Open Terminal in your Obsidian vault directory
2. Run these commands:

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
   git push -u origin main
   

Step 3: Extract Repository Information

From your GitHub repository URL (e.g., https://github.com/johndoe/my-obsidian-vault), identify:

• Repository Owner: johndoe (your GitHub username or organization)
• Repository Name: my-obsidian-vault

Step 4: Generate a GitHub Fine-Grained Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click "Generate new token"
3. Configure basic settings:
   • Token name: "Benny Chat Obsidian Access"
   • Expiration: 90 days (recommended) or custom date
   • Description (optional): "Read-only access for Obsidian vault"
4. Configure Repository access:
   • Select "Only select repositories"
   • Click "Select repositories" dropdown
   • Choose your Obsidian vault repository
5. Click "Generate token" (no need to modify permissions - default read access is sufficient)
6. Important: Copy the token immediately - you won't see it again!

Note: Fine-grained tokens provide better security. The default permissions give read-only access to your selected repository, which is all that's needed.

Step 5: Configure in Benny Chat

1. Open Benny Chat and go to Settings
2. Scroll to "MCP Tool Settings"
3. Find "Obsidian GitHub" in the list
4. Click "Configure" or the settings icon
5. Enter your configuration:
   • GitHub Token: Paste your personal access token from Step 4
   • Owner: Your GitHub username (e.g., johndoe)
   • Repository: Your repository name (e.g., my-obsidian-vault)
6. Toggle the switch to enable the integration
7. Click "Test Connection"
8. You should see a success message with available tools

Keeping Your Notes Synchronized

Automatic Sync with GitHub Desktop

1. GitHub Desktop will detect changes in your Obsidian vault
2. When you see changes, add a commit message (e.g., "Daily notes update")
3. Click "Commit to main"
4. Click "Push origin" to upload changes to GitHub

Manual Sync

After making changes in Obsidian:

git add .
git commit -m "Update notes"
git push

Pulling Latest Changes in Benny Chat

Your notes are fetched in real-time from GitHub, so once you push changes, they're immediately available in Benny Chat conversations.

Available Features

Once configured, you can:

• Search notes by filename: "Find my note about project planning"
• Search note contents: "Search for notes mentioning 'machine learning'"
• Read specific notes: "Show me my daily note from yesterday"
• Reference multiple notes: "What do my meeting notes say about the Q4 roadmap?"
• Track changes: "What notes have I updated recently?"

Usage Examples

• "Check my Obsidian notes about the Python project"
• "Find all notes tagged with #ideas"
• "What's in my 'Projects/WebDev' folder?"
• "Search for notes containing 'API design'"
• "Show me my most recent daily notes"

Best Practices

1. Organize your vault: Use folders and consistent naming
2. Use frontmatter: Add tags and metadata to notes for better search
3. Regular commits: Push changes daily or after important updates
4. Meaningful commit messages: Helps track when specific notes were updated
5. .gitignore file: Exclude .obsidian/workspace and other local settings

Recommended .gitignore for Obsidian

Create a .gitignore file in your vault root:

.obsidian/workspace*
.obsidian/workspaces.json
.trash/
.DS_Store

Troubleshooting

Connection Test Failed

1. Verify all three parameters are correct:
   • GitHub Token: No extra spaces or quotes
   • Owner: Your GitHub username (not email, not organization name unless it's an org repo)
   • Repository: Repository name exactly as shown in GitHub (case-sensitive, no .git extension)
2. Check token configuration:
   • Token hasn't expired (check GitHub Settings → Developer settings → Personal access tokens)
   • Repository is selected in your fine-grained token's configuration
   • Token was generated after selecting the repository
3. Ensure repository exists and you have access:
   • Visit https://github.com/[owner]/[repo] to confirm
   • For private repos, ensure you're logged into the correct GitHub account

Notes Not Found

1. Confirm notes are pushed to GitHub
2. Check GitHub directly to see if files are there
3. Try searching with different terms
4. Ensure you're not in a branch other than main

Permission Denied

1. Token issues:
   • Token might have expired - check GitHub Settings → Personal access tokens
   • Generate a new token if expired
2. Repository changes:
   • Repository visibility might have changed (public → private)
   • Repository might have been deleted or renamed
3. Token configuration:
   • For fine-grained tokens: Ensure the repository is still selected in token settings
   • You may need to edit the token to re-add repository access

Privacy Considerations

• Only repositories you explicitly configure are accessible
• Private repositories remain private with proper token scopes
• Benny Chat accesses notes only when you request them
• No caching of note contents beyond conversation context

Need Help?

1. Review GitHub's token documentation
2. Ask Benny Chat for help with specific error messages