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.

​
What is the OpenClicky SDK?

OpenClickySDKSession is the SDK-facing entry point that lets you embed OpenClicky’s full AI runtime directly into your own macOS app. Instead of shipping the menu-bar companion separately, your app owns and controls the entire OpenClicky runtime — voice input, agent mode, TTS playback, screen context, and the full conversational panel — as a first-class citizen of your window hierarchy.
Source-level integration only. OpenClicky is currently an app target, not a packaged Swift library or Swift Package Manager product. Integration is done by adding Swift source files and bundled resources from this repository into your host app target. A dedicated SPM product is not yet available.

​
Execution Modes

OpenClickySDKMode controls whether OpenClicky behaves as its built-in menu-bar companion or as an in-window runtime owned by your app.

​
OpenClickySDKMode.menuBar

Keeps the existing menu-bar runtime running exactly as the default OpenClicky app does. Use this when you want to incorporate CompanionManager directly without changing its behavior.

​
OpenClickySDKMode.embeddedWindow

Runs OpenClicky as an in-window, app-owned runtime. This is the mode intended for SDK embedding. In this mode:
  • The global push-to-talk shortcut monitor is not started — your app is responsible for triggering voice input through startVoiceCapture().
  • The overlay auto-show is disabled — the floating cursor overlay does not appear automatically on startup.
  • Onboarding and reveal behavior are not tied to menu-bar state — your app controls when and how the panel appears.
  • The notch pill (the persistent pill on the menu-bar notch) is not shown.

​
What You Get in Embedded Mode

When you initialize OpenClickySDKSession(mode: .embeddedWindow), you get a self-contained runtime that includes:
CapabilityDetails
OpenClickySDKSessionThe single @MainActor ObservableObject you own in your app. Controls start, stop, restart, and all prompt/voice inputs.
OpenClickySDKPanelA SwiftUI View wrapping CompanionPanelView — the full conversation panel, safe to embed in any NSWindow or .sheet.
OpenClickySDKPanelActionsA struct of seven optional callbacks for panel controls (dismiss, quit, HUD, memory, visual, feedback, settings).
AI runtimeFull Claude / OpenAI / Codex voice response pipeline, agent mode, TTS, screen capture, and memory.

​
Differences from the Menu-Bar Companion

FeatureMenu-bar companionEmbedded SDK
Global push-to-talk shortcut✅ Started automatically❌ Not started — use startVoiceCapture()
Overlay auto-show✅ Shows on startup❌ Disabled
Onboarding tied to menu-bar✅ Yes❌ No
Panel presentationDriven by clickyDismissPanel notificationsDriven by your app’s state (e.g. .sheet)
Notch pill✅ Shown❌ Not shown
CompanionManager runtimeSingle shared instanceOne per OpenClickySDKSession

​
Use Cases

The embedded SDK is designed for:
  • Custom AI-powered macOS apps built on top of OpenClicky’s runtime — ship your own branded experience powered by Claude, agent mode, and voice.
  • Internal tools that need an AI companion embedded into a specific window rather than globally.
  • Demos and prototypes that want the full OpenClicky conversation surface inside a single app window.
  • Extensions to existing apps that want to surface AI voice or text assistance inline.

​
Source-Level Integration Approach

Because OpenClicky ships as an app target (not an SPM package), embedding it means:
  1. Adding Swift source files from cursor-buddy/ into your host app target. Include everything except cursor_buddyApp.swift (the menu-bar app entry point).
  2. Copying bundled resources — model instructions, skills, wiki seed, CodexRuntime, and audio files — into your host app bundle at the resource root.
  3. Adding privacy keys to your host app’s Info.plist for microphone, speech recognition, screen capture, and Apple Events.
  4. Initializing and starting OpenClickySDKSession in your SwiftUI scene or AppKit controller.
  5. Wiring API keys for Anthropic, Codex, ElevenLabs, and Cartesia.
See the Quickstart for the full step-by-step walkthrough.

​
OpenClickySDKPanelActions

OpenClickySDKPanelActions is a struct of seven callback closures that let your host app respond to control affordances inside the embedded panel. All callbacks default to no-ops, so you only wire the ones you need. 
let actions = OpenClickySDKPanelActions(
    onPanelDismiss: { showOpenClicky = false },
    onQuit:         { showOpenClicky = false },
    onOpenHUD:      { /* show your HUD surface */ },
    onOpenMemory:   { /* show your memory UI */ },
    onOpenVisual:   { /* show your visual workspace */ },
    onOpenFeedback: { /* open your feedback URL */ },
    onShowSettings: { /* show your settings UI */ }
)
CallbackWhen it fires
onPanelDismissThe close affordance in the panel UI is activated
onQuitThe user taps “Quit OpenClicky” inside the panel
onOpenHUDThe panel requests the HUD surface
onOpenMemoryThe panel requests the memory window
onOpenVisualThe panel requests the visual intelligence workspace
onOpenFeedbackThe panel requests the feedback / inbox link
onShowSettingsThe panel requests the settings surface
Because your host app owns the window hierarchy, none of these callbacks have default behavior — you route each one to whichever surface makes sense for your app.

​
Next Steps

Quickstart

Add source files, bundle resources, and launch the embedded runtime in five steps.

API Reference

Complete reference for all public types, properties, and methods.

Build docs developers (and LLMs) love

Get started for freeTalk to us