Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jasonkneen/openclicky/llms.txt

Use this file to discover all available pages before exploring further.

OpenClicky is distributed as an Xcode project that you build and run yourself. This gives you full control over the code, signing identity, and update behavior. The app requires macOS 14.2 or newer and Xcode with the macOS SDK.

​
Requirements

  • macOS 14.2 or newer
  • Xcode with the macOS SDK installed
  • A signing team configured in Xcode (free Apple Developer account works for local runs)
  • API keys for the AI providers you want to use (supplied separately — see Configuration)

​
Build and Run

1

Clone the repository

git clone https://github.com/jasonkneen/openclicky.git
cd openclicky
2

Open in Xcode

open cursor-buddy.xcodeproj
3

Configure signing

In Xcode, select the cursor-buddy target → Signing & Capabilities tab → set your Team to your Apple Developer account (or personal team).
4

Select the scheme and run

  1. Select the cursor-buddy scheme from the scheme picker.
  2. Select the OpenClicky app target.
  3. Press Cmd+R to build and run.
5

Grant system permissions

macOS will prompt for three permissions when OpenClicky first runs:
  • Accessibility — required for the cursor overlay and UI element detection
  • Microphone — required for push-to-talk voice input
  • Screen Recording — required for screen-aware responses
Grant all three. You can verify them later in System Settings → Privacy & Security.
Do not use xcodebuild from the terminal for permission testing. macOS TCC permissions are tied to the signed app identity and install path — throwaway command-line builds cause permission loops. Always run from Xcode with a consistent signing identity.

​
Development Verification

For lightweight syntax checking without disturbing macOS permissions, run swiftc -parse over the source files you changed: 
swiftc -parse cursor-buddy/CompanionManager.swift cursor-buddy/CompanionPanelView.swift
For the external control bridge, a dedicated verification script covers Swift parsing, bridge health, MCP descriptors, screenshot capture, captions, secondary cursors, and SSE events: 
scripts/test-external-control-bridge.sh

​
Updating

OpenClicky uses Sparkle 2 for OTA updates in distributed builds. The app checks a signed appcast.xml feed hosted in this repository’s main branch and downloads signed DMGs from GitHub Releases. For development builds run from Xcode, updates are not applicable — rebuild from source to get the latest code. See docs/APP_UPDATES.md for the full release and appcast workflow.

​
Troubleshooting

Check that your signing team is set and that you’re running on macOS 14.2+. If you’ve run unsigned build artifacts before, revoke their TCC permissions in System Settings → Privacy & Security, then re-run from Xcode.
This usually means macOS cached an old permission grant for a different signed identity. Open System Settings → Privacy & Security → Accessibility (and Screen Recording), remove any existing OpenClicky or cursor-buddy entries, then relaunch from Xcode.
Check System Settings → Privacy & Security → Microphone. If OpenClicky isn’t listed, relaunch the app and try the push-to-talk shortcut — macOS will prompt for the permission on first use.

Build docs developers (and LLMs) love

Get started for freeTalk to us