https://github.com/hichipli/citebar
Real-time Google Scholar citation tracker in your macOS menu bar.
https://github.com/hichipli/citebar
academic-tools citation-tracker google-scholar macos makefile menu-bar-app open-science research-tools sparkle swift swiftsoup swiftui
Last synced: about 2 months ago
JSON representation
Real-time Google Scholar citation tracker in your macOS menu bar.
- Host: GitHub
- URL: https://github.com/hichipli/citebar
- Owner: hichipli
- License: mit
- Created: 2025-06-23T16:34:47.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-06-26T05:43:46.000Z (10 months ago)
- Last Synced: 2026-01-19T22:55:45.827Z (3 months ago)
- Topics: academic-tools, citation-tracker, google-scholar, macos, makefile, menu-bar-app, open-science, research-tools, sparkle, swift, swiftsoup, swiftui
- Language: HTML
- Homepage:
- Size: 238 KB
- Stars: 133
- Watchers: 8
- Forks: 14
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# CiteBar
**Track Your Academic Impact in Real-Time**
A elegant macOS menu bar application that keeps your Google Scholar citation metrics at your fingertips.
[](https://github.com/hichipli/CiteBar/releases)
[](https://www.apple.com/macos/)
[](https://swift.org)
[](LICENSE)
[](https://github.com/hichipli/CiteBar/releases)
---
## Why CiteBar?
Because 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.
**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?"
## Quick Start
### For Most Users (Recommended)
**Just want to use CiteBar?** Skip the technical stuff and get started in 60 seconds:
1. **Download** the latest release:
- **[Click here to download CiteBar](https://github.com/hichipli/CiteBar/releases)**
- Choose the latest `CiteBar-x.x.x-universal-[date].dmg` file (works on Apple Silicon + Intel, no chip-specific download needed)
- Double-click the DMG file when downloaded
- Drag CiteBar.app to the Applications folder
2. **Handle macOS security** (because we're not paying Apple $99/year... yet):
**Method 1 - Using Terminal (Quickest):**
- Press `Cmd + Space` to open Spotlight search
- Type "Terminal" and press Enter
- Copy and paste this command, then press Enter:
```bash
xattr -cr /Applications/CiteBar.app
```
**Method 2 - Through System Settings (No Terminal Required):**
- Try to run CiteBar from Applications - it will show a security warning
- Go to **System Settings** (or **System Preferences** on older macOS)
- Click **Privacy & Security**
- Scroll down to the **Security** section
- You'll see a message about CiteBar being blocked
- Click **"Open Anyway"** button next to the message
> **Legacy Upgrade Note:** If you're on `1.3.x` or `1.4.1`, you may need one manual upgrade first.
> 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.
3. **Set up your profile**:
- Click the CiteBar icon in menu bar
- Add your Google Scholar ID (from your profile URL)
- Choose refresh interval (24 hours recommended)
- Done!
**Having Issues?** Check our [troubleshooting guide](DISTRIBUTION.md) for common macOS security dialogs.
### For Developers & Tinkerers
Want to build from source or contribute? You're in the right place:
```bash
# Clone and build
git clone https://github.com/hichipli/CiteBar.git
cd CiteBar
make build && make run
# Or install to Applications
make install
```
**Requirements:** macOS 13.0+, Xcode Command Line Tools (`xcode-select --install`)
## Features That Actually Matter
**Real-time Citation Tracking**
- Live citation counts in your menu bar
- Historical trend tracking with growth indicators
- Configurable refresh intervals (1 hour to 2 days)
**Multi-Profile Management**
- Track multiple scholars (yourself, collaborators, competitors)
- Drag-and-drop profile reordering
- One-click profile switching and prioritization
**Respectful & Reliable**
- Built-in rate limiting to respect Google's servers
- Robust error handling (won't crash when Google changes their HTML)
- Automatic updates via Sparkle framework
**Privacy-First Design**
- All data stored locally on your Mac
- No telemetry, no cloud sync, no tracking
- Only accesses publicly available Scholar data
**Native macOS Integration**
- Professional SF Symbols icons (no emoji clutter)
- Native SwiftUI settings interface
- Auto-launch support with modern SMAppService API
## Architecture Deep Dive
For the technically curious, here's what makes CiteBar tick:
### Core Design Philosophy
CiteBar follows a clean, actor-based architecture that prioritizes thread safety and separation of concerns:
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ AppDelegate │────│ MenuBarManager │────│ CitationManager │
│ (@MainActor) │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ SettingsManager │ │ StorageManager │ │ SwiftSoup │
│ (ObservableObj) │ │ (Actor) │ │ (HTML Parse) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
### Key Technical Decisions
**Actor Isolation for Data Safety**
```swift
actor StorageManager {
// Thread-safe citation history storage
// Atomic file writes prevent data corruption
}
```
**MainActor for UI Consistency**
```swift
@MainActor class AppDelegate: NSObject, NSApplicationDelegate {
// All UI operations guaranteed on main thread
}
```
**Rate Limiting Strategy**
- 2-second delays between individual requests
- Configurable refresh intervals (user-controlled)
- Exponential backoff on errors
- Respectful User-Agent headers
### Google Scholar Integration
CiteBar parses public Google Scholar profiles using a robust HTML extraction strategy:
```swift
// Multiple CSS selectors for reliability
let selectors = ["td.gsc_rsb_std", ".gsc_rsb_std", "td[data-testid='citation-count']"]
```
**Why This Approach?**
- Google Scholar has no official API
- Public profiles are meant to be accessed
- We add appropriate delays and respect robots.txt
- Only scrapes publicly visible citation counts
### Data Flow & Persistence
1. **App Launch**: Load historical data immediately (prevents "No data" flash)
2. **Background Updates**: Fetch fresh data asynchronously
3. **Storage**: JSON files in `~/Library/Application Support/CiteBar/`
4. **Threading**: All network on background, all UI on main thread
```
Settings: ~/Library/Application Support/CiteBar/settings.json
History: ~/Library/Application Support/CiteBar/citation_history.json
```
## Development Workflow
### Build System
We use a Makefile for consistency across environments:
```bash
make build # Release build (.build/apple/Products/Release/CiteBar)
make debug # Debug build with logging
make test # Run unit tests
make xcode # Open Xcode project
make clean # Clean build artifacts
make install # Install to /Applications
make package # Create distribution DMG
```
### Code Organization
```
Sources/CiteBar/
├── main.swift # Entry point
├── AppDelegate.swift # App lifecycle, @MainActor
├── MenuBarManager.swift # NSStatusBar integration
├── CitationManager.swift # Google Scholar scraping
├── SettingsManager.swift # User preferences, ObservableObject
├── StorageManager.swift # Data persistence, Actor
├── Models.swift # Data structures, Codable
└── SettingsView.swift # SwiftUI settings interface
```
### Testing Philosophy
```bash
# Run the test suite
make test
# Or directly
swift test
```
We test the parts that matter:
- Google Scholar HTML parsing (with mock responses)
- Data persistence and migration
- Rate limiting logic
- Error handling scenarios
### Release Process
CiteBar uses GitHub Actions for automated releases:
1. Configure Sparkle signing once (required for auto-update validation):
- Repository variable or secret: `SPARKLE_PUBLIC_ED_KEY`
- Repository secret: `SPARKLE_PRIVATE_KEY`
2. Tag a version: `git tag v1.x.x && git push --tags`
3. GitHub Actions builds DMG with version + architecture
4. Workflow signs the DMG with EdDSA and generates `appcast.xml`
5. Users get automatic update notifications
Maintainers: see [RELEASING.md](RELEASING.md) for full release + signing workflow.
## Contributing
We love contributions! Whether you're fixing bugs, adding features, or improving docs:
### Getting Started
```bash
git clone https://github.com/hichipli/CiteBar.git
cd CiteBar
make xcode # Opens Xcode project
```
### Code Style
- Follow Swift API Design Guidelines
- Use SwiftFormat (configuration in repo)
- Prefer explicit types for clarity
- Document public APIs with `///`
- No force unwrapping without explicit safety comments
### What We're Looking For
**High Impact, Low Effort:**
- UI/UX improvements
- Better error messages
- Performance optimizations
- Additional citation metrics
**Future Vision:**
- Desktop widgets
- Citation trend visualizations
- Export functionality
- Dark mode support
## Privacy & Ethics
We take research ethics seriously:
**Data Handling**
- Only accesses publicly available Google Scholar data
- No personal information stored or transmitted
- All data remains on your local machine
- No telemetry or usage tracking
**Rate Limiting**
- Built-in delays respect Google's servers
- Default 24-hour refresh intervals
- Exponential backoff on errors
- Professional User-Agent headers
**Open Source Transparency**
- Full source code available for audit
- No hidden network requests
- Clear documentation of data flows
- MIT license for maximum freedom
## Support & Community
**Found a Bug?** Open an [issue](https://github.com/hichipli/CiteBar/issues) with:
- macOS version and CiteBar version
- Steps to reproduce
- Error messages or screenshots
**Feature Request?** We love ideas! Especially ones that come with pull requests.
**Installation Issues?** Check [DISTRIBUTION.md](DISTRIBUTION.md) for macOS security solutions.
**Development Questions?** Check [SETUP.md](SETUP.md) for detailed development instructions.
## Technical Specifications
**System Requirements:**
- macOS 13.0 (Ventura) or later
- Apple Silicon or Intel Mac
- 50MB free disk space
**Dependencies:**
- SwiftSoup (HTML parsing)
- Sparkle (automatic updates)
- Foundation, AppKit, SwiftUI (system frameworks)
**Performance:**
- Memory usage: ~15-25MB
- CPU usage: Near zero when idle
- Network: Minimal, user-configurable intervals
## License
MIT 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.
See [LICENSE](LICENSE) for the boring legal details.
---
**Built with care for the academic community**
[Download Latest Release](https://github.com/hichipli/CiteBar/releases) • [Report Issues](https://github.com/hichipli/CiteBar/issues) • [Contribute](CONTRIBUTING.md)