GitHub Float

Your GitHub Project's code reviews, always on top of your screen.
A tiny native macOS floating panel that shows what you put in review, who is reviewing it, and which teammates' PRs still need a reviewer.

github-float-demo.mp4

---

Why?

Your PR sits in In Review for two days because nobody noticed it. A teammate's PR waits for a reviewer while you're heads-down. You keep switching to the browser to check the board.

GitHub Float keeps your GitHub Project review flow in a small glass panel that floats above every window, on every Space, even over full-screen apps. Glance, don't switch.

✨ Features

• 🪟 Always on top: a non-activating floating panel that never steals focus, visible on all Spaces and over full-screen apps. Drag it anywhere; near a screen edge or corner it snaps into place like a magnet. Docked at the bottom, the header moves to the bottom row and the tasks open upwards, so the bar never jumps. The panel shrinks to fit short lists (folded sections leave no empty space) and grows back up to the size you dragged it to.
• 📌 Attach to Menu Bar: turn it on in the menu, or just drag the panel up onto the menu bar icon (the icon lights up; let go to attach), and the panel hangs right under the menu bar icon, with a popover arrow pointing at it; click the icon to show or hide it, and a click anywhere outside hides it again, like a menu bar popover. Right-click the icon for the options. Drag the panel away (or untick the option) to detach it and float it anywhere again. With two displays, the panel stays on its display while you work on the other one; click the menu bar icon there to bring it over.
• 👤 Mine: your tasks grouped by status (In Progress, In Review, Reviewed), each with its linked PRs. User Stories that have sub-issues are hidden: you follow them through their sub-issues.
• 🗂️ Your layout: click a section header to fold it, and drag headers to put the status you care about first (or right-click → Move Up / Move Down).
• ➡️ Send to review: right-click one of your tasks in In Progress (or an earlier column) → Move to In Review to update its board status without opening GitHub. Uses your configured review status and needs the project token scope (gh auth refresh -s project).
• 👀 Reviewing: the tasks you are reviewing for teammates, split into Your turn and Waiting on the author, with a notification when a re-review is requested.
• 🚚 Moves the card for you: approve and the card goes to the next status (e.g. Reviewed); request changes and it goes back to In Progress and you're unassigned. Your own tasks follow the same rule: when a reviewer requests changes, the card goes back to In Progress, even if it was moved to Reviewed (that column is only for approved work). And if someone approves a PR without assigning themselves first, they're added as the task's reviewer (second assignee), so it leaves Needs reviewer. Toggle it with Move Cards After My Review. When all the PRs of one of your own tasks are merged, it goes to Ready to Verify from whatever earlier column it is in (Move My Merged Tasks to Ready to Verify). The same goes for a User Story split into sub-issues: once all its sub-issues are closed or in Ready to Verify (or later), the story moves to Ready to Verify too.
• 🔍 Review state at a glance: awaiting review, being reviewed, changes requested, approved, merged, plus the reviewers and CI status (✅ ❌ ⏳).
• 🕊️ FC Monitor's john-pidgeon label: labeled PRs show Auto-approve · do not review in every tab. This is a notice of the team's convention, not an automatic approval or a change to the PR's actual review state.
• 🙋 Needs reviewer: teammates' tasks in review with no second assignee, and an Assign me button that adds you as the reviewer without opening GitHub (the task then moves to Reviewing).
• 🗄️ Archive people: right-click a task in Needs reviewer → Archive 's Tasks for people whose work you don't review (e.g. another team on the same board). Their tasks move to a folded Archived section at the bottom, with no badge count or notifications; open it when someone asks you anyway. Unarchive from the right-click menu or ⋯ → Archived People.
• 😀 Your own header icon: ⋯ → Header Icon swaps the app mark for an emoji (presets or any custom one).
• 👥 Only people count as reviewers: automatic team requests (e.g. CODEOWNERS) are ignored, so a PR stays No reviewers until someone is requested or picks the task, and you see their name. Before the review column (e.g. In Progress) a PR simply shows as Open.
• 🔁 Re-request review: when your PR has changes requested and you've pushed the fixes, the card shows a Re-request review button (also in the right-click menu). It asks those reviewers to look again, moves the card back to the review status and re-assigns them if they were unassigned.
• ⏱️ Time in status: an age badge turns orange after 24h and red after 72h.
• 🔔 Native notifications when something needs you: a new review, changes requested, approval, failing CI, merged PR, a task moved forward, or a new task waiting for a reviewer. Each kind of event has its own synth sound (needs you, good news, bad news, comment), and you can preview them or switch to the macOS default in the Sound menu.
• ⬆️ Updates itself: when a new release is out, a popup offers Update Now (downloads, installs and reopens in a few seconds, no Terminal or browser) or Remind Me Later (asks again the next day). A dot on the ⋯ button and an Update GitHub Float menu item stay until you update; Check for Updates… is always in the menu.
• ⚡ Efficient: one GraphQL request per poll for all tabs. Polling pauses while your Mac sleeps or is locked and backs off on errors.
• 🧩 Compact mode: collapse to a single line with your counts.
• 🔐 Private: no server and no telemetry. It only talks to api.github.com with your own token.
• 🪶 Native and tiny: Swift + SwiftUI, a few MB, no Electron.

Mine	Reviewing	Needs reviewer

📦 Install

Homebrew

brew install --cask vinimcorrea/tap/github-float

The app updates itself (it asks when a new version is out). To do it by hand, run brew update && brew upgrade --cask github-float (Homebrew refreshes taps only once a day, so without brew update a new release may not be seen yet).

Download

1. Download GitHubFloat.zip from the latest release and unzip it.
2. Move GitHubFloat.app to /Applications.
3. The app is ad-hoc signed (not notarized), so on first launch right-click → Open, or run:

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

Build from source

Requires Xcode 15+ / Swift 5.9+.

git clone https://github.com/vinimcorrea/github-float.git
cd github-float
./build.sh            # builds and installs ~/Applications/GitHubFloat.app
open ~/Applications/GitHubFloat.app

🚀 Setup

1. Authenticate. GitHub Float uses, in order: GH_TOKEN, GITHUB_TOKEN, or your GitHub CLI login (gh auth token). The easiest way is:

   gh auth login
   gh auth refresh -s read:project

   With a personal access token (classic), use the scopes read:project and repo (or public_repo).
2. Connect a project. On first launch, paste your project URL, e.g. https://github.com/orgs/my-org/projects/12 or https://github.com/users/me/projects/3. You can change it at any time from the ⋯ menu → Connect a Project… (⌘,).

Your project needs a single-select Status field (the default in GitHub Projects). The statuses shown in Mine and the status that means "in review" can be changed from the menu.

🧠 How it works

Tab	Shows
Mine	Items assigned to you whose Status is one of the selected statuses (default: In Progress, In Review, Reviewed), excluding the ones you are reviewing.
Reviewing	Items assigned to you where someone else authored the linked PR (or, without a PR, is the first assignee), while the PR is still open. Your turn means you have not reviewed yet or a re-review was requested. A task leaves once you approve or request changes.
Needs reviewer	Open items in the review status (default: In Review) not assigned to you that have fewer than 2 assignees. The convention: the author is the first assignee, and a reviewer adds themselves as the second one.

Review stage of each linked PR: merged/closed → draft → approved / changes requested (until every reviewer who asked for changes is re-requested) → being reviewed (a review was submitted) → awaiting review (reviewers requested) → no reviewers. Bot reviews and the author's own comments are ignored.

When you approve a task that is in the review status, GitHub Float moves it to the next status on the board. When you request changes, it moves the task to In Progress and removes you from its assignees. Only reviews submitted after the task entered the review status count, so older reviews never move a card back. This needs the project scope (gh auth refresh -s project).

⌨️ Shortcuts

Keys	Action
⌘1 / ⌘2 / ⌘3	Switch between Mine, Reviewing and Needs reviewer
⌘R	Refresh now
⌘W / – button	Hide the panel (click the menu bar icon to bring it back)
⌘,	Connect a project
Click a row	Open the issue or PR in your browser

The menu bar item shows mine · open counts. From the ⋯ menu you can also set the poll interval, the opacity, notifications and sound, and launch at login. Untick Show Hide Button to remove the – button from the header (shown by default); ⌘W and Hide Panel in the menu still work.

🛠️ CLI helpers

GitHubFloat.app/Contents/MacOS/GitHubFloat --dump              # print the current board data as text
GitHubFloat.app/Contents/MacOS/GitHubFloat --notify-test       # send a test notification
.build/release/GitHubFloat --screenshots docs                  # regenerate README screenshots with demo data

🗺️ Roadmap

• Multiple projects
• Custom tab filters (any Projects filter query)
• Homebrew cask
• Notarized builds
• Keyboard navigation inside the list

Have an idea? Open an issue.

🤝 Contributing

PRs are welcome! See CONTRIBUTING.md. The whole app is about 2k lines of Swift in Sources/GitHubFloat.

📄 License

MIT © Vinicius Correa

---

If GitHub Float saves you a few context switches, please ⭐ star the repo. It helps others find it.