If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/farzaa/clicky shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 2w ago
• MIT licensed
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live farzaa/clicky repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/farzaa/clicky.

What it runs against: a local clone of farzaa/clicky — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in farzaa/clicky | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 41 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of farzaa/clicky. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/farzaa/clicky.git
#   cd clicky
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of farzaa/clicky and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "farzaa/clicky(\\.git)?\\b" \\
  && ok "origin remote is farzaa/clicky" \\
  || miss "origin remote is not farzaa/clicky (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 41 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~11d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/farzaa/clicky"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Clicky is a macOS AI teaching companion that uses ScreenCaptureKit to see your screen, AssemblyAI for speech transcription, and Claude/Anthropic for AI reasoning. It sits as a persistent buddy next to your cursor, can point at screen elements, and provide real-time educational guidance by understanding both what you're doing visually and what you're saying via voice input. Monolithic macOS app structure: core Swift code lives directly in leanring-buddy/ directory with a single Xcode project (leanring-buddy.xcodeproj); Cloudflare Worker proxy (worker/) handles API key management and proxying to external services; no internal monorepo structure—the app and worker are loosely coupled via HTTPS.

Students, educators, and self-taught learners on macOS who want an AI tutor that understands their screen context and can guide them through coding problems, tutorials, or technical concepts without opening a separate chat window.

The project is in a transitional state: the open-source version (circa early 2026) is stable enough to build and run locally, but the original creator (Farza) has moved the active development private as of April 27, 2026. This archive is MIT-licensed and functional, but no longer receiving updates—it's frozen at a working but feature-complete state rather than actively developed.

Single-maintainer risk is high since development moved private; the open-source version will not receive bug fixes or security updates. The app depends on external SaaS APIs (Anthropic, AssemblyAI, ElevenLabs) with no fallback, and requires sensitive API keys managed via a Cloudflare Worker proxy. The codebase has minimal visible test coverage in the file list, increasing regression risk if you fork and modify.

Nothing. The repo is archived in open-source form as of April 2026. All active development has moved to a private codebase; this version is a snapshot released for community tinkering and licensing freedom (MIT), but no PRs, issues, or commits are actively tracked here.

git clone https://github.com/farzaa/clicky.git && cd clicky && open leanring-buddy.xcodeproj — then follow Manual Setup in README: configure a Cloudflare Worker with API keys (Anthropic, AssemblyAI, ElevenLabs), deploy it, then update the app to point to your Worker URL.

Daily commands: xcode-build-and-run: open leanring-buddy.xcodeproj in Xcode 15+, configure your Cloudflare Worker URL in app config, then build/run to macOS 14.2+. Alternatively, cd worker && npx wrangler dev to run the proxy locally during development.

• leanring-buddy/AppBundleConfiguration.swift: Central configuration and initialization point for the app, likely where Cloudflare Worker URL and API endpoint routing is defined
• leanring-buddy/AppleSpeechTranscriptionProvider.swift: Handles native macOS speech-to-text using Apple's framework; core input mechanism for understanding user speech
• leanring-buddy/AssemblyAIStreamingTranscriptionProvider.swift: Alternative STT provider using AssemblyAI API for higher accuracy; shows abstraction pattern for swappable transcription backends
• worker/wrangler.toml: Cloudflare Worker configuration: defines API secret keys and ElevenLabs voice ID; required for deploying the API proxy
• leanring-buddy/AGENTS.md: Documents the AI agent behavior, prompts, and interaction patterns—critical for understanding how Claude is instructed to behave as a tutor
• CLAUDE.md: Setup guide for using Claude Code to scaffold and develop the project; documents the intended onboarding workflow

Audio & transcription: edit AppleSpeechTranscriptionProvider.swift or AssemblyAIStreamingTranscriptionProvider.swift. App initialization & config: AppBundleConfiguration.swift. Worker proxy logic: worker/src/ or worker/wrangler.toml. UI and screen interaction likely in root leanring-buddy/ files (not fully visible in file list). View AGENTS.md and CLAUDE.md for prompt/behavior patterns.

1. Cloudflare Worker URL must be injected into the app at build time or runtime config—if misconfigured, all API calls will fail silently. 2. API keys (Anthropic, AssemblyAI, ElevenLabs) must be set as Wrangler secrets or in wrangler.toml vars; missing any key will break that feature (e.g., no TTS if ElevenLabs voice ID is blank). 3. ScreenCaptureKit requires macOS 14.2+ and may require screen recording permissions (System Preferences > Privacy & Security > Screen Recording)—without it, the core 'see your screen' feature fails. 4. ElevenLabs voice ID is a string literal in wrangler.toml, not secret; if changed, you must redeploy the Worker. 5. No local dev database or state persistence visible—assume all state is ephemeral or stored in user defaults (macOS).

• ScreenCaptureKit — This is Clicky's core perception mechanism—it's the macOS framework that lets the app capture screen pixels and recognize visual context; understanding it is essential to modify what the AI can 'see'
• Streaming Speech-to-Text (STT) — Clicky streams audio to AssemblyAI or uses Apple's native STT; streaming (vs. batch) is critical for low-latency, real-time tutor interactions
• API Key Management via Cloudflare Workers — Secrets are never shipped in the macOS binary; instead, the app talks to a Cloudflare Worker that proxies requests and injects keys server-side—this is a common pattern to keep sensitive credentials out of client apps
• Text-to-Speech (TTS) with ElevenLabs — The AI tutor must speak back to the user; ElevenLabs provides natural voice synthesis via API, and the app uses a specific voice ID to maintain consistency
• Vision-Language Models (Claude with Screen Context) — Claude can understand both text (user speech, code) and images (screenshots) simultaneously; this multi-modal reasoning is what allows Clicky to 'point at stuff' and give contextual guidance
• macOS App Sandboxing & Permissions — Clicky needs Screen Recording, Microphone, and possibly Accessibility permissions; understanding macOS security models is essential to debug permission-related crashes
• Wrangler & Cloudflare Worker Deployment — The Cloudflare Worker proxy is deployed via Wrangler CLI and run on Cloudflare's edge; understanding the wrangler.toml config and secret management is necessary to deploy and iterate on the backend

• madawei2699/codeium — IDE-integrated AI copilot; similar context-aware assistance model but for code editors rather than general screen context
• openai/gpt-4-vision-api-cookbook — Examples of using GPT-4 Vision for screen understanding; Clicky uses ScreenCaptureKit + Claude, so this explores the same 'see the screen' capability with a different LLM
• AssemblyAI/assemblyai-python-sdk — Official AssemblyAI Python SDK; Clicky uses AssemblyAI for STT, so this is the upstream service client library in a different language
• cloudflare/workers-sdk — Wrangler CLI and Worker development framework; Clicky's API proxy layer runs on Cloudflare Workers, so this is the core dev tool and reference
• anthropics/anthropic-sdk-python — Official Anthropic Python SDK; Clicky uses Claude for AI reasoning, so this is the canonical API client (Clicky likely uses Swift bindings or direct HTTP)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for Swift compilation and linting

The repo contains a full Xcode project (leanring-buddy.xcodeproj) but has no CI/CD pipeline. Building and testing the Swift/macOS app on every PR would catch compilation errors early. The file structure shows multiple transcription providers and API integrations that need validation.

• [ ] Create .github/workflows/swift-build.yml with xcodebuild commands for leanring-buddy.xcodeproj
• [ ] Add Swift linting step using SwiftLint (add .swiftlint.yml config)
• [ ] Test that ClaudeAPI.swift, BuddyDictationManager.swift, and transcription providers compile without errors
• [ ] Ensure workflow runs on pushes to main and all PRs

Document API integration requirements in CLAUDE.md and AGENTS.md

The codebase contains ClaudeAPI.swift, AppleSpeechTranscriptionProvider.swift, and AssemblyAIStreamingTranscriptionProvider.swift but the existing CLAUDE.md and AGENTS.md files lack setup instructions. New contributors won't know what API keys or configurations are needed to run the app locally.

• [ ] Expand CLAUDE.md with required Claude API key setup and authentication flow
• [ ] Document AssemblyAI API configuration in AGENTS.md or create SETUP.md
• [ ] Add instructions for AppleSpeechTranscriptionProvider (native vs. cloud providers)
• [ ] Include example .env or configuration file structure for local development
• [ ] Reference specific classes: ClaudeAPI.swift, BuddyTranscriptionProvider.swift

Extract transcription provider implementations into a shared protocol with unit tests

There are three transcription providers (AppleSpeechTranscriptionProvider.swift, AssemblyAIStreamingTranscriptionProvider.swift, BuddyTranscriptionProvider.swift) that likely have duplicated logic and error handling. Creating a common protocol and adding unit tests would improve maintainability and catch regressions.

• [ ] Analyze AppleSpeechTranscriptionProvider.swift, AssemblyAIStreamingTranscriptionProvider.swift, and BuddyTranscriptionProvider.swift for shared interfaces
• [ ] Create TranscriptionProvider.swift protocol defining common methods (start, stop, handle errors)
• [ ] Refactor all three providers to conform to the protocol
• [ ] Add unit tests in Tests/TranscriptionProviderTests.swift covering success/failure cases for each provider
• [ ] Update BuddyAudioConversionSupport.swift to use the unified protocol interface

• Add unit tests for AppleSpeechTranscriptionProvider.swift and AssemblyAIStreamingTranscriptionProvider.swift to verify correct error handling and retry logic when APIs are unavailable (file list shows no Tests/ directory).
• Create a .env.example file and documentation for configuring the Cloudflare Worker locally without secrets (e.g., stub/mock API responses for development), since current README requires production keys.
• Write integration test or checklist for the complete flow: audio capture → transcription → Claude → TTS → playback; currently no test artifacts visible in file list.

• High · Outdated Wrangler Dependency — package.json - devDependencies. The package.json specifies wrangler ^3.0.0, which uses a caret range that may allow installation of versions with known vulnerabilities. No lock file (package-lock.json or yarn.lock) is visible in the repository, creating supply chain risks. Fix: Pin wrangler to a specific version (e.g., 3.X.Y), generate and commit a lock file, and regularly audit dependencies using npm audit or yarn audit.
• High · Potential API Key Exposure in Source Code — leanring-buddy/ClaudeAPI.swift, leanring-buddy/OpenAIAPI.swift, leanring-buddy/ElevenLabsTTSClient.swift, leanring-buddy/AssemblyAIStreamingTranscriptionProvider.swift. Multiple API integration files detected (ClaudeAPI.swift, OpenAIAPI.swift, ElevenLabsTTSClient.swift, AssemblyAIStreamingTranscriptionProvider.swift) without visible .gitignore entries for configuration files. API keys may be hardcoded or accidentally committed. Fix: Ensure all API keys are stored in environment variables or secure configuration files. Add .env, .env.local, and config files to .gitignore. Use Xcode Build Settings or Keychain for sensitive credentials.
• High · Screen Capture and Accessibility Permissions Not Validated — leanring-buddy/CompanionScreenCaptureUtility.swift, leanring-buddy/GlobalPushToTalkShortcutMonitor.swift. Files like CompanionScreenCaptureUtility.swift and GlobalPushToTalkShortcutMonitor.swift suggest the app captures screen content and intercepts keyboard input. No visible permission validation or user consent dialogs in the file structure. Fix: Implement explicit user consent flows for screen recording and accessibility permissions. Request permissions at runtime with clear explanations. Validate permissions before performing sensitive operations.
• Medium · Unencrypted Audio Data Transmission — leanring-buddy/OpenAIAudioTranscriptionProvider.swift, leanring-buddy/AssemblyAIStreamingTranscriptionProvider.swift, leanring-buddy/AppleSpeechTranscriptionProvider.swift. Multiple transcription providers (OpenAIAudioTranscriptionProvider.swift, AssemblyAIStreamingTranscriptionProvider.swift, AppleSpeechTranscriptionProvider.swift) handle audio data. No visible encryption or TLS validation in file names or structure. Fix: Ensure all API communications use TLS 1.2+. Encrypt audio data in transit and at rest. Validate SSL/TLS certificates. Consider end-to-end encryption for sensitive audio.
• Medium · User Data Collection Without Clear Privacy Policy — leanring-buddy/ClickyAnalytics.swift, README.md. ClickyAnalytics.swift suggests analytics collection, and the app captures screen content and audio. No visible privacy policy or data handling documentation in the repository. Fix: Create a comprehensive privacy policy documenting what data is collected, how it's used, and how users can opt-out. Implement analytics consent dialogs. Ensure GDPR/CCPA compliance.
• Medium · Missing Input Validation in LLM Integrations — leanring-buddy/ClaudeAPI.swift, leanring-buddy/OpenAIAPI.swift. ClaudeAPI.swift and OpenAIAPI.swift handle API responses from external LLM services. No visible input sanitization or validation against prompt injection attacks. Fix: Implement strict input validation and sanitization for all LLM responses. Use parameterized API calls where possible. Validate and escape output before displaying to users.
• Medium · Potential Insecure Deserialization — leanring-buddy.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. Package.resolved file suggests use of third-party Swift packages, but no visible dependency verification or integrity checks. Package resolution could be vulnerable to man-in-the-middle attacks. Fix: Pin Swift package versions to specific commits or tags. Verify package checksums. Use private package registries if available. Regularly audit transitive dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.