OpenClicky is a macOS menu-bar assistant that drives its own overlay

A menu-bar host for an assistant that can see the screen

OpenClicky is described as a native macOS menu-bar companion by Jason Kneen, and it hosts Clicky, an AI companion providing push-to-talk voice help, screen-aware responses, image gallery views, local agent work, and a cursor overlay for pointing at user interface elements. The two-layer structure matters, because the menu-bar app is the host and Clicky is what it serves. Screen awareness is the capability that shapes everything else. The documentation describes screen-aware guidance using the markers `[POINT:x,y:label]` and `[TYPE:x,y:label]`, which are how the model asks the host to indicate a place on screen, either to point at it or to type into it. Combined with a cursor overlay, that turns a text answer into a directed one, and the cursor is the app's own overlay rather than the macOS pointer, which matters for both safety and appearance. The application is MIT licensed, and the last push to the repository was on 2026-09-05.

Routing decides whether the model answers or acts

The routing section is the most useful part of the documentation, because it describes an order of preference rather than a list of features. Clicky prefers structured routes over visible user interface whenever possible. Direct answers serve simple questions. Web search handles fresh information. Image gallery flows cover visual content. Child workers are spawned for substantial builds, research, artifact work, connected-app actions, or multi-step interface tasks. Work that stays in the same context goes through `sessions_send`, while new work starts in `sessions_spawn`. Integration routes such as GitHub through Composio MCP are preferred before falling back to browser or window automation, and OpenClicky's computer-use path is used only as the last-mile fallback for native Mac or browser actions. The stated capability list behind that routing covers fresh web search for facts and news, image gallery display, child workers and agent spawning, GitHub integration through Composio MCP, local shell and file work inside the configured projects root, frontend builds and previews, reports and PDF, DOCX and spreadsheet output, repo scaffolding, a native computer-use fallback, and optional yes/no Agent Mode confirmations through local Nodex AirPods head gestures. The preference order is the design: a model that can be answered without touching the screen should be.

Secrets stay local and outside the project directory

OpenClicky uses local configuration only, with no Google login requirement and no hosted key-sync flow, and the secrets section is specific about how keys reach the app. It can read local secrets from the in-app Settings fields, from launch environment variables, from a secrets file at `~/.config/openclicky/secrets.env`, or from a custom file path set with `OPENCLICKY_SECRETS_FILE`. The recognised values are short.

ANTHROPIC_API_KEY=your_anthropic_key
ELEVENLABS_API_KEY=your_elevenlabs_key
ELEVENLABS_VOICE_ID=your_elevenlabs_voice_id
OPENAI_API_KEY=your_openai_or_codex_key

The recommended local setup creates the directory with restrictive permissions before you create the file, then restricts the file itself.

mkdir -p ~/.config/openclicky
chmod 700 ~/.config/openclicky
$EDITOR ~/.config/openclicky/secrets.env
chmod 600 ~/.config/openclicky/secrets.env

The guidance that the repository `.gitignore` excludes `.env` and `.env.local` is followed by the note that the app no longer reads repository-local `.env` files at all, and the instruction to keep secrets outside the project directory. Google Workspace access is handled through local tooling rather than through an OpenClicky-hosted Google login or key sync, which is a deliberate narrowing of scope rather than an omission.

Building in Xcode, and why xcodebuild is discouraged

The build instructions are short, and the constraints are specific. You need macOS 14.2 or newer, Xcode with the macOS SDK, a signing team configured in Xcode for local runs, and local API keys supplied outside the repository. The build itself opens the project.

open cursor-buddy.xcodeproj

Then in Xcode you select the `cursor-buddy` scheme, select the OpenClicky app target, set your signing team, run the app with Cmd+R, and grant the Accessibility, Microphone and Screen Recording permissions when macOS asks. The permission step is not a formality, since the app points at the screen and listens to the microphone, and the documentation goes out of its way to warn against using terminal `xcodebuild` for permission testing. The reason given is that macOS TCC permissions are tied to the signed app identity and install path, and throwaway command-line builds can cause permission loops. The legacy `cursor-buddy` folder and scheme names are kept for project continuity, while the product, bundle display name and app identity are OpenClicky, which is a detail worth knowing before you search for build settings.

The control bridge is a local HTTP API with a fixed scope

OpenClicky exposes a local-only control bridge for agents and other trusted local apps, listening on a fixed loopback address.

http://127.0.0.1:32123

The bridge is intentionally non-invasive. It drives the overlay, takes screenshots and speaks through text to speech, but it does not start dictation, submit prompts, create new agent sessions, or mutate the normal OpenClicky conversation state. That boundary is the interesting design decision, because a bridge that could submit prompts or spawn sessions would carry far more risk to expose on a port. The endpoints are listed explicitly. `GET /health` checks status, `GET /mcp/tools` lists MCP-style tool descriptors, `POST /cursor` points with the primary cursor or creates one secondary marker, `POST /cursors` shows several temporary markers at once, `POST /caption` shows a short caption near a coordinate or the current cursor, `POST /screenshot` captures local screenshots with display-frame metadata for locating the interface, `POST /speak` speaks through the app's text to speech without entering voice mode, `POST /clear` clears bridge-created overlay elements, and `GET /events` streams server-sent events.

Primary cursor, secondary markers, and not warping the pointer

The cursor behaviour is specified in enough detail to be testable, which is unusual and welcome. The default `/cursor` uses the existing smooth pointing choreography, the same behaviour the app uses for voice prompts such as showing the Apple menu, and the triangle zips to the target, shows the caption and returns to the real pointer. The requirement is that it should not warp the macOS pointer and should not draw a duplicate primary cursor. Secondary cursors are a separate concept, explicit temporary markers for multi-point explanations, alternatives or screen-tour overlays, which disappear automatically after `durationMs` or can be cleared with `/clear`. The example calls show the shape of the API.

curl -s -X POST http://127.0.0.1:32123/cursor \
  -H 'Content-Type: application/json' \
  -d '{"x":640,"y":520,"caption":"Click this menu","durationMs":4500}'

The multi-marker variant takes a list of cursors with an accent colour each, and the screenshot endpoint takes a `focused` flag. The distinction between a primary pointer and secondary markers is a good piece of API design, since a screen tour needs several labels at once while a single instruction should not leave a trail of arrows behind.

Verification, packaging and the limits of the documentation

Development verification has a script that does more than compile. For a lightweight syntax check that does not disturb macOS permissions, the documentation suggests running `swiftc -parse` over the changed source files, and warns against launching unsigned or temporary build products for permission testing. The external control bridge can be checked with a script.

scripts/test-external-control-bridge.sh

That script performs Swift parse and typecheck checks, verifies the local bridge, exercises the MCP descriptors, screenshot capture, captions and secondary cursors, checks the server-sent events, and confirms that primary cursor guidance uses the app's own choreography without warping the real system pointer. That last assertion is the kind of thing that is easy to break and hard to notice, so having it in a script is a genuine saving. The optional hands-free Agent Mode confirmations through AirPods head gestures have their own document. Distribution is handled through `appcast.xml`, the demo clip and the disk image background, with the update feed and direct-distribution release flow documented in `docs/APP_UPDATES.md`. What the documentation does not cover is the wider product surface: there is no release history, the repository has no GitHub releases, and the version of the underlying models and providers is not stated, so treat the capability list as a record of one point in time rather than a contract.

Editorial conclusion

Adopt OpenClicky if you want a local macOS assistant that can point at interface elements, capture screenshots and speak without sending your screen to a hosted service, and you are prepared to supply your own API keys. Skip it if you need a cross-platform client or an assistant with a hosted conversation history, since the configuration is local by design. Before you commit, set up the secrets file outside the project directory, and read the AirPods gesture documentation, because that optional confirmation mode has its own privacy and hardware requirements.

Frequently asked questions

Official sources

1. Issues
2. jasonkneen/openclicky on GitHub
3. License: MIT
4. README