Lunavect

Installing Lunavect

Requirements

macOS 14 Sonoma or later. The download includes Apple silicon and Intel code; the release has been tested on Apple silicon. Intel hardware and other supported macOS versions still need testing.
Claude Code CLI for Claude usage and sessions. Claude Desktop alone is not enough.
The official Codex client for Codex usage and sessions.

Only the client you choose to connect is required. Allowances depend on what that client exposes for your account.

Homebrew

With Homebrew installed:

brew tap lovach/lunavect https://github.com/lovach/Lunavect
brew install --cask lovach/lunavect/lunavect
open -a Lunavect

The cask downloads the signed release DMG and checks its SHA-256 checksum.

Direct download

Download the DMG, about 11 MB.
Open it and drag Lunavect to Applications.
Open Lunavect from Applications.

The app is Developer ID signed and notarized by Apple. The ZIP and appcast.xml on the release page are for the built-in updater. Choose the DMG for manual installation. Checksum files are included on the Releases page.

Connect a client

Choose Connect Claude or Connect Codex in Lunavect. The guide checks the official client, offers installation when needed, and starts sign-in through that client. Before enabling the connection, it explains the local event handlers and Claude status-line changes.

You can connect either service or both. Existing authentication stays with the official clients. Lunavect does not ask you to paste provider passwords or API keys.

Right-click the desktop and choose Edit Widgets.
Search for Lunavect and choose a widget and size.
For an activity widget, right-click the placed widget and choose Edit Widget to set its source and time period.

macOS schedules widget refreshes. Native layouts have been inspected; placement and refresh of the release on the real desktop remain unverified. See the compatibility notes.

Update

Use Settings → Updates in Lunavect to check for a release or manage automatic downloads.

For a Homebrew installation:

brew update
brew upgrade --cask lovach/lunavect/lunavect

Uninstall

Disconnect Claude and Codex in Settings → Connections, then quit Lunavect. This lets Lunavect restore previous event handlers and the Claude status line before the app is removed.

If you have used Keep Awake, stop it, quit Lunavect and remove its system helper before removing the app. Deleting the app does not run this cleanup. Run the command from the installed app:

"/Applications/Lunavect.app/Contents/MacOS/Lunavect" --unregister-awake-helper

For an installation in your home folder, use "$HOME/Applications/Lunavect.app/Contents/MacOS/Lunavect". The command fails if sleep is still disabled or the helper could not be unregistered; resolve that before removing the app. Complete removal lists the checks.

For a Homebrew installation (the cask quits Lunavect before removing it):

brew uninstall --cask lovach/lunavect/lunavect

For a direct installation, delete Lunavect from Applications. Settings and activity history are retained. See connection removal for more detail.

Troubleshooting

A limit is unavailable: open Settings → Connections. Check the selected client’s status and follow its repair guidance. A successful sign-in does not guarantee that the client has supplied fresh allowances.
Sessions stop updating: use the connection diagnostics to check event handlers. Session state depends on client events; reconnecting or repairing a service should be done through Settings.
A value looks stale: check its timestamp. Missing or expired limits are not treated as unlimited usage.

If the problem remains, report a bug with the app version, macOS version, Mac architecture and steps to reproduce. Remove private titles, paths and credentials from attachments.

FAQ · Privacy and data removal · Verified checks and open limitations · Back to README

This site is open source. Improve this page.