{"id":30707041,"url":"https://github.com/tidusjar/octobar","last_synced_at":"2026-06-23T22:03:11.716Z","repository":{"id":312617330,"uuid":"1048064002","full_name":"tidusjar/OctoBar","owner":"tidusjar","description":"GitHub notifications, without the noise.","archived":false,"fork":false,"pushed_at":"2025-08-31T21:58:19.000Z","size":109,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T23:40:00.946Z","etag":null,"topics":["github","notifications"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tidusjar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-31T20:45:33.000Z","updated_at":"2025-08-31T21:58:22.000Z","dependencies_parsed_at":"2025-08-31T23:40:04.585Z","dependency_job_id":"7c067cd9-a7c7-4002-b7ff-5215f8d278ed","html_url":"https://github.com/tidusjar/OctoBar","commit_stats":null,"previous_names":["tidusjar/octobar"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tidusjar/OctoBar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidusjar%2FOctoBar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidusjar%2FOctoBar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidusjar%2FOctoBar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidusjar%2FOctoBar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tidusjar","download_url":"https://codeload.github.com/tidusjar/OctoBar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidusjar%2FOctoBar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273341736,"owners_count":25088416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","notifications"],"created_at":"2025-09-02T20:13:55.310Z","updated_at":"2026-06-23T22:03:11.683Z","avatar_url":"https://github.com/tidusjar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OctoBar - GitHub Notifications Menu Bar App\n\nA cross-platform menu bar/system tray application built with Electron + React + TypeScript that provides a filtered inbox for GitHub notifications.\n\n**Supported Platforms:**\n- macOS (menu bar integration)\n- Windows (system tray integration)\n\n## Features\n\n- **System Tray Integration**: Tray icon with unread notification badge count (macOS) and context menu (Windows)\n- **Cross-Platform Styling**: Native-like dropdown menu styled for both macOS and Windows\n- **Smart Grouping**: Notifications grouped by Repository\n- **Rich Notifications**: Shows title, type (PR, issue, review request, mention), and relative time\n- **Quick Actions**: Mark as read, Open in browser, Mute thread, Star/Prioritize\n- **Smart Filters**: Work, Personal, and All views\n- **GitHub API Integration**: Real-time notifications from GitHub API\n- **Setup Wizard**: Guided setup for GitHub Personal Access Token\n- **Secure Storage**: PAT stored securely using system keychain (macOS Keychain/Windows Credential Manager)\n- **Real-time Updates**: Live notification loading and status updates\n- **Error Handling**: Graceful error handling with retry functionality\n- **Offline Caching**: Cache last 100 notifications for quick loading\n- **Background Refresh**: Automatic notification updates at configurable intervals (1-60 minutes)\n- **Desktop Notifications**: Native desktop notifications with sound alerts\n- **Notification Settings**: Configurable sound and desktop notification preferences\n- **Debug Mode**: Hidden developer tools for testing and troubleshooting\n- **Theme Support**: Light, dark, and system theme modes\n- **Filter Management**: Advanced filtering by organizations and repositories\n\n## Project Structure\n\n```\nsrc/\n├── main/                 # Electron main process\n│   ├── main.ts         # Main process entry point\n│   ├── preload.ts      # Preload script for secure IPC\n│   └── secureStorage.ts # Secure PAT storage using keytar\n├── renderer/            # React renderer process\n│   ├── components/      # React components\n│   │   ├── Header.tsx\n│   │   ├── FilterBar.tsx\n│   │   ├── NotificationList.tsx\n│   │   ├── NotificationItem.tsx\n│   │   ├── QuickActions.tsx\n│   │   ├── SetupWizard.tsx\n│   │   ├── SettingsModal.tsx\n│   │   ├── FilterSettingsModal.tsx\n│   │   └── setup/       # Setup wizard steps\n│   │       ├── WelcomeStep.tsx\n│   │       ├── PATStep.tsx\n│   │       ├── FilterStep.tsx\n│   │       └── CompletionStep.tsx\n│   ├── services/        # Data services\n│   │   ├── githubService.ts\n│   │   └── notificationService.ts\n│   ├── contexts/        # React contexts\n│   │   └── ThemeContext.tsx\n│   ├── hooks/           # Custom React hooks\n│   │   └── useBackgroundRefresh.ts\n│   ├── types/           # TypeScript type definitions\n│   │   ├── notifications.ts\n│   │   ├── electron.d.ts\n│   │   └── electron-api.d.ts\n│   ├── App.tsx          # Main React component\n│   ├── main.tsx         # React entry point\n│   ├── index.html       # HTML template\n│   └── App.css          # Styles\n├── package.json         # Dependencies and scripts\n├── tsconfig.json        # TypeScript config for renderer\n├── tsconfig.main.json   # TypeScript config for main process\n└── vite.config.ts       # Vite build configuration\n```\n\n## Development Setup\n\n### Prerequisites\n\n- Node.js 18+ \n- npm or yarn\n- **macOS** (for native menu bar integration) or **Windows** (for system tray integration)\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd OctoBar\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Create a placeholder icon:\n   - Replace `src/renderer/assets/icon.png` with a 16x16 or 32x32 PNG icon\n   - The app will fallback to a default icon if none is provided\n\n### Development\n\n#### macOS/Linux\n1. Start the development server:\n```bash\nnpm run dev\n```\n\n#### Windows\n1. Start the development server using the Windows script:\n```batch\nscripts\\dev.bat\n```\n\nOr manually:\n```bash\nnpm run dev\n```\n\nThis will:\n- Start the Vite dev server for the React app\n- Compile the TypeScript main process\n- Launch the Electron app\n\n2. The app will appear in your menu bar (macOS) or system tray (Windows) with a tray icon\n3. **macOS**: Click the icon to open the dropdown with GitHub notifications\n4. **Windows**: Left-click to open notifications, right-click for context menu\n\n### Building\n\n1. Build for production:\n```bash\nnpm run build\n```\n\n2. Create distributable:\n\n**For current platform:**\n```bash\nnpm run dist\n```\n\n**For Windows specifically:**\n```bash\nnpm run dist:win\n```\n\n**For macOS specifically:**\n```bash\nnpm run dist:mac\n```\n\nThis will create platform-specific installers:\n- **Windows**: Creates an NSIS installer (`.exe`) in the `release` folder\n- **macOS**: Creates a DMG file in the `release` folder\n\n## Automated Builds \u0026 Releases\n\nOctoBar uses **semantic-release** with **Conventional Commits** for fully automated versioning and releasing:\n\n### 🚀 Semantic Release System\n- **Industry Standard**: Uses the proven `semantic-release` tool\n- **Conventional Commits**: Automatically determines version increments based on commit messages\n- **Automatic Versioning**: Uses semantic versioning (e.g., v1.0.0, v1.1.0, v2.0.0)\n- **Multi-platform**: Builds for both macOS and Windows\n- **Changelog Generation**: Automatically generates changelogs and release notes\n\n### 📝 Conventional Commit Types\nSemantic-release analyzes commit messages to determine version increments:\n\n- **`feat:`** → Minor version bump (1.0.0 → 1.1.0)\n- **`fix:`** → Patch version bump (1.0.0 → 1.0.1)\n- **`perf:`** → Patch version bump (1.0.0 → 1.0.1)\n- **`refactor:`** → Patch version bump (1.0.0 → 1.0.1)\n- **`feat!:`** or **`fix!:`** → Major version bump (1.0.0 → 2.0.0)\n- **`docs:`, `style:`, `test:`, `chore:`** → No version bump (unless breaking)\n\n### 🎯 Release Behavior\n\n#### Pre-Releases (Current)\n- **Trigger**: Push to `main` branch with conventional commits\n- **Format**: `v1.0.0-alpha.1`, `v1.1.0-alpha.2`, `v2.0.0-alpha.1`\n- **Type**: Pre-release for testing and development\n- **Artifacts**: macOS DMG/zip and Windows EXE/zip\n- **Note**: All releases are currently alpha pre-releases until ready for stable v1.0.0\n\n#### Pull Request Builds\n- **Trigger**: Any pull request to `main`\n- **Purpose**: Build validation and testing\n- **Artifacts**: Available for 7 days for testing\n- **No Release**: No releases created for PRs\n\n### 🔧 Workflow Features\n- **Semantic Versioning**: Automatic version calculation\n- **Changelog Generation**: Auto-generated from commit messages\n- **Git Tagging**: Automatic git tag creation\n- **GitHub Releases**: Automatic GitHub release creation\n- **Multi-platform Builds**: macOS and Windows support\n- **Artifact Management**: 90-day retention for releases\n\n### 📋 Configuration Files\n- `.github/workflows/release.yml` - Main workflow using semantic-release\n- `.releaserc.js` - Semantic-release configuration (JavaScript format)\n- `.npmrc` - NPM authentication configuration\n\n### 💡 How to Use Conventional Commits\n\nTo trigger automatic releases, use conventional commit messages:\n\n```bash\n# Minor version bump (1.0.0 → 1.1.0)\ngit commit -m \"feat: add notification sound settings\"\ngit commit -m \"feat(ui): implement dark mode toggle\"\n\n# Patch version bump (1.0.0 → 1.0.1)\ngit commit -m \"fix: resolve white screen issue in packaged app\"\ngit commit -m \"fix(notifications): handle permission denied gracefully\"\ngit commit -m \"perf: optimize background refresh interval\"\ngit commit -m \"refactor: simplify notification service\"\n\n# Major version bump (1.0.0 → 2.0.0)\ngit commit -m \"feat!: redesign notification system with breaking changes\"\ngit commit -m \"fix!: change API structure (breaking change)\"\n\n# No version bump (documentation, tests, etc.)\ngit commit -m \"docs: update README with new features\"\ngit commit -m \"test: add unit tests for notification service\"\ngit commit -m \"chore: update dependencies\"\n```\n\n### 🎯 Examples\n\n- **`feat: add desktop notifications`** → Creates v1.1.0-alpha.1 (minor bump)\n- **`fix: resolve packaging issue`** → Creates v1.0.1-alpha.1 (patch bump)\n- **`feat!: redesign UI with breaking changes`** → Creates v2.0.0-alpha.1 (major bump)\n- **`docs: update README`** → No release (no version bump)\n\n### 🚀 Creating Your First Stable Release\n\nWhen you're ready for a stable v1.0.0 release, simply update the `.releaserc.js` file:\n\n```javascript\nmodule.exports = {\n  branches: [\n    'main'  // Remove the prerelease configuration\n  ],\n  // ... rest of config\n};\n```\n\nThis will switch from pre-releases to stable releases.\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"Not allowed to load local resource\" Error\nIf you see an error like:\n```\nNot allowed to load local resource: file:///Applications/OctoBar.app/Contents/Resources/app.asar/renderer/index.html\n```\n\nThis indicates a file path issue in the packaged app. The fix has been implemented in the main process to correctly locate the renderer files.\n\n#### Debugging Packaged App Structure\nUse the debug script to check the file structure in a packaged app:\n```bash\nnode scripts/check-packaged-structure.js\n```\n\n#### Development vs Production\n- **Development**: App loads from Vite dev server (`http://localhost:3001`)\n- **Production**: App loads from packaged files (`dist/renderer/index.html`)\n\n#### Console Logs\nThe app includes extensive console logging to help debug issues:\n- Main process logs appear in the terminal/console\n- Renderer process logs appear in the browser dev tools\n- Debug mode provides additional logging and testing tools\n\n## Current Implementation Status\n\n### ✅ Completed\n- Electron main process with tray app and popup window\n- Cross-platform support (macOS and Windows)\n- React frontend with component structure\n- GitHub API integration with real notifications\n- Personal Access Token setup wizard\n- Secure PAT storage using system keychain (macOS Keychain/Windows Credential Manager)\n- TypeScript type definitions\n- Native macOS-style UI components\n- Quick action buttons (mark as read, open in browser)\n- Filter system (Work, Personal, All)\n- Responsive design with proper styling\n- Real-time notification loading\n- Error handling and retry functionality\n- Notification grouping by repository\n- Mark as read functionality (individual and bulk)\n- Refresh notifications functionality\n- **Background refresh system** with configurable intervals (1-60 minutes)\n- **Desktop notifications** with native Electron notification API\n- **Sound notifications** with custom audio generation\n- **Settings management** with persistent storage\n- **Theme system** (light, dark, system)\n- **Advanced filtering** by organizations and repositories\n- **Debug mode** with comprehensive testing tools\n- **Notification permission handling** with user-friendly UI\n\n### 🔄 In Progress\n- Filter implementation (Work/Personal views need backend logic)\n- Mute thread functionality (UI ready, API integration pending)\n- Star thread functionality (UI ready, API integration pending)\n\n### 📋 TODO\n- Implement Work/Personal filter logic based on organization/repository\n- Add mute thread API integration\n- Add star thread API integration\n- Implement macOS Focus mode detection\n- Add keyboard shortcuts\n- Add notification search functionality\n- Add notification history/archive\n- Add notification categories and custom filters\n\n## GitHub Integration\n\nThe app now integrates with the real GitHub API:\n\n- **Authentication**: Uses Personal Access Token (PAT) stored securely in system keychain\n- **API Endpoints**: Fetches notifications from GitHub Notifications API\n- **Real-time Data**: Loads actual unread notifications from your GitHub account\n- **Smart URL Building**: Automatically generates proper GitHub URLs for different notification types\n- **Rate Limiting**: Respects GitHub API rate limits\n- **Error Handling**: Graceful handling of API errors with user-friendly messages\n\n## Setup Wizard\n\nNew users are guided through a setup process:\n\n1. **Welcome**: Introduction to the app\n2. **GitHub Token**: Enter and validate your Personal Access Token\n3. **Filters**: Configure notification filters (Work/Personal)\n4. **Completion**: Setup complete, ready to use\n\nThe wizard validates your PAT and ensures it has the necessary permissions for notifications.\n\n## Notification System\n\nOctoBar includes a comprehensive notification system with both visual and audio alerts:\n\n### Desktop Notifications\n- **Native Integration**: Uses Electron's native notification API for proper desktop integration\n- **Click to Focus**: Clicking notifications brings the app to focus\n- **Auto-dismiss**: Notifications automatically close after 5 seconds\n- **Permission Handling**: Automatic permission requests with user-friendly UI\n\n### Sound Notifications\n- **Custom Audio**: Generates custom notification sounds using Web Audio API\n- **No External Files**: Sounds are generated programmatically, no audio files required\n- **Configurable**: Can be enabled/disabled in settings\n\n### Background Refresh\n- **Automatic Updates**: Fetches new notifications at configurable intervals\n- **Smart Detection**: Only shows notifications for new notifications (count increases)\n- **Configurable Intervals**: Choose from 1, 5, 15, 30, or 60 minutes\n- **Settings Integration**: Refresh interval is saved and restored between sessions\n\n### Settings Management\n- **Persistent Storage**: All settings are saved securely and restored on app restart\n- **Real-time Updates**: Settings changes take effect immediately\n- **Theme Support**: Light, dark, and system theme modes\n- **Filter Management**: Advanced filtering by organizations and repositories\n\n## Debug Mode\n\nOctoBar includes a hidden debug mode for developers and power users:\n\n### Activation\n1. Open the Settings modal\n2. Click the \"Settings\" title 5 times\n3. Debug mode will activate (title will turn orange and show a wrench emoji)\n\n### Debug Tools\n- **Notification Testing**: Test different types of notifications\n- **Force Notifications**: Bypass settings to test notification functionality\n- **Permission Checking**: Check and request notification permissions\n- **Settings Logging**: View current settings and notification status\n- **Manual Refresh**: Force manual notification refresh\n- **Comprehensive Logging**: Detailed console output for troubleshooting\n\n### Use Cases\n- **Development**: Test notification functionality during development\n- **Troubleshooting**: Diagnose notification issues\n- **User Testing**: Verify notification functionality works correctly\n- **Demo Purposes**: Show notification features to others\n\n## Secure Storage\n\n### Cross-Platform Credential Storage\n\nOctoBar uses the `keytar` library to securely store your GitHub Personal Access Token (PAT) in the operating system's native credential store:\n\n- **macOS**: Stored in macOS Keychain (`/Applications/Utilities/Keychain Access.app`)\n- **Windows**: Stored in Windows Credential Manager (`Control Panel \u003e Credential Manager \u003e Windows Credentials`)\n- **Linux**: Stored in libsecret/gnome-keyring\n\n#### Windows Credential Manager Details\n\nOn Windows, your PAT will appear in Credential Manager as:\n- **Internet or network address**: `OctoBar`\n- **User name**: `GitHub_PAT`\n- **Password**: Your encrypted GitHub Personal Access Token\n\nYou can view/manage this credential by:\n1. Opening **Control Panel** → **Credential Manager**\n2. Clicking **Windows Credentials**\n3. Looking for the **OctoBar** entry\n\nThe credential is encrypted using Windows' built-in encryption and is only accessible to your user account.\n\n## Architecture\n\n### Main Process (Electron)\n- Manages the system tray and popup window with cross-platform support\n- Handles app lifecycle and window management\n- Provides secure IPC communication via preload script\n- Manages secure storage of GitHub PAT using keytar (supports both macOS Keychain and Windows Credential Manager)\n- **Native Notifications**: Handles desktop notifications using Electron's Notification API\n- **Settings Management**: Stores and retrieves application settings securely\n\n### Renderer Process (React)\n- Renders the notification UI with theme support\n- Manages component state and user interactions\n- Communicates with main process via electronAPI\n- Handles GitHub API calls through GitHubService\n- **Background Refresh**: Automatic notification updates using custom hooks\n- **Notification Service**: Manages sound and desktop notifications\n- **Settings UI**: Comprehensive settings management with real-time updates\n\n### Data Flow\n1. **Background Refresh**: useBackgroundRefresh hook triggers periodic updates\n2. **GitHubService**: Fetches real notifications from GitHub API\n3. **NotificationService**: Detects new notifications and triggers alerts\n4. **App Component**: Manages global state and notification grouping\n5. **Components**: Render notifications with proper grouping and styling\n6. **User Actions**: Trigger service methods for real API calls\n7. **UI Updates**: Reflect real-time state changes and theme updates\n\n## Styling\n\nThe app uses:\n- CSS custom properties for consistent theming\n- Backdrop filters for modern aesthetics (macOS-style)\n- Responsive design principles\n- Cross-platform color palette with native system integration\n- Smooth transitions and hover effects\n- Professional setup wizard styling with animations\n\n## Contributing\n\n1. Follow the existing code structure and patterns\n2. Use TypeScript strict mode\n3. Implement proper error handling\n4. Add tests for new functionality\n5. Update documentation as needed\n\n## License\n\nThis project uses a **dual licensing model** - see the [LICENSE](LICENSE) file for details.\n\n### Non-Commercial Use (Free)\n\n- ✅ **Personal use** - Use for personal projects\n- ✅ **Educational use** - Use in educational settings\n- ✅ **Open source projects** - Use in open source projects\n- ✅ **Modification** - Modify and adapt the code\n- ✅ **Distribution** - Share and distribute for non-commercial purposes\n\n### Commercial Use (Paid License Required)\n\n- 💰 **Commercial products** - Use in commercial software\n- 💰 **Business use** - Use by commercial entities\n- 💰 **Profit-generating activities** - Use for profit\n- 💰 **Commercial development** - Use in commercial software development\n\n### What this means:\n\n- 🆓 **Free for non-commercial use** - Students, hobbyists, open source projects\n- 💰 **Paid license for commercial use** - Businesses must purchase a commercial license\n\n### Commercial Licensing\n\nFor commercial use, please contact us for licensing terms and pricing:\n- **Email**: [tidusjar@gmail.com]\n- **GitHub**: [tidusjar]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidusjar%2Foctobar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftidusjar%2Foctobar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidusjar%2Foctobar/lists"}