The Swift package target is `macOS(.v14)`, so Sonoma or newer is the supported baseline.
Setup guide
Install ZackEyes.
ZackEyes ships as a universal macOS DMG for Apple Silicon and Intel Macs. The current app target requires macOS 14 or newer.
Install.
Use the public release channel for the latest signed installer asset and future update checks.
- Download the DMG. Use the latest ZackEyes installer from GitHub Releases.
- Open the DMG. Drag ZackEyes into Applications when Finder shows the installer window.
- Launch the app. Keep Claude Code or Codex CLI running in your normal terminal; ZackEyes installs the supported hooks when it can find those CLIs.
- Handle macOS security prompts. If macOS asks for confirmation on first launch, approve the app from System Settings and reopen it.
- Review optional permissions. Accessibility permission enables terminal tab jump. Notifications permission enables macOS alerts for completed turns, rate limits, update availability, and errors.
Compatibility
What is supported.
The release build uses both `arm64` and `x86_64`, producing a universal macOS app bundle for the DMG.
ZackEyes installs hooks for whichever CLI it finds and skips missing agents without breaking the terminal workflow.
With Accessibility permission, clicking a session card can activate the terminal tab where that agent is running.
A Settings window — opened from the notch gear or the menu-bar icon — collects the global hotkey, island visibility, quota presentation, and a Preferred quota source that picks whether the compact pill favors Claude or Codex.
Build from source.
ZackEyes is MIT-licensed and the full app, bridge CLI, and this website live in one monorepo. If you'd rather build the DMG yourself, audit the hook installer, or hack on a feature, clone the repo and run the same Makefile we ship from.
- Clone the source.
git clone https://github.com/yangshiqi/ZackEyes.git - Need Xcode Command Line Tools.
xcode-select --installif you haven't already; the build uses Swift 6 from the system toolchain. - Build the app.
cd ZackEyes && make appproduces a debug bundle.make app-releasebuilds the universal release bundle.make dmgwraps it into a drag-to-Applications DMG. - Run the tests.
swift testexercises the bridge, hook installer, socket types, and notch logic in < 2s. - Contribute. Pick a good first issue, open a PR. See the repo README for the workflow.
Uninstall ZackEyes.
Remove the app bundle first. If you also want to clean local integration state, remove ZackEyes-managed hook entries and local settings.
- Quit ZackEyes. Use the menu bar item or Activity Monitor if the app is still running.
- Remove the app. Delete ZackEyes from `/Applications`.
- Review agent hooks. ZackEyes hook commands contain the literal string `zackeyes`, so they can be identified in `~/.claude/settings.json` and `~/.codex/hooks.json`.
- Delete local settings if needed. Remove `~/.zackeyes` only if you want to clear local ZackEyes configuration.
Troubleshooting
Common setup problems.
macOS says ZackEyes cannot be opened
Open System Settings, review the Security prompt for ZackEyes, allow the app, then launch it again from Applications.
Claude or Codex sessions do not appear
Confirm the relevant CLI is installed and start a fresh Claude Code or Codex CLI session. Codex threads that started before hooks were installed may need a new thread for full hook-driven behavior.
Permission requests do not show in the notch
Check that ZackEyes is running and that the agent hook file contains a ZackEyes-managed command. If the app is closed, the agent should fall back to its native terminal prompt.
Reinstall hooks
Quit ZackEyes, remove stale hook entries containing zackeyes from the Claude or Codex hook files if needed, then reopen ZackEyes and start a new agent session.