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/leetcode-mafia/cheetah 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.

AVOID — Looks unmaintained — solo project with stale commits

• CC0-1.0 licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ 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 leetcode-mafia/cheetah repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/leetcode-mafia/cheetah.

What it runs against: a local clone of leetcode-mafia/cheetah — 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 leetcode-mafia/cheetah | Confirms the artifact applies here, not a fork | | 2 | License is still CC0-1.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 510 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of leetcode-mafia/cheetah. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/leetcode-mafia/cheetah.git
#   cd cheetah
#
# 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 leetcode-mafia/cheetah and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC0-1\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC0-1\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC0-1.0" \\
  || miss "license drift — was CC0-1.0 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"

# 4. Critical files exist
test -f "Cheetah/CheetahApp.swift" \\
  && ok "Cheetah/CheetahApp.swift" \\
  || miss "missing critical file: Cheetah/CheetahApp.swift"
test -f "Cheetah/OpenAIExecutor.swift" \\
  && ok "Cheetah/OpenAIExecutor.swift" \\
  || miss "missing critical file: Cheetah/OpenAIExecutor.swift"
test -f "LibWhisper/WhisperStream.swift" \\
  && ok "LibWhisper/WhisperStream.swift" \\
  || miss "missing critical file: LibWhisper/WhisperStream.swift"
test -f "CheetahIPC/Server.swift" \\
  && ok "CheetahIPC/Server.swift" \\
  || miss "missing critical file: CheetahIPC/Server.swift"
test -f "Cheetah/ConversationAnalyzer.swift" \\
  && ok "Cheetah/ConversationAnalyzer.swift" \\
  || miss "missing critical file: Cheetah/ConversationAnalyzer.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 510 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~480d)"
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/leetcode-mafia/cheetah"
  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).

Cheetah is a native macOS app that provides real-time AI coaching for software engineering interviews by transcribing audio locally via whisper.cpp and generating hints/solutions using GPT-4 via OpenAI API. It integrates with live coding platforms through a Firefox browser extension to analyze code and interview performance in real-time. Monolithic Swift app: Cheetah/ contains the main macOS UI (Views/ with SwiftUI components), backend logic (OpenAIExecutor.swift, ConversationAnalyzer.swift, PromptGenerator.swift, ModelDownloader.swift), and audio integration. CheetahIPC/ is a separate module for inter-process communication (Client.swift, Server.swift, Messages.swift). ExtensionHelper/ is a small XPC helper. The browser extension lives in a separate ./extension/ directory (not shown in file list but referenced in README).

Software engineers preparing for technical interviews who want real-time coaching during mock interview sessions. Users need a Mac with Apple silicon, an OpenAI API key, and optionally a Firefox browser to use the code analysis feature.

Early-stage but actively maintained: the repo shows recent CI/CD setup (build.yml, release.yml workflows), clean Xcode project structure, and documented prerequisites, but the disclaimer warns that the app may generate incorrect solutions. There's no visible test suite in the file list, suggesting pre-1.0 maturity. The tight integration with external services (Whisper, GPT-4, Firefox extension) and Apple-only platform constraint limits its audience.

Significant dependency on OpenAI API pricing and availability—every user action costs money. Requires whisper.cpp to be manually checked out at ../whisper.cpp (non-standard, fragile), and tight coupling to Apple silicon Macs makes it unmaintainable on other platforms. No visible test coverage and single-maintainer risk (leetcode-mafia org, but limited contributor history visible). The entitlements model (Cheetah.entitlements, ExtensionHelper.entitlements) suggests complex sandbox/IPC setup that could break on macOS updates.

Recent work focuses on release automation (release.yml exists) and build stability (build.yml for CI). The Sparkle.swift file suggests in-app update mechanism is implemented. No specific PRs or issues visible in the file list, but the project README mentions it works with Whisper and GPT-4, indicating active use of these APIs.

Clone the repo, install SDL2, check out whisper.cpp in ../whisper.cpp, then build via Xcode:

git clone https://github.com/leetcode-mafia/cheetah.git
cd cheetah
brew install sdl2
git clone https://github.com/ggerganov/whisper.cpp.git ../whisper.cpp
open Cheetah.xcodeproj

Then build & run in Xcode (⌘B to build, ⌘R to run). Requires macOS 13.1+, Apple silicon Mac, and an OpenAI API key to be set in the app.

Daily commands: Open Cheetah.xcodeproj in Xcode, ensure whisper.cpp is at ../whisper.cpp, then Cmd+R. The app will prompt for OpenAI API key on first launch. Select audio input device and hit 'Answer', 'Refine', or 'Analyze' buttons in CoachView.swift.

• Cheetah/CheetahApp.swift — Main app entry point and lifecycle manager; sets up the macOS application window and integrates all core systems (audio capture, AI coaching, browser extension communication).
• Cheetah/OpenAIExecutor.swift — Handles all GPT-4 API calls for generating hints and solutions; core AI interaction logic that drives the coaching experience.
• LibWhisper/WhisperStream.swift — Bridges local Whisper speech-to-text with the macOS audio capture pipeline; critical for real-time transcription that feeds the coaching system.
• CheetahIPC/Server.swift — Inter-process communication server that enables the browser extension to send interview context and receive AI responses from the macOS app.
• Cheetah/ConversationAnalyzer.swift — Analyzes transcribed conversation history to provide contextual coaching hints; bridges raw transcription with intelligent prompt generation.
• Cheetah/PromptGenerator.swift — Constructs structured prompts for GPT-4 based on interview context and conversation state; determines quality and relevance of AI coaching.
• Cheetah/BrowserExtension.swift — Manages communication with the browser extension and LeetCode integration; enables app to understand which problem is being solved.

Add a new AI coaching prompt strategy

1. Create a new analysis function in ConversationAnalyzer.swift that extracts specific problem domain patterns (e.g., dynamic programming hints vs. graph traversal hints). (Cheetah/ConversationAnalyzer.swift)
2. Add a new prompt template method in PromptGenerator.swift that calls your analyzer and formats the coaching request. (Cheetah/PromptGenerator.swift)
3. Wire the new prompt generator into OpenAIExecutor.swift by adding a case to the request switch logic. (Cheetah/OpenAIExecutor.swift)
4. Update CoachView.swift to display the new coaching response format if it differs from existing hints. (Cheetah/Views/CoachView.swift)

Add support for a new coding platform (not LeetCode)

1. Create a new JavaScript file in the extension/ directory following the pattern of cheetah.js, with DOM selectors for the target platform. (extension/cheetah.js)
2. Register the new extension manifest with updated content_scripts and host_permissions. (extension/manifest.json)
3. Extend BrowserExtension.swift to parse the new platform's problem metadata format and normalize it to the existing Cheetah message protocol. (Cheetah/BrowserExtension.swift)
4. Add platform-specific message type in CheetahIPC/Messages.swift if needed, or reuse existing structure. (CheetahIPC/Messages.swift)

Integrate a custom local LLM instead of OpenAI GPT-4

1. Create a new file (e.g., LocalLLMExecutor.swift) that wraps your local model inference (e.g., llama.cpp or equivalent). (Cheetah/OpenAIExecutor.swift)
2. Implement the same streaming/completion interface as OpenAIExecutor to maintain compatibility with PromptGenerator. (Cheetah/OpenAIExecutor.swift)
3. Update ContentView.swift and AuthTokenView.swift to remove or conditionally hide the OpenAI API key input when using local model. (Cheetah/Views/ContentView.swift)
4. Refactor the coach response handling in CoachView.swift to work with both remote and local inference. (Cheetah/Views/CoachView.swift)

• SwiftUI + macOS native — Tight OS integration for microphone permissions, window management, and browser extension communication via local IPC; native app provides better UI responsiveness and system resource access than cross-platform alternatives.
• Whisper.cpp (local speech-to-text) — Runs inference on-device (no API calls), reducing latency and privacy concerns; offline-capable for edge cases; leverages Apple Silicon for fast transcription.
• GPT-4 API (OpenAI) — Provides state-of-the-art conversational intelligence for generating hints and solutions; streaming responses allow real-time feedback without blocking the UI.
• Browser extension (JavaScript + manifest v3) — Seamless integration with LeetCode; injects problem context directly into the interview environment without requiring user copy-paste workflows.
• Local IPC (Unix domain sockets or similar) — Secure, fast communication between browser extension and macOS app without exposing API keys or conversation data to the internet; avoids network overhead.

• macOS-only app (not cross-platform)

  • Why: Simplifies implementation by leveraging Apple Silicon and native APIs (Whisper.cpp, SwiftUI, system audio APIs); avoids complexity of Electron or cross-platform frameworks.
  • Consequence: Linux and Windows users cannot use Cheetah; reduces addressable market but improves product fit for Mac users.

• Requires external OpenAI API key (no backend service)

  • Why: Avoids building and maintaining a backend; users retain control and privacy of their data; reduces operational overhead.
  • Consequence: Users must pay OpenAI directly and manage API quotas; single point of failure if OpenAI API goes down; no server-side analytics or session persistence.

• Whisper.cpp runs locally (not remote API call)

  • Why: Reduces latency and network calls; transcription happens offline; privacy-preserving (audio never leaves the device).
  • Consequence: Requires significant local compute; slower on older Macs; larger app bundle; model download on first run.

• Real-time streaming UI with coach hints vs. batch processing

  • Why: Streaming provides immediate feedback during live interviews; better U
  • Consequence: undefined

1. whisper.cpp must be cloned to ../whisper.cpp (sibling directory of repo root), not inside the repo—build will fail silently if path is wrong. 2. SDL2 must be installed via Homebrew; building without it will cause linker errors. 3. Running in Xcode Debug mode makes audio transcription extremely slow (mentioned in README); use Release build for real use. 4. OpenAI API key must be provided in the UI; there's no .env file or config file support visible. 5. Browser extension only works with Firefox (not Chrome/Safari); requires manual manifest.json editing and about:debugging setup. 6. The app uses XPC and entitlements (Cheetah.entitlements), which may break if notarization or sandboxing settings change on new macOS versions.

• Whisper (OpenAI speech-to-text) — Cheetah's core capability: local, real-time audio transcription without sending raw audio to a server. Understanding Whisper's accuracy, latency, and model variants (tiny/base/small/medium/large) is critical for performance tuning.
• XPC (inter-process communication on macOS) — CheetahIPC module uses XPC to communicate between the main app and the browser extension; required for code-from-browser analysis feature. Security model is critical.
• SwiftUI and AppKit integration — Cheetah mixes SwiftUI (Views/) with AppKit components (NSTextFieldWrapper.swift, RSDimensionHuggingTextField.swift); understanding bridging is essential for UI changes.
• Prompt engineering for LLMs — PromptGenerator.swift constructs prompts sent to GPT-4; small changes in prompt wording dramatically affect answer quality and cost. Understanding few-shot learning and chain-of-thought is critical.
• macOS app code signing and notarization — Cheetah uses entitlements (Cheetah.entitlements) and XPC, which require proper code signing and Apple notarization for distribution. Breaking these will prevent users from running the app.
• Audio input capture and loopback routing — ModelDownloader.swift and audio integration require understanding macOS audio device APIs. The README recommends BlackHole for loopback to capture both sides of an interview call; this is non-trivial setup.
• Firefox WebExtensions API — Browser extension communicates with the main app via the CheetahIPC protocol to send code snippets for analysis. Understanding manifest.json, content scripts, and the messaging API is required to extend platform support (e.g., Chrome).

• ggerganov/whisper.cpp — Direct dependency: Cheetah vendors whisper.cpp for local audio-to-text; understanding its C++ API is essential for audio pipeline changes.
• openai/whisper — The original Python Whisper model that whisper.cpp ports; useful for understanding model capabilities and accuracy trade-offs.
• openai/gpt-4 — The core AI backend Cheetah calls via API; knowledge of prompt engineering and token limits affects OpenAIExecutor.swift design.
• leetcode-mafia/interview-handbook — Companion repo from same org containing interview prep materials that Cheetah could surface as prompts or coaching hints.
• ExistentialAudio/BlackHole — Audio loopback driver explicitly recommended in README for capturing both sides of interview conversation; users must install separately.

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 unit tests for OpenAISwift and ConversationAnalyzer modules

The repo lacks test coverage for critical AI integration logic. OpenAISwift/OpenAISwift.swift handles API communication and ConversationAnalyzer.swift processes interview responses. These are high-risk components that would benefit from unit tests to catch regressions when updating OpenAI API versions or conversation logic.

• [ ] Create Tests/OpenAISwiftTests.swift with tests for ChatMessage parsing and API endpoint construction
• [ ] Create Tests/ConversationAnalyzerTests.swift with tests for hint generation logic and response evaluation
• [ ] Add XCTest target to Cheetah.xcodeproj/project.pbxproj
• [ ] Integrate test execution into .github/workflows/build.yml

Add integration test workflow for whisper.cpp dependency setup

The README states 'whisper.cpp must be checked out in ../whisper' but there's no automated validation. New contributors often struggle with this setup. A GitHub Actions workflow should verify the whisper.cpp dependency is properly configured and the build succeeds with it present.

• [ ] Create .github/workflows/test-whisper-integration.yml
• [ ] Add step to clone whisper.cpp into ../whisper directory
• [ ] Build the Cheetah project with the dependency present
• [ ] Add documentation to README.md with the exact clone command and expected directory structure

Extract and document LibWhisper C++ bridge API in LibWhisper/LibWhisper.h

LibWhisper.h is a thin wrapper around whisper.cpp (stream.cpp/stream.h) but lacks inline documentation. The public C API for audio capture and transcription is unclear. Adding detailed header documentation would help contributors extend audio processing or debug integration issues.

• [ ] Document each function in LibWhisper/LibWhisper.h with parameter descriptions and return value semantics
• [ ] Add inline comments to LibWhisper/stream.h explaining the audio buffer management and whisper inference pipeline
• [ ] Create LibWhisper/README.md explaining the C++ bridge layer, audio device enumeration, and stream lifecycle
• [ ] Document the SDL.h dependency and why it's needed for CaptureDevice.swift

• Add unit tests for PromptGenerator.swift: the prompt templates are critical to answer quality but there's no visible test file. Create Tests/PromptGeneratorTests.swift with test cases for different question types (arrays, trees, strings).
• Document the OpenAI API key setup flow: users see no clear error message if API key is missing/invalid. Add validation in AuthTokenView.swift and surface helpful error messages (check actual implementation).
• Add Safari browser extension support: README only mentions Firefox. The extension is in ./extension/ (not in file list), so research whether Safari's WebExtensions API is compatible and add a manifest-safari.json if feasible.

• High · Missing API Key Validation and Storage — Cheetah/Views/AuthTokenView.swift, Cheetah/OpenAIExecutor.swift. The application requires users to provide their own OpenAI API key for functionality. The file 'AuthTokenView.swift' suggests the app handles API credentials. Without seeing the implementation, there's a significant risk that API keys could be stored insecurely in plaintext, transmitted without encryption, or logged inadvertently. Fix: Implement secure credential storage using macOS Keychain API. Never store API keys in UserDefaults, config files, or log output. Use encrypted storage for any sensitive credentials. Implement certificate pinning for API communications.
• High · Unvalidated External Process Execution — LibWhisper/stream.cpp, LibWhisper/WhisperStream.swift, Build configuration. The application depends on 'whisper.cpp' which must be checked out externally in '../whisper'. This external dependency is compiled and executed locally. There's risk of supply chain attack, unauthorized modifications, or execution of malicious code if the dependency source is compromised or if integrity validation is not performed. Fix: Implement integrity verification (code signing, hash validation) for the whisper.cpp dependency. Pin specific versions/commits. Verify GPG signatures if available. Consider vendoring the dependency directly in the repository rather than requiring external checkout.
• High · Browser Extension Security Risks — extension/manifest.json, extension/cheetah.js, extension/background.js, Cheetah/BrowserExtension.swift. The codebase includes a browser extension ('extension/manifest.json', 'extension/background.js', 'extension/cheetah.js') that likely interacts with web pages and collects information. Browser extensions have elevated privileges and can access sensitive data. No visible Content Security Policy or input validation patterns detected in the file structure. Fix: Implement strong Content Security Policy in manifest.json. Validate and sanitize all user input and data from web pages. Use secure communication protocols between extension and main app. Implement proper permission scoping. Avoid eval() or dangerous dynamic code execution. Add comprehensive input validation for intercepted data.
• Medium · Inter-Process Communication (IPC) Security — CheetahIPC/Client.swift, CheetahIPC/Server.swift, CheetahIPC/Messages.swift. The CheetahIPC module (Client.swift, Server.swift, Messages.swift) handles communication between the main app, extension, and ExtensionHelper. Without visible authentication/authorization mechanisms, there's potential for unauthorized inter-process message injection or replay attacks. Fix: Implement message authentication codes (HMAC) for all IPC messages. Add cryptographic signatures to ensure message origin verification. Implement nonce-based replay attack prevention. Validate message structure and types strictly. Use a well-vetted IPC framework rather than custom implementation if possible.
• Medium · Unencrypted Audio Stream Processing — LibWhisper/CaptureDevice.swift, LibWhisper/stream.cpp, LibWhisper/WhisperStream.swift. The application captures and processes audio from the user's microphone (LibWhisper/CaptureDevice.swift) and transcribes it using whisper.cpp. If audio is cached, logged, or transmitted without encryption, sensitive interview information could be exposed. Fix: Ensure audio streams are processed in-memory only without disk caching. Implement encryption for any persisted audio data. Sanitize logs to exclude audio content. Clear audio buffers immediately after processing. Implement secure deletion of temporary files.
• Medium · Missing Entitlements Validation — Cheetah/Cheetah.entitlements, ExtensionHelper/ExtensionHelper.entitlements. The application uses entitlements files (Cheetah.entitlements, ExtensionHelper.entitlements) but without viewing their contents, there's risk of over-privileged entitlements being requested, enabling capabilities not necessary for core functionality. Fix: Follow principle of least privilege - request only necessary entitlements. Review and justify each entitlement requested. Document why each entitlement is needed. Regularly audit requested permissions against actual functionality. Remove any unused entitlements.
• Medium · Prompt Injection Risk via User Input — undefined. The PromptGenerator.swift and ConversationAnalyzer.swift files suggest the app processes user input (interview questions/transc Fix: undefined

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.