Like Gmail, but for your GitHub notifications.

Features • Quick Start • Documentation • Contributing

Octobud is a Mac desktop application that helps you manage the flood of GitHub notifications with filtering, custom views, keyboard shortcuts, and automation rules.

Built with Go and Svelte 5. Runs as a single binary with SQLite - no external dependencies required. On macOS, Octobud runs as a menu bar app that opens your browser to a local web interface.

• macOS: Full support with menu bar integration, auto-start, and secure Keychain storage for GitHub credentials
• Linux & Windows: Core functionality works, but menu bar integration and auto-start are not available. GitHub credentials are encrypted at rest, but the encryption key is stored locally, so an attacker with machine access could decrypt them. Keychain support is planned for a future release.

If you manage many GitHub notifications, you know that organizing and triaging them efficiently can be a major challenge.

Octobud builds on GitHub's notification system and provides a Gmail-like experience for notification management: rich filtering and querying, custom filter views, keyboard shortcuts, automation rules, and more, all running locally on your machine.

Download Latest Release - Download the .pkg installer for your Mac (Apple Silicon or Intel). Octobud will appear in your menu bar and open automatically in your browser.

Official releases with embedded assets are currently only available for macOS. For Linux and Windows, you must build from source (see below). The app will be accessible at http://localhost:8808 in your browser. Note: Menu bar integration and auto-start are not available on these platforms.

Note: Keychain support is not yet implemented on Linux and Windows. Your GitHub OAuth token or PAT will be encrypted at rest, but because the encryption key will be stored in plain text, anyone with access to your machine can still get your token.

Prerequisites: Go 1.24+ and Node.js 24+

git clone https://github.com/octobud-hq/octobud.git && cd octobud
make build
./bin/octobud

🎉 That's it! On macOS, Octobud will appear in your menu bar and open in your browser. On Linux and Windows, open http://localhost:8808 manually. Connect your GitHub account using either OAuth or a Personal Access Token (PAT). Both methods work equally well - choose OAuth for convenience, or PAT if your organization disables OAuth apps or you have multiple GitHub orgs. See the OAuth Setup Guide or Personal Access Token Setup Guide for detailed instructions.

# Terminal 1: Backend
make backend-dev

# Terminal 2: Frontend
make frontend-dev

./bin/octobud --help
  -port int        Port to listen on (default 8808)
  -data-dir string Data directory (default: platform-specific)
  -no-open         Don't open browser on startup
  -version         Show version and exit

When you first launch Octobud, you'll be guided through setup:

1. Connect GitHub - You'll be prompted to connect your GitHub account. Choose either OAuth or a Personal Access Token (PAT). Both methods work equally well:

   • OAuth - Convenient and secure, uses GitHub's device flow
   • PAT - Recommended if your organization disables OAuth apps or you have multiple GitHub orgs

   Both require the following scopes:

   • repo
   • notifications
   • read:discussions (this permission is only required for PAT)

   See the OAuth Setup Guide or Personal Access Token Setup Guide for detailed instructions. You can update your authentication method later in Settings → Account.

2. Configure Initial Sync - Next, you'll be prompted to configure how far back to sync notifications. Start small (30 days) - you can always sync more later.

3. Learn the basics - Press h for keyboard shortcuts, or see Start Here.

Here are some recommended views and rules to help you get started:

Views:

• Assigned / Authored - in:inbox,filtered (reason:assign OR author:<YOUR_USERNAME>)
• Reviews - in:inbox,filtered reason:review_requested

Views with auto-filter rule:

• [Bots] - in:inbox,filtered author:[bot] + rule to skip inbox

See the Views & Rules guide for detailed instructions on creating views and rules.

• Start Here - Initial setup and core workflows
• OAuth Setup - Complete guide for OAuth authentication
• Personal Access Token Setup - Complete guide for PAT setup
• Query Syntax - Filter and search notifications
• Keyboard Shortcuts - Navigate efficiently
• Views & Rules - Organize your inbox
• Concepts - How syncing, queries, and actions work
• Architecture - Technical architecture overview
• Troubleshooting - Common issues and solutions
• Migration Guide - Upgrading and database migrations

See ROADMAP.md for planned features.

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve documentation

Found a security vulnerability? Please report it responsibly. See SECURITY.md for details.

Octobud is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means you're free to use, modify, and distribute this software, but if you run a modified version as a network service, you must make the source code available to users of that service.

• 💬 Discussions - Ask questions and share ideas
• 🐛 Issue Tracker - Report bugs and request features
• 📚 Documentation - Comprehensive guides and reference

Octobud is an independent, open-source project. It is not affiliated with, endorsed by, or officially supported by GitHub, Inc. GitHub and the GitHub logo are trademarks of GitHub, Inc.

Made with ❤️ by someone who hates reading GitHub notifications in plain text and managing a million Gmail filters.