[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1574":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},1574,"openclicky","jasonkneen\u002Fopenclicky","jasonkneen","openclicky -- the open source version of clicky",null,"Swift",394,73,5,1,0,10,94,175,30,5.61,"MIT License",false,"main",true,[],"2026-06-12 02:00:29","# OpenClicky\n\nOpenClicky is a native macOS menu-bar companion by Jason Kneen. It provides push-to-talk voice help, screen-aware responses, a cursor overlay for pointing at UI elements, and an Agent Mode dashboard for coding, research, writing, and automation tasks.\n\nOpenClicky uses local configuration only. There is no Google login requirement and no hosted key-sync flow.\n\n## Requirements\n\n- macOS 14.2 or newer\n- Xcode with the macOS SDK\n- A signing team configured in Xcode for local runs\n- Local API keys supplied outside the repository\n\n## Repository Layout\n\n- `leanring-buddy.xcodeproj` and `leanring-buddy\u002F` contain the macOS app target.\n- `leanring-buddyTests\u002F` contains focused app tests.\n- `leanring-buddyUITests\u002F` contains UI test scaffolding.\n- `AppResources\u002FOpenClicky\u002F` contains bundled model instructions, skills, wiki seed, Codex runtime, and completion audio.\n- `appcast.xml`, `clicky-demo.gif`, and `dmg-background.png` support distribution and release packaging.\n- `docs\u002FAPP_UPDATES.md` documents the Sparkle update feed and direct-distribution release flow.\n\nThe legacy `leanring-buddy` folder and scheme names are kept for project continuity. The product, bundle display name, and app identity are OpenClicky.\n\n## Secrets\n\nDo not commit API keys to this repository.\n\nOpenClicky can read local secrets from:\n\n- the in-app Settings fields\n- launch environment variables\n- a secrets file at `~\u002F.config\u002Fopenclicky\u002Fsecrets.env`\n- a custom file path set with `OPENCLICKY_SECRETS_FILE`\n\nSupported values:\n\n```sh\nANTHROPIC_API_KEY=your_anthropic_key\nELEVENLABS_API_KEY=your_elevenlabs_key\nELEVENLABS_VOICE_ID=your_elevenlabs_voice_id\nOPENAI_API_KEY=your_openai_or_codex_key\n```\n\nGoogle Workspace access is intentionally handled through local tooling, not OpenClicky-hosted Google login or key sync. See [Google Workspace via gogcli](#google-workspace-via-gogcli).\n\nRecommended local setup:\n\n```sh\nmkdir -p ~\u002F.config\u002Fopenclicky\nchmod 700 ~\u002F.config\u002Fopenclicky\n$EDITOR ~\u002F.config\u002Fopenclicky\u002Fsecrets.env\nchmod 600 ~\u002F.config\u002Fopenclicky\u002Fsecrets.env\n```\n\nThe repo `.gitignore` excludes `.env` and `.env.local`, but the app no longer reads repo-local `.env` files. Keep secrets outside the project directory.\n\n## Build And Run\n\nOpen the project in Xcode:\n\n```sh\nopen leanring-buddy.xcodeproj\n```\n\nIn Xcode:\n\n1. Select the `leanring-buddy` scheme.\n2. Select the OpenClicky app target.\n3. Set your signing team.\n4. Run the app with `Cmd+R`.\n5. Grant Accessibility, Microphone, and Screen Recording permissions when macOS asks.\n\nDo not use terminal `xcodebuild` for permission testing. macOS TCC permissions are tied to the signed app identity and install path, and throwaway command-line builds can cause permission loops.\n\n## Development Verification\n\nFor a lightweight syntax check that does not disturb macOS permissions, run `swiftc -parse` over the changed source files. Avoid launching unsigned or temporary build products for permission testing.\n\nThe external-control bridge can be checked with:\n\n```sh\nscripts\u002Ftest-external-control-bridge.sh\n```\n\nThe script performs Swift parse\u002Ftypecheck checks, verifies the local bridge, exercises MCP descriptors, screenshot capture, captions, secondary cursors, SSE events, and confirms that primary cursor guidance uses OpenClicky's native choreography without warping the real system pointer.\n\n## External Control Bridge\n\nOpenClicky exposes a local-only control bridge for agents and other trusted local apps:\n\n```text\nhttp:\u002F\u002F127.0.0.1:32123\n```\n\nThe bridge is intentionally non-invasive. It drives OpenClicky's overlay, screenshots, and TTS, but does not start dictation, submit prompts, create new agent sessions, or mutate the normal OpenClicky conversation state.\n\nUseful endpoints:\n\n- `GET \u002Fhealth` checks bridge status.\n- `GET \u002Fmcp\u002Ftools` lists MCP-style tool descriptors.\n- `POST \u002Fcursor` points with the primary OpenClicky cursor, or creates one secondary marker with `mode: \"secondary\"`.\n- `POST \u002Fcursors` shows multiple temporary secondary markers at once.\n- `POST \u002Fcaption` shows a short caption near a coordinate or the current cursor.\n- `POST \u002Fscreenshot` captures local screenshots with display-frame metadata for locating UI.\n- `POST \u002Fspeak` speaks through OpenClicky's TTS without entering voice mode.\n- `POST \u002Fclear` clears bridge-created overlay elements.\n- `GET \u002Fevents` streams server-sent bridge events.\n\nPrimary cursor behavior matters: default `\u002Fcursor` uses OpenClicky's existing smooth pointing choreography, the same behavior used by voice prompts like \"show me the Apple menu\". The OpenClicky triangle zips to the target, shows the caption, and returns to the real pointer. It should not warp the macOS pointer and should not draw a duplicate primary cursor.\n\nSecondary cursors are explicit temporary markers. Use them for multi-point explanations, alternatives, or screen-tour overlays. They automatically disappear after `durationMs` or can be cleared with `\u002Fclear`.\n\nExample primary pointer cue:\n\n```sh\ncurl -s -X POST http:\u002F\u002F127.0.0.1:32123\u002Fcursor \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"x\":640,\"y\":520,\"caption\":\"Click this menu\",\"durationMs\":4500}'\n```\n\nExample simultaneous multi-marker cue:\n\n```sh\ncurl -s -X POST http:\u002F\u002F127.0.0.1:32123\u002Fcursors \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"durationMs\":4500,\"cursors\":[{\"x\":640,\"y\":520,\"caption\":\"Editor\",\"accentHex\":\"#60A5FA\"},{\"x\":900,\"y\":520,\"caption\":\"Logs\",\"accentHex\":\"#F59E0B\"}]}'\n```\n\nExample screenshot-to-pointer workflow:\n\n```sh\ncurl -s -X POST http:\u002F\u002F127.0.0.1:32123\u002Fscreenshot \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"focused\":false}'\n\ncurl -s -X POST http:\u002F\u002F127.0.0.1:32123\u002Fcursor \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"x\":1180,\"y\":760,\"caption\":\"Use this button\"}'\n```\n\nBundled agent skills for this bridge live in `AppResources\u002FOpenClicky\u002FOpenClickyBundledSkills\u002F`:\n\n- `google-workspace-gogcli`: local Google Workspace access through `gogcli` for Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Contacts, Tasks, Admin, Groups, and related Google services.\n- `openclicky-screen-control`: quick point, caption, screenshot, speak, and clear commands.\n- `openclicky-screen-tour`: recordable visual tours with multiple simultaneous markers, area-focused overlays, speech, and primary cursor choreography.\n\n## Google Workspace via gogcli\n\nOpenClicky can connect agents to Google Workspace through the local [`gogcli`](https:\u002F\u002Fgithub.com\u002Fsteipete\u002Fgogcli) command, installed as `gog`. This keeps Google authentication local to the user's machine and avoids adding hosted OAuth, Google login, or cloud key sync to OpenClicky.\n\nIf gogcli uses the encrypted file keyring, OpenClicky agents need the same keyring password non-interactively. Put it in `~\u002F.config\u002Fopenclicky\u002Fsecrets.env` as `GOG_KEYRING_PASSWORD=...`, or migrate gogcli to the macOS Keychain backend. If Google's OAuth screen says \"Clicky\", that branding comes from the local OAuth client stored in `~\u002FLibrary\u002FApplication Support\u002Fgogcli\u002Fcredentials.json`; replace it with an OpenClicky-owned Desktop OAuth client to change the consent-screen app name.\n\nInstall on macOS:\n\n```sh\nbrew install gogcli\n```\n\nCheck status from OpenClicky Settings → Google, or from the terminal:\n\n```sh\nscripts\u002Fcheck-gogcli-workspace.sh\n```\n\nOr manually:\n\n```sh\ngog --version\ngog auth status --json\ngog auth list\n```\n\nInitial setup requires a Google Cloud Desktop OAuth client JSON owned by the user or their Workspace organization. Store it in gogcli, not in this repository:\n\n```sh\ngog auth credentials ~\u002FDownloads\u002Fclient_secret_....json\n```\n\nAuthorize with least-privilege scopes for the services needed:\n\n```sh\n# Read-only Gmail + Drive example\ngog auth add you@example.com --services gmail,drive --gmail-scope readonly --drive-scope readonly\n\n# Calendar + Tasks read-only example\ngog auth add you@example.com --services calendar,tasks --readonly\n```\n\nFor Workspace-specific clients\u002Fdomains:\n\n```sh\ngog --client work auth credentials ~\u002FDownloads\u002Fwork-client.json --domain example.com\ngog auth alias set work you@example.com\n```\n\nCommon read commands:\n\n```sh\ngog gmail search 'newer_than:7d' --account work --json\ngog calendar events --account work --json\ngog drive search \"name contains 'proposal'\" --account work --json\ngog contacts search 'Jane Doe' --account work --json\n```\n\nWrite actions such as sending email, posting Chat messages, modifying Drive files, changing calendar events, contacts, groups, or admin state should only run after explicit user intent. The bundled `google-workspace-gogcli` skill documents safe usage patterns for agents.\n\n## Swift SDK Embedding (Windowed)\n\nFor Swift hosts that want an in-window OpenClicky instance that is separate from the OS-level menu-bar companion, use `OpenClickySDKSession` from `leanring-buddy\u002FOpenClickySDK.swift`.\n\nExample:\n\n```swift\nimport SwiftUI\n\nlet sdk = OpenClickySDKSession(mode: .embeddedWindow)\n\n\u002F\u002F In app startup\nsdk.start()\n\n\u002F\u002F In SwiftUI\nvar body: some View {\n    sdk.makePanelView(actions: .init(\n        onPanelDismiss: { \u002F* dismiss host panel *\u002F },\n        onQuit: { \u002F* close host window if needed *\u002F }\n    ))\n}\n\n\u002F\u002F Send input\nsdk.submitTextPrompt(\"Summarize this page\")\n```\n\nThe host can either use SDK actions for Settings\u002FHUD\u002FMemory, or keep them no-op and route that experience separately.\n\nSee [OpenClicky SDK Integration Guide](docs\u002FOpenClickySDKIntegration.md) for step-by-step host app integration instructions.\n\n## Direct Updates\n\nOpenClicky uses Sparkle for direct-distribution OTA updates. Installed builds check the signed `appcast.xml` feed from this repository's `main` branch, then download and install signed release DMGs from GitHub Releases. See [docs\u002FAPP_UPDATES.md](docs\u002FAPP_UPDATES.md) for the release checklist and appcast item template.\n\n## Credits And Upstream Work\n\nOpenClicky is maintained by [Jason Kneen](https:\u002F\u002Fgithub.com\u002Fjasonkneen).\n\nThis project builds on the original open-source Clicky work:\n\n- Original project: [farzaa\u002Fclicky](https:\u002F\u002Fgithub.com\u002Ffarzaa\u002Fclicky)\n- Original creator: Farza, GitHub [@farzaa](https:\u002F\u002Fgithub.com\u002Ffarzaa), X [@FarzaTV](https:\u002F\u002Fx.com\u002Ffarzatv)\n\nOpenClicky has also incorporated ideas and implementation patterns from these forks:\n\n- [@danpeg](https:\u002F\u002Fgithub.com\u002Fdanpeg)'s [danpeg\u002Fclicky](https:\u002F\u002Fgithub.com\u002Fdanpeg\u002Fclicky), reviewed locally as `clicky-teach`, for tutor-mode direction and idle observation behavior.\n- [@milind-soni](https:\u002F\u002Fgithub.com\u002Fmilind-soni)'s [milind-soni\u002Ftiptour-macos](https:\u002F\u002Fgithub.com\u002Fmilind-soni\u002Ftiptour-macos), for developer-menu\u002Fdebug tooling patterns and related teaching-assistant UX ideas.\n\n## License\n\nMIT. Copyright 2026 Jason Kneen. Portions are derived from or informed by the upstream MIT-licensed projects credited above.\n","OpenClicky 是一个开源的 macOS 菜单栏伴侣应用，旨在提供语音帮助、屏幕感知响应、UI 元素指针叠加以及适用于编码、研究、写作和自动化任务的代理模式仪表板。其核心功能包括本地配置管理（无需 Google 登录或托管密钥同步流程）、语音交互支持及丰富的辅助工具集，采用 Swift 语言开发。该应用适合需要高效执行多任务处理或寻求智能化工作辅助的专业人士使用，尤其在需要频繁切换任务或进行复杂操作时能显著提升效率。",2,"2026-06-11 02:44:47","CREATED_QUERY"]