An always-on-top, frameless desktop panel that tracks your open GitHub pull requests and assigned issues. Built with Tauri 2 and React. Designed to live in a corner of your screen so you can glance at your queue without context-switching to a browser tab.
- Platform: macOS only (universal binary via DMG). Linux/Windows builds have not been tested.
- Auth: GitHub Personal Access Token, stored in the OS keychain (macOS Keychain Services / Windows Credential Manager / Linux Secret Service) via the
keyringcrate. The token never crosses the JS→Rust IPC after onboarding. - Data: PRs (
is:pr is:open author:@meplusis:pr is:open review-requested:@me, deduped) and issues (is:issue is:open assignee:@me) fetched from GitHub's GraphQL API. Polled every 60 seconds. Backed by an in-memory cache with a 30 second TTL.
Pre-built DMGs ship under Releases. Download, drag to Applications, launch.
First-launch Gatekeeper warning. The DMG is not Apple-Developer-ID code-signed or notarized yet, so macOS will show "GitBar can't be opened because Apple cannot check it for malicious software" the first time you launch. The workaround is a one-time approval:
- In
/Applications, right-click (or Control-click)GitBar.appand choose Open. - In the dialog that appears, click Open again.
- Future launches work normally from Spotlight, the Dock, or Finder.
Apple-Developer-ID signing is on the roadmap for a future release. Until then, the right-click-Open dance is the cost of running a small OSS macOS app. (Separately, the .app.tar.gz bundle that the in-app auto-updater downloads is signed with a minisign key; that signature is what tauri-plugin-updater checks before applying an update. It is unrelated to Gatekeeper and the DMG itself.)
git clone https://github.com/pravton/gitbar.git
cd gitbar
npm install
npm run tauri buildThe DMG lands in src-tauri/target/release/bundle/dmg/.
Requirements:
- Node.js
^22.22.2,^24.15.0, or>=26.0.0(an even-numbered LTS line; the floor comes from jsdom 30 and vitest 5, enforced viaenginesinpackage.json). Node 24 LTS is recommended;.nvmrcpins it. - Rust toolchain (stable, install via rustup)
- macOS 13+ for
color-mix()and:has()CSS support in the webview
- Generate a GitHub Personal Access Token with the
repoandread:orgscopes (github.com/settings/tokens). - Launch GitBar. Paste the token into the onboarding screen.
- The panel sits always-on-top across every macOS Space. Drag the header to move, click the chevron to collapse to a strip, click the tray icon to toggle visibility.
- Optional: add more accounts (say, work and personal) from Settings, then switch between them from Settings or the tray's Switch Account menu. The panel follows your macOS light/dark appearance.
The header carries a mood indicator on the left ("It's raining" when your queue is heavy), a strip of stat tiles for PRs / Review / Issues (each with a 24-hour trend sparkline behind the number so you can see whether the queue is growing), and a kebab menu with refresh / settings / help / density / "expand or collapse all groups". Click the amber Review tile to filter the PR list to "asked to review me"; click PRs to clear it.
The list below the search box shows PRs or issues for the active tab. Type to filter by repo, title, or #N across whatever's visible.
Each PR card includes:
- A CI pill at the bottom, with job counts when it matters ("CI 2/9 failing", "CI 3/9 running"). Click it to drill into per-job runs: status, duration, workflow, click-through to the job log on GitHub. Lazy-fetched per card (no extra polling), with a short cache so reopening is free.
- An Eye icon when you were asked to review this PR (sourced from the
review-requested:@mesearch, not just GitHub'sreview_decisionfield, so it works in repos without required-review rules). - A dashed PR icon + neutral grey dot when the PR is a draft. Drafts are visually deprioritized but the CI pill below still shows the real CI state.
- A Deploy button when the PR body carries a deploy-link marker (see below).
- A comments toggle in the card footer that opens a read-only comments panel: the conversation plus submitted reviews (approved / changes requested), newest last, and the PR's inline code review threads (file and line, resolved / outdated, each expandable), all linking to GitHub. Unresolved threads come first. New comments are marked. Close it with the toggle, the panel's X, or
Esc. Issue cards get the same panel. Bodies render a safe markdown subset (bold, italic, code, code blocks, headings, links, and shields.io badges as coloured pills); raw HTML is never rendered and remote images show as links. Lazy-fetched when opened, like the CI drill-down. - An unread badge (dot and "+N") on cards with comments added since you last looked, including while the app was closed, summed on collapsed repo groups. Opening the comments panel so it's on screen, or opening the item on GitHub, clears it. Tracked per account in
localStorage, by comment count, so your own new comments count too.
Toggle Compact (single-line rows) and Comfortable (full cards) via the kebab menu: Compact fits roughly three times more rows on the screen for the same vertical space. When a repo has three or more open PRs, they collapse into a single repo tile you can expand or collapse with the G keybind. A repo stays grouped until you quit, and one that starts grouping while the app is running opens instead of hiding the cards you were reading. Searching opens every group and puts them back when you clear it, leaving open the group around a card you selected. A filter opens only the groups it cuts below three PRs.
If GitHub returns 401 (expired or revoked PAT), a red banner appears at the top of the list with a Replace token button. It opens Settings on the rotate form, so you can paste a new token without losing the account. To remove an account, use its remove button in Settings.
If your token isn't authorized for an organization's SAML SSO, GitHub leaves that organization's results out of the list. A warning banner says how many are hidden, with a link to https://github.com/settings/tokens, where Configure SSO authorizes a classic token. Refresh afterwards to see them. If you already know and don't need those results, the banner's × hides it for that account, and Settings → Notifications → Hidden items warning turns it back on. Hiding it never hides other warnings, such as a failed query.
GitBar parses a labeled line out of the PR body and surfaces it as a click-through "Deploy" button. Drop one of these into your PR description:
Deploy: https://my-preview.example.com
Accepted labels (case-insensitive): Deploy:, Deploy-Link:, Preview:, Local-Deploy:, Local:. Or use an invisible HTML comment:
<!-- gitbar:deploy=https://my-preview.example.com -->
If both a body marker and a GitHub deployments-API URL exist, the body marker wins. This is intentional — a manually pasted local URL (Tailscale tunnel, ngrok, internal staging box) is usually more useful than an auto-generated cloud preview.
See AGENTS.md for the full convention if you want an AI agent to add the line when opening PRs.
The filter button on the PRs tab opens a popover with toggles for draft state, organization, CI status, and review-requested-only. Filters and named presets persist to localStorage. To share them across machines, turn on Filter sync in Settings: it's opt-in, and keeps them in a secret gist on your account. It needs the gist scope on your token, and anyone with the gist's URL can read it (see SECURITY.md).
The list is fully keyboard-driven:
| Key | Action |
|---|---|
↓ / ↑ (or j / k) |
Move selection between cards, wraps at the ends |
Enter |
Open the selected PR or issue in your browser or expand a repo group, or press the button or link that has focus |
D |
Open the selected PR's deploy URL (if it has one) |
C |
Show or hide the selected card's comments |
Cmd+1 / Cmd+2 |
Switch to the PRs / Issues tab |
/ |
Open the filter popover |
R |
Refresh data now |
G |
Expand or collapse all repo groups |
S |
Open settings |
? |
Show the in-app keyboard-shortcut cheat sheet |
Esc |
Close the help / filter popover, then open comments panels, then clear the selection (in that order) |
Press ? in-app, or click the ? button in the header, to see this list as a modal. Keys that would otherwise be hotkeys (digits, letters, /, ?) are swallowed by any input you're typing in, so the filter popover's text fields work normally.
Frontend (React + TypeScript + Tailwind v4) calls Rust commands via @tauri-apps/api invoke(). Rust calls GitHub's GraphQL API directly. The PATs are held in the OS keychain (one entry per account) and in Rust process memory only; a token crosses the JS to Rust IPC only when you paste it in. The main commands:
check_auth(token): validates a candidate PAT and returns its login. Called beforeadd_accountorreplace_active_token.list_accounts(),add_account(login, token),remove_account(login),switch_account(login),replace_active_token(expected_login, token): manage the account roster. Exactly one account is active; changing it clears the PR/issue snapshot so one account's data never shows under another.get_data(): returns{ prs, issues, partial_message, withheld_message, last_fetched_at_ms, history }, refreshing if the cache is older than 30 seconds. Reads the active token from Rust state; takes no parameter.refresh_cache(): forces a refresh and returns the same shape. Used by the manual refresh button.get_pr_checks(pr_url): fetches CI check runs for one PR when you expand its CI pill.gist_sync_enable(initial_payload),gist_sync_pull(login, gist_id),gist_sync_push(login, gist_id, payload): opt-in filter sync through one secret gist.get_item_comments(item_url): fetches the comments, submitted reviews, and inline review threads on one PR or issue when you open its comments panel.
Before each poll, a cheap conditional GET /notifications checks whether anything changed; a 304 skips the GraphQL refresh entirely, and a full refresh still runs at least every 5 minutes.
A tokio::sync::Mutex in AppState makes refreshes single-flight: concurrent stale callers wait on one in-flight fetch rather than firing parallel requests. Errors flow back to the UI as a tagged enum (auth | rate_limited | network | server | partial) so the frontend can route 401s back to onboarding and surface rate-limit retry-after times.
For full architecture detail see CLAUDE.md.
npm install # install JS deps
git config core.hooksPath .githooks # enable the pre-commit hook (one-time)
npm run tauri dev # full app with native window + HMR
npm run dev # frontend only (for browser iteration)
npm run build # tsc + vite build
npm run typecheck # tsc --noEmit (also runs in the pre-commit hook)
npm test # Vitest (frontend)
npm run test:rust # cargo test (Rust)
npm run install:local # build + replace /Applications/GitBar.app (see below)GitBar checks for a newer signed build on startup via tauri-plugin-updater. When one is available, a thin strip appears between the header and the list with a Restart to install button. The download + install + relaunch is one click. Updates are signed with a minisign keypair; the public key lives in src-tauri/tauri.conf.json under plugins.updater.pubkey and the corresponding private key is held in the TAURI_SIGNING_PRIVATE_KEY GitHub Actions secret. Releases without a valid signature are rejected by the client.
For maintainers cutting a release:
- Make sure
TAURI_SIGNING_PRIVATE_KEYis set as a repository secret (one-time). - Bump
versioninpackage.json,src-tauri/Cargo.toml, andsrc-tauri/tauri.conf.json. - Tag and push (
git tag vX.Y.Z && git push origin vX.Y.Z). Therelease.ymlworkflow builds a universal DMG, signs the.app.tar.gz, generateslatest.json, and uploads everything to a draft GitHub release. - Publish the draft. The updater endpoint resolves
latest.jsonvia the/releases/latest/download/redirect, so only published, non-prerelease tags are seen by users.
Rotating the signing key (only do this if the old private key is compromised; it forces every existing install to be reinstalled manually):
npx tauri signer generate -p "" -w .secrets/tauri-updater.key --ci -f
# Update plugins.updater.pubkey in src-tauri/tauri.conf.json with the
# contents of .secrets/tauri-updater.key.pub, then push the new private
# key to the TAURI_SIGNING_PRIVATE_KEY repo secret.npm run install:local rebuilds and atomically swaps /Applications/GitBar.app so the version you launch from Spotlight/Dock matches your current checkout. It also quits the running app, strips macOS quarantine, and relaunches. Cold build is 3-8 minutes; warm cache is ~30 seconds. Use this when you want to test against the production-style binary instead of npm run tauri dev.
The pre-commit hook runs tsc --noEmit and cargo check only on the relevant file types (~2-3s) and is the per-commit gate. CI (.github/workflows/ci.yml) runs on PRs targeting main or a release/* branch and on push to main, and skips changes that only touch docs. CI can also be triggered manually from the Actions tab via workflow_dispatch. Releases (.github/workflows/release.yml) build a universal macOS DMG when a v* tag is pushed.
Tests run at default parallelism — no --test-threads=1 needed. The Rust GraphQL endpoint is overridable in debug builds via GITBAR_GITHUB_GRAPHQL_URL for wiremock-based tests; the override is gated behind cfg(debug_assertions) so release builds always target api.github.com.
Branch conventions and commit style are in CLAUDE.md. Contribution guidelines: CONTRIBUTING.md.
- PAT storage. Stored in the OS keychain (
keyringcrate). The webview never receives or holds the token after onboarding; data-fetch commands take notokenparameter. Earlier versions stored it inlocalStorage; first launch of v0.2+ migrates that value into the keychain silently and removes the legacy entry. Details inSECURITY.md. - Endpoint override. The
GITBAR_GITHUB_GRAPHQL_URLenv var is honored only in debug builds. Release builds hard-codeapi.github.comso a hostile environment cannot redirect PAT-bearing requests. - Content-Security-Policy. Distinct policies for release (
csp) and dev (devCsp) intauri.conf.json. Release locksscript-src 'self',object-src 'none',base-uri 'self',frame-ancestors 'none'; onlystyle-src 'unsafe-inline'is permitted (Tailwind v4's runtime style injection requires it). The Vite HMR WebSocket and'unsafe-eval'are dev-only. SeeSECURITY.md. - Dependencies.
npm auditclean.cargo auditreports 17 advisories, all unmaintained-crate notices (not active CVEs) on transitive deps pulled in by Tauri (gtk-*,glib,proc-macro-error,unic-*). None affect the macOS target. CI ignores them explicitly so the audit job stays meaningful for new findings.
Report security issues via GitHub private vulnerability reporting; do not open public issues for vulnerabilities. Full policy in SECURITY.md.
See ROADMAP.md for tracked work and ideas.
MIT, see LICENSE.