clicky README

The project's README from github.com/farzaa/clicky. As one markdown file: README.md.

Update: April 27, 2026.

Hi there! I'm Farza, the guy that made Clicky.

The existing codebase remains open source. Tinker with it, make it yours, start a company out of it, do whatever you want I don't mind. But, for all the new stuff I'm hacking on, gonna keep it private. To get the latest Clicky, you can go here.

I also tweeted about this here.

Go crazy with this repo!! It's an MIT license.

Hi, this is Clicky.

It's an AI teacher that lives as a buddy next to your cursor. It can see your screen, talk to you, and even point at stuff. Kinda like having a real teacher next to you.

Download it here for free.

Here's the original tweet that kinda blew up for a demo for more context.

Clicky — an ai buddy that lives on your mac

This is the open-source version of Clicky for those that want to hack on it, build their own features, or just see how it works under the hood.

Get started with Claude Code

The fastest way to get this running is with Claude Code.

Once you get Claude running, paste this:

Hi Claude.

Clone https://github.com/farzaa/clicky.git into my current directory.

Then read the CLAUDE.md. I want to get Clicky running locally on my Mac.

Help me set up everything — the Cloudflare Worker with my own API keys, the proxy URLs, and getting it building in Xcode. Walk me through it.

That's it. It'll clone the repo, read the docs, and walk you through the whole setup. Once you're running you can just keep talking to it — build features, fix bugs, whatever. Go crazy.

Manual setup

If you want to do it yourself, here's the deal.

Prerequisites

1. Set up the Cloudflare Worker

The Worker is a tiny proxy that holds your API keys. The app talks to the Worker, the Worker talks to the APIs. This way your keys never ship in the app binary.

cd worker
npm install

Now add your secrets. Wrangler will prompt you to paste each one:

npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler secret put ASSEMBLYAI_API_KEY
npx wrangler secret put ELEVENLABS_API_KEY

For the ElevenLabs voice ID, open wrangler.toml and set it there (it's not sensitive):

[vars]
ELEVENLABS_VOICE_ID = "your-voice-id-here"

Deploy it:

npx wrangler deploy

It'll give you a URL like https://your-worker-name.your-subdomain.workers.dev. Copy that.

2. Run the Worker locally (for development)

If you want to test changes to the Worker without deploying:

cd worker
npx wrangler dev

This starts a local server (usually http://localhost:8787) that behaves exactly like the deployed Worker. You'll need to create a .dev.vars file in the worker/ directory with your keys:

ANTHROPIC_API_KEY=sk-ant-...
ASSEMBLYAI_API_KEY=...
ELEVENLABS_API_KEY=...
ELEVENLABS_VOICE_ID=...

Then update the proxy URLs in the Swift code to point to http://localhost:8787 instead of the deployed Worker URL while developing. Grep for clicky-proxy to find them all.

3. Update the proxy URLs in the app

The app has the Worker URL hardcoded in a few places. Search for your-worker-name.your-subdomain.workers.dev and replace it with your Worker URL:

grep -r "clicky-proxy" leanring-buddy/

You'll find it in:

4. Open in Xcode and run

open leanring-buddy.xcodeproj

In Xcode:

  1. Select the leanring-buddy scheme (yes, the typo is intentional, long story)
  2. Set your signing team under Signing & Capabilities
  3. Hit Cmd + R to build and run

The app will appear in your menu bar (not the dock). Click the icon to open the panel, grant the permissions it asks for, and you're good.

Permissions the app needs

Architecture

If you want the full technical breakdown, read CLAUDE.md. But here's the short version:

Menu bar app (no dock icon) with two NSPanel windows — one for the control panel dropdown, one for the full-screen transparent cursor overlay. Push-to-talk streams audio over a websocket to AssemblyAI, sends the transcript + screenshot to Claude via streaming SSE, and plays the response through ElevenLabs TTS. Claude can embed [POINT:x,y:label:screenN] tags in its responses to make the cursor fly to specific UI elements across multiple monitors. All three APIs are proxied through a Cloudflare Worker.

Project structure

leanring-buddy/          # Swift source (yes, the typo stays)
  CompanionManager.swift    # Central state machine
  CompanionPanelView.swift  # Menu bar panel UI
  ClaudeAPI.swift           # Claude streaming client
  ElevenLabsTTSClient.swift # Text-to-speech playback
  OverlayWindow.swift       # Blue cursor overlay
  AssemblyAI*.swift         # Real-time transcription
  BuddyDictation*.swift     # Push-to-talk pipeline
worker/                  # Cloudflare Worker proxy
  src/index.ts              # Three routes: /chat, /tts, /transcribe-token
CLAUDE.md                # Full architecture doc (agents read this)

Contributing

PRs welcome. If you're using Claude Code, it already knows the codebase — just tell it what you want to build and point it at CLAUDE.md.

Got feedback? DM me on X @farzatv.

clicky (farzaa/clicky)

Searching Database…

7.7K ·GitHub
Clicky
What is this?Clicky is an AI teacher that lives next to your cursor: it sees your screen, talks to you, and can even point at things on screen, like having a real teacher sitting beside you.
Is this the actual Clicky app, or the code behind it?It's a native macOS menu bar app written in Swift. This repo is the open-source version for hacking on it; the polished latest Clicky is a separate free download, and the author keeps new development private.
How do I get it running?Fastest way: paste the repo prompt into Claude Code — it clones the repo, reads the docs, and walks you through setup. Manually: deploy the Cloudflare Worker, update the proxy URLs in the Swift code, then open in Xcode, set your signing team, and hit Cmd+R.
What do I need installed before I can build it?macOS 14.2+, Xcode 15+, Node.js 18+, and a Cloudflare account (free tier works). You also need API keys for Anthropic, AssemblyAI, and ElevenLabs.
Why does it need all those permissions?It asks for four: Microphone for push-to-talk capture, Accessibility for the global Control+Option shortcut, Screen Recording for hotkey screenshots, and Screen Content for ScreenCaptureKit access. Without these, its core see-and-talk loop can't work.
Does it run on Windows, or is it Mac-only?Mac only. It's a Swift app built in Xcode and requires macOS 14.2+ for ScreenCaptureKit, so there's no Windows or Linux version.
Where do my API keys and screen data go?Your API keys live in a Cloudflare Worker proxy rather than in the app: the app talks to the Worker, and the Worker talks to the APIs. Voice audio, transcripts, and screenshots still go out to AssemblyAI, Claude, and ElevenLabs during use.
Can I reuse the code in my own project?Yes — it's MIT licensed, so you can tinker with it, make it yours, or even start a company out of it.
How does the pointing-at-things part actually work?Claude can embed [POINT:x,y:label:screenN] tags in its responses, which make your cursor fly to specific UI elements across multiple monitors.
What happens when I hold the push-to-talk key?Your audio streams over a websocket to AssemblyAI for transcription; the transcript plus a screenshot go to Claude via streaming SSE, and the reply is played back through ElevenLabs TTS.
Where does the app show up once it's running?In the menu bar, not the dock. It uses two NSPanel windows: a control panel dropdown and a full-screen transparent cursor overlay.
What are similar projects?BetterDisplay, tendedero, bluey-by-riley, lipflow, rooms, jarvis, macos-sysdata, textream
Which topics is it in?menubar, voice-assistant, screenshot, computer-use, menu-bar, xcode, speech-recognition, tts, cloudflare, macos-app, websocket, streaming
Creator
farzaa
Size
10.8 MB
Stars
7.7K
Updated
CommitApr 27
Age
6mo
Commits · 90 Days