Peek

A modern, minimal macOS menu-bar app that keeps a quiet eye on your GitHub pull requests.

Peek lives in your menu bar, polls GitHub via the gh CLI, and tells you when a PR needs your attention — silently, with native notifications and a glassmorphic dropdown panel.

Features

• Glanceable count badge in the menu bar — number of PRs that actually need you (review requested or ready to merge).
• Sectioned dropdown with glass / vibrancy background:
  • Recent activity — anything updated in the last hour.
  • Needs your review — review requested from you, oldest first (FIFO fairness).
  • Ready to merge — your PRs that are approved, green, and mergeable.
  • Your open PRs — everything you've authored that's still open.
  • Ignored — collapsible list of muted PRs.
• Native notifications with click-to-open. Banners only — no sound, no nag.
• Smart change detection between polls:
  • new review requests
  • re-review requested (new commits after you approved)
  • your PR approved / changes requested / ready to merge
  • CI failed / recovered
  • merge conflicts
  • draft → ready transitions
• Adaptive polling: 60 s when idle, 10 s when the panel is open or activity was recently detected (auto-falls back after 3 min of quiet).
• Search-as-you-type — just start typing in the open panel to filter by title, repo, author (@alice), or PR number (#123).
• Keyboard accessible — Tab/Shift-Tab to navigate, Return to open, Esc to clear search, ⌘R to refresh, ⌘Q to quit.
• Ignore / unignore PRs via right-click or hover button. Persists across launches.
• No Dock icon, no menu bar app menu (LSUIElement), no windows.
• No webhook server required. Uses your existing gh auth.

Requirements

• macOS 14 (Sonoma) or later
• gh installed and authenticated (gh auth login)
• Xcode Command Line Tools (xcode-select --install) — full Xcode not required

Installation

Prebuilt binary

1. Download the latest Peek.zip from the Releases page.

2. Unzip and move Peek.app to /Applications.

3. Since the build is ad-hoc signed (no paid Apple Developer cert), macOS Gatekeeper will block it on first launch. Strip the quarantine flag once:

   xattr -dr com.apple.quarantine /Applications/Peek.app

4. Launch Peek.app. Look for the small ring icon in the menu bar.

5. Grant notification permission when prompted.

Build from source

git clone git@github.com:srijanmukherjee/peek.git
cd peek
./scripts/bundle.sh
open build/Peek.app

scripts/bundle.sh runs swift build -c release, wraps the executable into Peek.app with the right Info.plist, and ad-hoc codesigns it for local launches.

First-run setup

Peek shells out to the official GitHub CLI. If you don't already have it:

brew install gh
gh auth login

Pick the GitHub.com host and grant the default scopes. Peek inherits this token via gh api — it never reads your credentials directly.

Development

swift build              # debug build
swift run Peek           # run unbundled (notifications log to stdout)
swift test               # run unit tests (Swift Testing framework)
./scripts/bundle.sh      # produce build/Peek.app

Architecture notes

• Single GraphQL fetch via gh api graphql returns the involved-PR list with reviewDecision, mergeable, statusCheckRollup, per-reviewer states, and head commit OID in one round trip.
• Diff against persisted snapshots to emit ChangeEvents. First run is silent (seeding) so you don't get a ping for every existing PR.
• PRStore is an actor — concurrency-safe persistence in ~/Library/Application Support/Peek/state.json.
• Adaptive polling runs in a single Task loop; switching modes cancels the current Task.sleep so the new interval takes effect immediately.

Configuration

Settings are mostly hardcoded right now. Edit Sources/Peek/App.swift to change cadence:

@StateObject private var poller = Poller(
    interval: 60,            // slow / background poll
    fastInterval: 10,        // when panel open or activity detected
    activityWindow: 180      // stay fast for N seconds after a change
)

State persists at ~/Library/Application Support/Peek/state.json. Delete it to reset (loses ignore list and snapshot history → next launch will be a silent reseed).

Roadmap

• Launch at login via SMAppService.mainApp.register()
• Per-repo filter / mute list (beyond per-PR ignore)
• Inline "Approve" / "Request changes" actions
• Custom notification sounds per event type (opt-in)
• Snooze toggle
• Light-mode theming pass

License

MIT. See LICENSE.

Credits

Built by Srijan Mukherjee.