🔐 GitHub Auth Agent

Skip the gh auth login dance. Press ⌘G; a menu-bar app OCRs the device code off your screen, drives agent-browser against github.com/login/device, and clicks Authorize for you. ✨

GitHub.Auth.Agent.mp4

---

🚀 Quickstart

# 1. install (builds release binaries + /Applications app + /usr/local/bin/auth-cli)
git clone git@github.com:LivioGama/github-auth-agent.git
cd github-auth-agent
make install

# 2. capture a GitHub session (one-time, manual login)
agent-browser --state ~/.config/auth-daemon/github-auth.json \
              open https://github.com/login

# 3. run
open /Applications/GitHubAuthAgent.app

Then in any shell, run gh auth login, leave the device code on screen, and press ⌘G. 🎉

---

🤔 How it works

Press ⌘G anywhere → Apple Vision OCRs your visible screen and finds the XXXX-XXXX code near GitHub context → the daemon drives agent-browser (with saved cookies) → fills the 8 boxes → clicks Authorize → 🔔 notification.

The Cmd+G hotkey is intercepted via CGEventTap and suppressed so it never reaches the focused app.

---

🔓 Permissions

Pane	Why
🦾 Accessibility	catch ⌘G globally
📺 Screen Recording	OCR your screen
🔔 Notifications	enable GitHub Auth Agent when prompted

Find GitHub Auth Agent in each list (System Settings → Privacy & Security) and toggle it on.

---

🍔 Menu-bar app

Click the GitHub mark in the menu bar:

• Show browser window — toggle headless vs. visible browser for the auth flow
• Scan screen now (⌘G) — same as the hotkey
• Open logs / Open state folder
• Quit GitHub Auth Agent

---

🏗️ Layout

github-auth-agent/
├── rust/
│   ├── Cargo.toml          # workspace
│   └── crates/
│       ├── core/           # gaa-core: shared types, regexes, paths, Prefs
│       ├── cli/            # auth-cli: status / start / daemon
│       └── daemon/         # auth-daemon: HTTP + hotkey + OCR + tray
├── scripts/install.sh
├── assets/GitHubAuthAgent.app/   # bundle skeleton; binary swapped in at install
├── Makefile  README.md  LICENSE

Runtime state:

Path	Purpose
/Applications/GitHubAuthAgent.app	menu-bar app (Rust binary)
/usr/local/bin/auth-cli	CLI
~/Library/Logs/GitHub Auth Agent/auth-daemon.log	append-only log
~/.config/auth-daemon/github-auth.json	saved GitHub cookies (0700 dir)
~/.config/auth-daemon/prefs.json	headless toggle, internal flags
~/.config/auth-daemon/auth-daemon.pid	single-instance lock

---

🧰 CLI

auth-cli status                  # daemon health
auth-cli start github            # trigger flow with the code already on screen
auth-cli start github --code XXXX-XXXX
auth-cli daemon start            # exec the daemon in foreground
auth-cli daemon stop             # pkill the daemon

Set AUTH_DAEMON_URL to point the CLI at a non-default port.

---

🛠️ Develop

make build       # cargo build --release
make run         # foreground daemon
make test        # cargo test --workspace
make fmt         # cargo fmt --all
make lint        # cargo clippy --all-targets -- -D warnings

The workspace has three crates:

Crate	Purpose
gaa-core	Pure types, regexes, paths, prefs serde. All unit-tested.
auth-cli	Clap-based CLI; reqwest::blocking against the daemon's HTTP API.
auth-daemon	macOS-only binary: axum HTTP, tray-icon menu, CGEventTap hotkey, native objc2-vision OCR, subprocess agent-browser driver.

---

🐛 Troubleshooting

Symptom	Fix
⌘G does nothing	Grant Accessibility to /Applications/GitHubAuthAgent.app.
"OCR failed"	Grant Screen Recording.
No notifications	Toggle GitHub Auth Agent on under Notifications; disable Focus.
reason=not_found / expired	Code already used or aged out — rerun gh auth login.
Missing …/github-auth.json	Skipped the cookie-capture step.
daemon already running	Click Quit in the tray, or auth-cli daemon stop.

📜 tail -f ~/Library/Logs/GitHub\ Auth\ Agent/auth-daemon.log or use the tray Open logs item.

---

📄 License

MIT — see LICENSE. Bundles a re-skinned terminal-notifier (MIT) for native notifications.