{"id":29193682,"url":"https://github.com/hichipli/citebar","last_synced_at":"2026-03-08T17:07:48.635Z","repository":{"id":300811117,"uuid":"1007217328","full_name":"hichipli/CiteBar","owner":"hichipli","description":"Real-time Google Scholar citation tracker in your macOS menu bar.","archived":false,"fork":false,"pushed_at":"2025-06-26T05:43:46.000Z","size":244,"stargazers_count":133,"open_issues_count":3,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-01-19T22:55:45.827Z","etag":null,"topics":["academic-tools","citation-tracker","google-scholar","macos","makefile","menu-bar-app","open-science","research-tools","sparkle","swift","swiftsoup","swiftui"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hichipli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-06-23T16:34:47.000Z","updated_at":"2025-12-03T12:13:23.000Z","dependencies_parsed_at":"2025-06-23T18:45:06.138Z","dependency_job_id":"8c145b0c-8cd7-4d7f-99d7-14ad7c1239a0","html_url":"https://github.com/hichipli/CiteBar","commit_stats":null,"previous_names":["hichipli/citebar"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hichipli/CiteBar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hichipli%2FCiteBar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hichipli%2FCiteBar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hichipli%2FCiteBar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hichipli%2FCiteBar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hichipli","download_url":"https://codeload.github.com/hichipli/CiteBar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hichipli%2FCiteBar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28633757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["academic-tools","citation-tracker","google-scholar","macos","makefile","menu-bar-app","open-science","research-tools","sparkle","swift","swiftsoup","swiftui"],"created_at":"2025-07-02T03:06:54.481Z","updated_at":"2026-03-08T17:07:48.628Z","avatar_url":"https://github.com/hichipli.png","language":"HTML","readme":"# CiteBar\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"Assets.xcassets/AppIcon.appiconset/256.png\" alt=\"CiteBar Logo\" width=\"128\" height=\"128\"\u003e\n  \n  **Track Your Academic Impact in Real-Time**\n  \n  A elegant macOS menu bar application that keeps your Google Scholar citation metrics at your fingertips.\n\n  [![Latest Release](https://img.shields.io/github/v/release/hichipli/CiteBar?style=flat-square)](https://github.com/hichipli/CiteBar/releases)\n  [![macOS](https://img.shields.io/badge/macOS-13.0+-blue?style=flat-square)](https://www.apple.com/macos/)\n  [![Swift](https://img.shields.io/badge/Swift-6.0-orange?style=flat-square)](https://swift.org)\n  [![License](https://img.shields.io/github/license/hichipli/CiteBar?style=flat-square)](LICENSE)\n  [![Downloads](https://img.shields.io/github/downloads/hichipli/CiteBar/total?style=flat-square)](https://github.com/hichipli/CiteBar/releases)\n\n\u003c/div\u003e\n\n---\n\n## Why CiteBar?\n\nBecause refreshing your Google Scholar profile every 20 minutes isn't productive research. CiteBar transforms citation tracking from an obsessive browser tab into a elegant, unobtrusive companion that respects both your attention and Google's servers.\n\n**Perfect for:** Researchers tracking paper impact, department heads monitoring team metrics, PhD students celebrating their first citations, and anyone who's ever wondered \"Did my h-index just go up?\"\n\n## Quick Start\n\n### For Most Users (Recommended)\n\n**Just want to use CiteBar?** Skip the technical stuff and get started in 60 seconds:\n\n1. **Download** the latest release:\n   - **[Click here to download CiteBar](https://github.com/hichipli/CiteBar/releases)**\n   - Choose the latest `CiteBar-x.x.x-universal-[date].dmg` file (works on Apple Silicon + Intel, no chip-specific download needed)\n   - Double-click the DMG file when downloaded\n   - Drag CiteBar.app to the Applications folder\n\n2. **Handle macOS security** (because we're not paying Apple $99/year... yet):\n   \n   **Method 1 - Using Terminal (Quickest):**\n   - Press `Cmd + Space` to open Spotlight search\n   - Type \"Terminal\" and press Enter\n   - Copy and paste this command, then press Enter:\n   ```bash\n   xattr -cr /Applications/CiteBar.app\n   ```\n   \n   **Method 2 - Through System Settings (No Terminal Required):**\n   - Try to run CiteBar from Applications - it will show a security warning\n   - Go to **System Settings** (or **System Preferences** on older macOS)\n   - Click **Privacy \u0026 Security** \n   - Scroll down to the **Security** section\n   - You'll see a message about CiteBar being blocked\n   - Click **\"Open Anyway\"** button next to the message\n\n\u003e **Legacy Upgrade Note:** If you're on `1.3.x` or `1.4.1`, you may need one manual upgrade first.  \n\u003e Install the latest DMG from [Releases](https://github.com/hichipli/CiteBar/releases/latest), and after you're on `1.4.4+`, in-app automatic updates should work normally.\n\n3. **Set up your profile**:\n   - Click the CiteBar icon in menu bar\n   - Add your Google Scholar ID (from your profile URL)\n   - Choose refresh interval (24 hours recommended)\n   - Done!\n\n**Having Issues?** Check our [troubleshooting guide](DISTRIBUTION.md) for common macOS security dialogs.\n\n### For Developers \u0026 Tinkerers\n\nWant to build from source or contribute? You're in the right place:\n\n```bash\n# Clone and build\ngit clone https://github.com/hichipli/CiteBar.git\ncd CiteBar\nmake build \u0026\u0026 make run\n\n# Or install to Applications\nmake install\n```\n\n**Requirements:** macOS 13.0+, Xcode Command Line Tools (`xcode-select --install`)\n\n## Features That Actually Matter\n\n**Real-time Citation Tracking**\n- Live citation counts in your menu bar\n- Historical trend tracking with growth indicators\n- Configurable refresh intervals (1 hour to 2 days)\n\n**Multi-Profile Management**\n- Track multiple scholars (yourself, collaborators, competitors)\n- Drag-and-drop profile reordering\n- One-click profile switching and prioritization\n\n**Respectful \u0026 Reliable**\n- Built-in rate limiting to respect Google's servers\n- Robust error handling (won't crash when Google changes their HTML)\n- Automatic updates via Sparkle framework\n\n**Privacy-First Design**\n- All data stored locally on your Mac\n- No telemetry, no cloud sync, no tracking\n- Only accesses publicly available Scholar data\n\n**Native macOS Integration**\n- Professional SF Symbols icons (no emoji clutter)\n- Native SwiftUI settings interface\n- Auto-launch support with modern SMAppService API\n\n## Architecture Deep Dive\n\nFor the technically curious, here's what makes CiteBar tick:\n\n### Core Design Philosophy\n\nCiteBar follows a clean, actor-based architecture that prioritizes thread safety and separation of concerns:\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   AppDelegate   │────│  MenuBarManager  │────│ CitationManager │\n│   (@MainActor)  │    │                  │    │                 │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n         │                        │                        │\n         │                        │                        │\n         ▼                        ▼                        ▼\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│ SettingsManager │    │  StorageManager  │    │   SwiftSoup     │\n│ (ObservableObj) │    │     (Actor)      │    │   (HTML Parse)  │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Key Technical Decisions\n\n**Actor Isolation for Data Safety**\n```swift\nactor StorageManager {\n    // Thread-safe citation history storage\n    // Atomic file writes prevent data corruption\n}\n```\n\n**MainActor for UI Consistency**\n```swift\n@MainActor class AppDelegate: NSObject, NSApplicationDelegate {\n    // All UI operations guaranteed on main thread\n}\n```\n\n**Rate Limiting Strategy**\n- 2-second delays between individual requests\n- Configurable refresh intervals (user-controlled)\n- Exponential backoff on errors\n- Respectful User-Agent headers\n\n### Google Scholar Integration\n\nCiteBar parses public Google Scholar profiles using a robust HTML extraction strategy:\n\n```swift\n// Multiple CSS selectors for reliability\nlet selectors = [\"td.gsc_rsb_std\", \".gsc_rsb_std\", \"td[data-testid='citation-count']\"]\n```\n\n**Why This Approach?**\n- Google Scholar has no official API\n- Public profiles are meant to be accessed\n- We add appropriate delays and respect robots.txt\n- Only scrapes publicly visible citation counts\n\n### Data Flow \u0026 Persistence\n\n1. **App Launch**: Load historical data immediately (prevents \"No data\" flash)\n2. **Background Updates**: Fetch fresh data asynchronously\n3. **Storage**: JSON files in `~/Library/Application Support/CiteBar/`\n4. **Threading**: All network on background, all UI on main thread\n\n```\nSettings: ~/Library/Application Support/CiteBar/settings.json\nHistory:  ~/Library/Application Support/CiteBar/citation_history.json\n```\n\n## Development Workflow\n\n### Build System\n\nWe use a Makefile for consistency across environments:\n\n```bash\nmake build      # Release build (.build/apple/Products/Release/CiteBar)\nmake debug      # Debug build with logging\nmake test       # Run unit tests\nmake xcode      # Open Xcode project\nmake clean      # Clean build artifacts\nmake install    # Install to /Applications\nmake package    # Create distribution DMG\n```\n\n### Code Organization\n\n```\nSources/CiteBar/\n├── main.swift              # Entry point\n├── AppDelegate.swift       # App lifecycle, @MainActor\n├── MenuBarManager.swift    # NSStatusBar integration\n├── CitationManager.swift   # Google Scholar scraping\n├── SettingsManager.swift   # User preferences, ObservableObject\n├── StorageManager.swift    # Data persistence, Actor\n├── Models.swift           # Data structures, Codable\n└── SettingsView.swift     # SwiftUI settings interface\n```\n\n### Testing Philosophy\n\n```bash\n# Run the test suite\nmake test\n\n# Or directly\nswift test\n```\n\nWe test the parts that matter:\n- Google Scholar HTML parsing (with mock responses)\n- Data persistence and migration\n- Rate limiting logic\n- Error handling scenarios\n\n### Release Process\n\nCiteBar uses GitHub Actions for automated releases:\n\n1. Configure Sparkle signing once (required for auto-update validation):\n   - Repository variable or secret: `SPARKLE_PUBLIC_ED_KEY`\n   - Repository secret: `SPARKLE_PRIVATE_KEY`\n2. Tag a version: `git tag v1.x.x \u0026\u0026 git push --tags`\n3. GitHub Actions builds DMG with version + architecture\n4. Workflow signs the DMG with EdDSA and generates `appcast.xml`\n5. Users get automatic update notifications\n\nMaintainers: see [RELEASING.md](RELEASING.md) for full release + signing workflow.\n\n## Contributing\n\nWe love contributions! Whether you're fixing bugs, adding features, or improving docs:\n\n### Getting Started\n\n```bash\ngit clone https://github.com/hichipli/CiteBar.git\ncd CiteBar\nmake xcode  # Opens Xcode project\n```\n\n### Code Style\n\n- Follow Swift API Design Guidelines\n- Use SwiftFormat (configuration in repo)\n- Prefer explicit types for clarity\n- Document public APIs with `///`\n- No force unwrapping without explicit safety comments\n\n### What We're Looking For\n\n**High Impact, Low Effort:**\n- UI/UX improvements\n- Better error messages\n- Performance optimizations\n- Additional citation metrics\n\n**Future Vision:**\n- Desktop widgets\n- Citation trend visualizations\n- Export functionality\n- Dark mode support\n\n## Privacy \u0026 Ethics\n\nWe take research ethics seriously:\n\n**Data Handling**\n- Only accesses publicly available Google Scholar data\n- No personal information stored or transmitted\n- All data remains on your local machine\n- No telemetry or usage tracking\n\n**Rate Limiting**\n- Built-in delays respect Google's servers\n- Default 24-hour refresh intervals\n- Exponential backoff on errors\n- Professional User-Agent headers\n\n**Open Source Transparency**\n- Full source code available for audit\n- No hidden network requests\n- Clear documentation of data flows\n- MIT license for maximum freedom\n\n## Support \u0026 Community\n\n**Found a Bug?** Open an [issue](https://github.com/hichipli/CiteBar/issues) with:\n- macOS version and CiteBar version\n- Steps to reproduce\n- Error messages or screenshots\n\n**Feature Request?** We love ideas! Especially ones that come with pull requests.\n\n**Installation Issues?** Check [DISTRIBUTION.md](DISTRIBUTION.md) for macOS security solutions.\n\n**Development Questions?** Check [SETUP.md](SETUP.md) for detailed development instructions.\n\n## Technical Specifications\n\n**System Requirements:**\n- macOS 13.0 (Ventura) or later\n- Apple Silicon or Intel Mac\n- 50MB free disk space\n\n**Dependencies:**\n- SwiftSoup (HTML parsing)\n- Sparkle (automatic updates)\n- Foundation, AppKit, SwiftUI (system frameworks)\n\n**Performance:**\n- Memory usage: ~15-25MB\n- CPU usage: Near zero when idle\n- Network: Minimal, user-configurable intervals\n\n## License\n\nMIT License - Use CiteBar however you want, build amazing things on top of it, make money with it. Just don't blame us if Google changes their HTML structure again.\n\nSee [LICENSE](LICENSE) for the boring legal details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with care for the academic community**\n\n[Download Latest Release](https://github.com/hichipli/CiteBar/releases) • [Report Issues](https://github.com/hichipli/CiteBar/issues) • [Contribute](CONTRIBUTING.md)\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhichipli%2Fcitebar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhichipli%2Fcitebar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhichipli%2Fcitebar/lists"}