Cat Eye — GitHub Actions & PR Monitor for macOS

A lightweight, native macOS menu bar app for monitoring GitHub Actions CI/CD status, pull request reviews, and weekly CI health. Open source, ~380KB, accessible, zero Electron.

The octocat's eye never blinks.

There are plenty of GitHub status apps out there. Most are Electron wrappers that eat 200MB+ of RAM to show you a green checkmark. Cat Eye exists because a status indicator shouldn't cost more than the IDE it sits next to.

Cat Eye is built on three principles:

• Extremely low footprint — a single ~380KB Swift binary, ~35MB of RAM, zero frameworks beyond AppKit. No runtime, no bundled browser, no background bloat.
• Minimalist — just the important information: are your Actions passing, and do any PRs need your review. Deeper stats live behind the Insights tab, so the default view stays a status light, not a dashboard.
• Accessible — colour is never the only signal. Status uses the Okabe-Ito colour-blind-safe palette plus shape and text cues, and everything is keyboard navigable.

Actions tab	Pull Requests tab

Features

Actions Tab

• Live status icon — GitHub mark tinted by status, with a small badge glyph (check / cross / hourglass) so state is readable without colour
• Pulsing animation — icon gently pulses when any action is actively running
• Rich popover — scrollable list of recent runs across all your repos, styled like the GitHub Actions UI
• Per-run details — workflow name, run number, branch badge, timestamps, and duration
• Expandable run rows — click a run to expand it inline: failed runs show the exact failure annotations (job/step + message), successful runs show the full commit message and durations, in-progress runs show live elapsed time and per-workflow status
• Calculated ETA — estimates remaining time for running actions based on historical durations
• macOS notifications — alerts when actions start, pass, or fail — click the notification to open the popover

Pull Requests Tab

• Review queue — shows PRs where your review is requested, across all tracked repos
• Expandable detail — click any PR to expand inline with full description and labels
• PR actions — approve, request changes, comment, merge (merge/rebase/squash), or close — all from the menu bar
• Inline comments — type and submit comments without leaving the popover
• Safe input — popover won't dismiss while you're typing a comment

Insights Tab

• Deploy log — every run Cat Eye sees is appended to ~/.config/cat-eye/deploys.jsonl, so your history survives restarts
• Last 7 days vs previous 7 — pass rate, average duration, deploy pass rate, and a per-workflow breakdown
• Automatic insights — slowest workflow, biggest failure source, and the branches that fail most
• Copy report for AI — copies a full markdown report plus a task prompt, ready to paste into Claude or ChatGPT

General

• Tabbed interface — switch between Actions, PRs and Insights
• Repo filter — "All Repos" or pick a specific repo; persists across tabs
• Built-in setup — login to GitHub and pick repos to track from the settings panel
• Keyboard accessible — navigate rows with Tab, activate with Return or Space
• Colour-blind friendly — status colours use the Okabe-Ito colour-blind-safe palette, and every state also carries a shape or text signal (badge glyphs, spelled-out statuses, tooltips)
• Copy URL — one-click copy of any run or PR URL to clipboard
• Direct links — click to open runs or PRs in GitHub
• Multi-repo — monitor as many repos as you want from a single widget
• Adaptive polling — 30s normally, 10s while the popover is open and a run is in progress (both configurable)
• Hot-reload config — change tracked repos from settings without restarting
• Auto-detects gh CLI — finds your GitHub CLI install automatically
• Error feedback — clear messages when gh CLI is missing, auth fails, or API errors occur
• Tiny footprint — ~380KB binary, ~35MB memory, zero dependencies beyond macOS

Requirements

• macOS 13+ (Ventura or later)
• GitHub CLI (gh) installed and authenticated (brew install gh && gh auth login)
• Apple Silicon or Intel Mac
• Xcode Command Line Tools only if building from source (xcode-select --install)

Installation

Upgrading from 1.0.x: the bundle identifier changed to com.clintoncodewell.cateye. macOS treats that as a new app, so you will be asked for notification permission again, and any old CatEye.app should be deleted. Your settings in ~/.config/cat-eye/config.json carry over untouched.

Option 1: Homebrew (recommended)

brew tap clintoncodewell/tap
brew install cat-eye

Then launch with open $(brew --prefix)/CatEye.app.

Option 2: Download binary

Grab CatEye.zip from the latest release, unzip, and double-click. On first launch, macOS will block it — right-click → Open → Open to bypass Gatekeeper (required for unsigned apps).

Option 3: Build from source

# Prerequisites (skip if already installed)
xcode-select --install   # Xcode Command Line Tools
brew install gh           # GitHub CLI

# Clone and build
git clone https://github.com/clintoncodewell/cat-eye.git
cd cat-eye
./build.sh

# Run
open CatEye.app

On first launch, the Settings panel opens automatically:

1. Login — click "Login..." to authenticate with GitHub (opens Terminal with gh auth login --web)
2. Pick repos — your repos and org repos are fetched automatically; check the ones you want to track
3. Add manually — type owner/repo in the "Add Repo Manually" field for repos not in the list
4. Save — click "Save & Apply" and you're monitoring

Reopen Settings any time via the gear icon in the footer. You can also Logout from the Settings panel.

Make it findable via Spotlight / Raycast

# Symlink into ~/Applications (indexed by Spotlight)
ln -sf "$(pwd)/CatEye.app" ~/Applications/CatEye.app

Then search for "Cat Eye" in Spotlight or Raycast.

Auto-start on login

cat > ~/Library/LaunchAgents/com.cateye.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cateye</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/open</string>
        <string>/path/to/cat-eye/CatEye.app</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
EOF

# Enable it
launchctl load ~/Library/LaunchAgents/com.cateye.plist

Replace /path/to/cat-eye/ with your actual install path.

Configuration

Config lives in ~/.config/cat-eye/config.json (managed via the Settings panel, or edit directly):

{
    "repos": [
        "myorg/backend",
        "myorg/frontend",
        "myuser/side-project"
    ],
    "pollInterval": 30,
    "pollActiveInterval": 10,
    "runsPerRepo": 10,
    "filterDefaultBranches": false
}

Key	Default	Description
repos	[]	GitHub repos to monitor (owner/repo format)
pollInterval	30	Seconds between checks when idle
pollActiveInterval	10	Seconds between checks while the popover is open and a run is in progress
runsPerRepo	10	Number of recent runs to fetch per repo
filterDefaultBranches	false	Hide workflow runs from branches other than main or develop

Using the PRs tab

Switch to the PRs tab to see pull requests where your review is requested.

• Expand a PR — click any PR row to expand it inline, showing the description, labels, and action buttons
• Approve — click "Approve" (optionally type a comment first)
• Request changes — type your feedback in the comment field, then click "Changes" (comment is required)
• Comment — type in the comment field and click "Comment"
• Merge — pick a merge strategy (Merge commit / Rebase / Squash) from the dropdown, then click "Merge"
• Close — click "Close", then confirm by clicking "Sure?" (auto-resets after 3 seconds)
• Filter — use the repo dropdown in the top bar to focus on a specific repo

When a PR is expanded, the popover switches to semitransient mode so it won't close while you're typing a comment.

Building from source

# Requires Xcode Command Line Tools
xcode-select --install

# Build (produces CatEye.app)
./build.sh

How it works

• Uses the gh CLI under the hood — no API tokens to manage, no OAuth flows. If gh auth status works, Cat Eye works.
• Fetches runs via gh api repos/OWNER/REPO/actions/runs and PRs via gh pr list --search review-requested:@me, for every configured repo, all concurrently.
• The 10-second poll runs only while the popover is open. Closed, Cat Eye falls back to the normal interval — measured on a real machine, that took a long CI run from 1,148 GitHub API calls/hour down to 382.
• PR actions (approve, comment, merge, close) call gh pr review, gh pr comment, gh pr merge, and gh pr close respectively.
• Runs as a macOS accessory app (no Dock icon, no Cmd+Tab entry).
• Notifications use the native UserNotifications framework — respects Do Not Disturb and Focus modes.

Menu bar icon states

Colours come from the Okabe-Ito colour-blind-safe palette, and each state also punches a badge glyph into the icon so it's readable without colour perception.

Icon	Badge	Meaning
Bluish green	Checkmark	All recent key runs passing
Vermillion	Cross	Most recent deploy/test run failed
Sky blue (pulsing)	Hourglass	A run is currently in progress
Gray	—	No data or no repos configured

Prioritizes deploy and smoke test workflows for overall status, so Dependabot noise won't turn your icon red.

Troubleshooting

Problem	Fix
Icon stays gray, "GitHub CLI not found"	Install gh: brew install gh and restart Cat Eye
"Not authenticated" error	Run gh auth login in Terminal, or click Login in Settings
"No access" or a 404 from gh	The token expired or lost a scope. GitHub answers 404, not 401, for a private repo it cannot see — run gh auth login
No PRs showing	The PR tab only shows PRs where your review is requested — not all open PRs
Popover closes while typing	Expand a PR first — this switches to semitransient mode
Config changes not taking effect	Click "Save & Apply" in Settings — no restart needed
Build fails	Ensure Xcode Command Line Tools are installed: xcode-select --install

Why Cat Eye?

	Cat Eye	Typical Electron app
Binary	~380 KB	150–300 MB
Memory	~35 MB (0.2%)	200–400 MB
CPU at idle	0%	0.5–2%
Dependencies	macOS + gh CLI	Node.js, Chromium, npm packages
Startup	Instant	2–5 seconds

Cat Eye is a single Swift file compiled to a native binary. No runtime, no garbage collector, no bundled browser engine. It wakes up every 30 seconds, runs a few gh CLI commands, updates a menu bar icon, and goes back to sleep.

Process info

Process name	cat-eye
Spotlight name	Cat Eye
Binary size	~380KB
Memory	~35 MB / 0.2% on 16GB Mac
Bundle ID	com.clintoncodewell.cateye

Contributing

Contributions welcome — see CONTRIBUTING.md. The short version: keep it lean (one Swift file, zero dependencies), keep it secure, keep it accessible.

License

MIT