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/Beingpax/VoiceInk 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 1d ago
• Other licensed
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms
• ⚠ 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 Beingpax/VoiceInk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Beingpax/VoiceInk.

What it runs against: a local clone of Beingpax/VoiceInk — 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 Beingpax/VoiceInk | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "VoiceInk/AppDelegate.swift" \\
  && ok "VoiceInk/AppDelegate.swift" \\
  || miss "missing critical file: VoiceInk/AppDelegate.swift"
test -f "VoiceInk/Recorder.swift" \\
  && ok "VoiceInk/Recorder.swift" \\
  || miss "missing critical file: VoiceInk/Recorder.swift"
test -f "VoiceInk/CoreAudioRecorder.swift" \\
  && ok "VoiceInk/CoreAudioRecorder.swift" \\
  || miss "missing critical file: VoiceInk/CoreAudioRecorder.swift"
test -f "VoiceInk/Models/TranscriptionModelRegistry.swift" \\
  && ok "VoiceInk/Models/TranscriptionModelRegistry.swift" \\
  || miss "missing critical file: VoiceInk/Models/TranscriptionModelRegistry.swift"
test -f "VoiceInk/CursorPaster.swift" \\
  && ok "VoiceInk/CursorPaster.swift" \\
  || miss "missing critical file: VoiceInk/CursorPaster.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/Beingpax/VoiceInk"
  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).

VoiceInk is a native macOS voice-to-text application that transcribes speech to text in real-time using local AI models (Whisper), with zero cloud dependencies and 99% accuracy. It replaces commercial services like Superwhisper and Wispr Flow by running entirely on-device with privacy-first architecture, featuring context-aware AI, global hotkeys, and intelligent app-specific settings via Power Mode. Single-target Xcode project structure: VoiceInk/ contains the main app code organized by feature (CoreAudioRecorder.swift, HotkeyManager.swift, MenuBarManager.swift, HistoryWindowController.swift), Models/ subdirectory holds data structures (AIPrompts.swift), AppIntents/ wraps Shortcuts integration, and Assets.xcassets centralizes UI resources. AppDelegate.swift and AppDefaults.swift manage app lifecycle and user preferences.

macOS users (Sonoma 14.0+) who need fast, private voice dictation without subscriptions; power users in writing-heavy workflows (emails, coding, documentation); developers wanting to build or fork a privacy-focused alternative to commercial voice AI tools.

Active and production-ready: the project recently went open-source after 5 months of dedicated development, has a live website (tryvoiceink.com) with paid licensing tier, and maintains a clear GitHub presence with CI/CD setup (Makefile, .xcscheme). However, the open-source codebase is relatively young; maturity depends on test coverage and contributor activity, which are not visible in the file list.

Single-maintainer risk (Beingpax authored the entire codebase) with GPL v3 license that may limit some commercial fork scenarios. The repo's risk is moderate: it's a consumer app (not infrastructure), so late commits won't break downstream users, but long gaps in maintenance could freeze feature development. Whisper model dependencies and macOS-specific Audio APIs create OS version coupling.

The codebase is in early open-source phase post-initial release; the visible file structure suggests active feature set (custom sounds, clipboard management, mini-recorder, AI context awareness) but specific recent PRs and milestones are not visible in the provided data. BUILDING.md and CONTRIBUTING.md exist, indicating the maintainer is preparing for external contributions.

Clone the repo and build in Xcode: git clone https://github.com/Beingpax/VoiceInk.git && cd VoiceInk && open VoiceInk.xcodeproj. Then use Xcode's build & run (Cmd+R) or the Makefile: make build (Makefile present but commands not detailed in provided snippets). Requires macOS 14.0+ and Xcode with Swift support.

Daily commands: Open VoiceInk.xcodeproj in Xcode and press Cmd+R. Or via Makefile: make build && make run (exact targets unspecified). The app runs as a menu-bar agent with a mini-recorder floating window and history GUI window.

• VoiceInk/AppDelegate.swift — Application entry point and lifecycle manager; establishes menu bar presence, hotkey system, and core recorder initialization.
• VoiceInk/Recorder.swift — Primary voice capture orchestrator; coordinates audio input, transcription, and result delivery—all recording flows depend on this.
• VoiceInk/CoreAudioRecorder.swift — Low-level audio capture using Core Audio framework; handles microphone input buffering and format conversion.
• VoiceInk/Models/TranscriptionModelRegistry.swift — Registry for transcription models (Whisper variants); required to understand how transcription engines are plugged in and selected.
• VoiceInk/CursorPaster.swift — Accessibility framework integration for cursor tracking and text insertion; critical for the main value proposition of voice-to-cursor.
• VoiceInk/HotkeyManager.swift — Global hotkey registration and handling; enables push-to-talk and quick access patterns that drive UX.
• VoiceInk/PowerMode/PowerModeSessionManager.swift — Advanced feature orchestrator managing context-aware transcription sessions across active applications and browser tabs.

Add a new Transcription Model

1. Create a new model definition in TranscriptionModelRegistry.swift following the TranscriptionModel protocol (VoiceInk/Models/TranscriptionModelRegistry.swift)
2. Add model binary or download URL to Resources/models/ directory (VoiceInk/Resources/models/)
3. Register the model in the registry's init() method with unique identifier, name, and language support (VoiceInk/Models/TranscriptionModelRegistry.swift)
4. Update AppDefaults.swift to expose model selection in user preferences if needed (VoiceInk/AppDefaults.swift)

Add a new AI Enhancement Filter

1. Create a new enhancement class conforming to the filter protocol in Services/AIEnhancement/ (VoiceInk/Services/AIEnhancement/AIEnhancementOutputFilter.swift)
2. Implement the transform(text:) method to modify transcription output (VoiceInk/Services/AIEnhancement/AIEnhancementOutputFilter.swift)
3. Register the filter in the Recorder's enhancement pipeline (VoiceInk/Recorder.swift)
4. Add toggle/configuration option in AppDefaults if user-configurable (VoiceInk/AppDefaults.swift)

Add a new Browser for Power Mode

1. Create a new AppleScript file in Resources/ following the pattern (e.g., operaURL.scpt) (VoiceInk/Resources/)
2. Implement getBrowserName() and getBrowserURL() methods in BrowserURLService.swift (VoiceInk/PowerMode/BrowserURLService.swift)
3. Register the browser in BrowserURLService's browser detection switch statement (VoiceInk/PowerMode/BrowserURLService.swift)
4. Test URL extraction and add to Power Mode configuration if context-specific prompts needed (VoiceInk/PowerMode/PowerModeConfig.swift)

Add a new Siri Shortcut Intent

1. Create new Intent struct in AppIntents/ conforming to AppIntent protocol (VoiceInk/AppIntents/)
2. Implement perform() method to trigger desired action (e.g., start recording) (VoiceInk/AppIntents/ToggleMiniRecorderIntent.swift)
3. Register intent in AppShortcuts.swift with title, description, and keyboard shortcut if desired (VoiceInk/AppIntents/AppShortcuts.swift)
4. Call the intent action from AppDelegate or relevant manager to execute behavior (VoiceInk/AppDelegate.swift)

• Swift + SwiftUI — Native macOS development; tight integration with

macOS Sonoma 14.0+ is a hard requirement (stated in README); testing on older systems will fail. The app uses Core Audio APIs directly, so microphone permissions (Privacy > Microphone in System Preferences) must be granted before first use, or the recorder will fail silently. Whisper model files must be downloaded separately (not visible in file list, likely happens at runtime). The Makefile exists but specific targets are not documented; check Makefile directly for build flags. Xcode project may require resolved Swift Package Manager dependencies (Package.resolved present).

• Core Audio API — VoiceInk's CoreAudioRecorder.swift must capture audio from the system microphone using Core Audio; understanding Audio Units, HAL, and ring buffers is critical for debugging audio issues.
• AppKit Menu-Bar Agents — MenuBarManager.swift creates a persistent menu-bar icon and floating window; this is a macOS-specific pattern (not iOS) that requires NSStatusBar, NSPopover, and lifecycle management.
• Global Hotkey Registration (CGEventTap) — HotkeyManager.swift implements push-to-talk via low-level keyboard event capture; CGEventTap requires Accessibility permissions and careful event filtering to avoid consuming system hotkeys.
• Local LLM Inference (Whisper on-device) — VoiceInk runs Whisper models locally rather than calling a cloud API; this trades startup latency and disk space for privacy and offline capability. Understanding model quantization and inference optimization matters for performance tuning.
• macOS App Sandboxing & Entitlements — The app must declare entitlements for Microphone access, Accessibility (for hotkeys), and Pasteboard (for CursorPaster.swift); missing or incorrect entitlements cause runtime permission failures.
• Shortcuts Integration (AppIntents Framework) — AppIntents/ exposes ToggleMiniRecorderIntent and DismissMiniRecorderIntent so users can automate VoiceInk via the Shortcuts app; this is a macOS 12+ pattern replacing deprecated NSUserActivity.
• Context-Aware Prompt Injection — AIPrompts.swift adapts transcription by analyzing screen content (the app or URL in focus); this improves accuracy for domain-specific vocabulary without fine-tuning the Whisper model.

• openai/whisper — The underlying speech-to-text model that VoiceInk wraps; understanding Whisper's architecture and accuracy trade-offs is essential for improving transcription quality.
• soffes/Whisper — Swift bindings for OpenAI Whisper; likely the integration layer VoiceInk uses to call Whisper from native macOS code.
• zzanehip/The-Unarchiver — Similarly structured open-source macOS app; demonstrates patterns for menu-bar agents, sandboxing, and app distribution in the Swift/AppKit ecosystem.
• MonitorControl/MonitorControl — Another menu-bar-resident macOS utility using similar hotkey and preferences patterns; good reference for HotkeyManager and AppDefaults patterns.
• Superwhisper/Superwhisper — The commercial competitor VoiceInk aims to replace; studying its UX and feature set (if open) validates VoiceInk's roadmap.

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 TranscriptionModelRegistry.swift and TranscriptionModel.swift

The Models/ directory contains critical transcription logic (TranscriptionModelRegistry.swift, TranscriptionModel.swift) but there are no visible test files in the repo. These components handle model selection, validation, and transcription execution—core functionality that would benefit from unit tests to prevent regressions and document expected behavior.

• [ ] Create VoiceInkTests/ directory with TranscriptionModelTests.swift
• [ ] Add tests for TranscriptionModelRegistry initialization, model lookup, and fallback behavior
• [ ] Add tests for TranscriptionModel validation and error handling
• [ ] Ensure tests cover edge cases (missing models, invalid configurations)
• [ ] Update Makefile with a 'test' target to run XCTest suite

Add GitHub Actions workflow for macOS builds and code quality checks

The repo has .github/ISSUE_TEMPLATE/ and .github/PULL_REQUEST_TEMPLATE.md but no .github/workflows/ directory with CI/CD automation. A build workflow would catch compilation errors, and a linting workflow would maintain code quality consistency across contributions.

• [ ] Create .github/workflows/build.yml to run 'xcodebuild build' on pull requests targeting macOS 14.0+
• [ ] Add SwiftLint step via GitHub Actions to enforce Swift style guidelines
• [ ] Configure workflow to run on push to main and all pull requests
• [ ] Document the workflow requirements in CONTRIBUTING.md
• [ ] Reference existing Makefile targets in the workflow for consistency

Add integration documentation and examples for AppIntents (AppShortcuts.swift, ToggleMiniRecorderIntent.swift, DismissMiniRecorderIntent.swift)

The AppIntents/ directory shows sophisticated Siri Shortcuts integration (ToggleMiniRecorderIntent, DismissMiniRecorderIntent, AppShortcuts) but there's no dedicated documentation or examples showing users/developers how to use these intents. Adding documentation would improve discoverability and make it easier for contributors to extend this feature.

• [ ] Create docs/APP_INTENTS.md explaining available Siri Shortcuts (toggle mini recorder, dismiss mini recorder)
• [ ] Document required entitlements and Info.plist keys needed for AppIntents
• [ ] Add example screenshots or GIF showing how to add VoiceInk shortcuts to Siri
• [ ] Document how new intents should be added (reference structure in AppIntents/ files)
• [ ] Link APP_INTENTS.md from README.md in a Features section

• Add unit tests for VoiceInk/ClipboardManager.swift and VoiceInk/CursorPaster.swift: these files lack obvious test coverage and are critical for paste-on-transcription logic.
• Document the Makefile targets in BUILDING.md: the Makefile exists but BUILDING.md does not list build, run, or release commands, making it hard for new contributors to understand the build workflow.
• Add a preferences/settings UI window: VoiceInk/AppDefaults.swift centralizes settings but no UI file (like PreferencesViewController.swift) exists to let users configure them; this is a gap vs. commercial competitors.

VoiceInk demonstrates a reasonably secure foundation as an open-source macOS application. The GPL v3 licensing and open-source nature promote transparency. However, there are areas for improvement: (1) No visible automated dependency vulnerability scanning, (2) Missing explicit security policy for responsible disclosure, (3) Lack of documented privacy/security implications for microphone and clipboard access, and (4) No visible evidence of code signing/notarization documentation. The architecture appears sound with proper separation of concerns (CoreAudioRecorder, ClipboardManager, HotkeyManager, etc.), but sensitive operations like clipboard management and audio recording require careful permission handling. Recommend implementing a SECURITY.md policy, automating dependency checks, and explicitly documenting all privacy-sensitive operations.

• Medium · Missing Dependency Lock File Visibility — VoiceInk.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. While Package.resolved exists in the repository, the analysis cannot verify if all Swift Package Manager dependencies are properly pinned and audited. No evidence of dependency vulnerability scanning in the CI/CD pipeline was found in the provided structure. Fix: Ensure all dependencies in Package.resolved are reviewed for known vulnerabilities. Implement automated dependency scanning in CI/CD (e.g., using Dependabot or similar tools). Consider using Swift's built-in security advisories.
• Medium · Potential Hardcoded Configuration in LocalBuild.xcconfig — LocalBuild.xcconfig. The LocalBuild.xcconfig file may contain build-time secrets or sensitive configuration. While this is a build configuration file, it could be committed with sensitive values like API keys or credentials. Fix: Ensure LocalBuild.xcconfig is in .gitignore and never committed with sensitive data. Use environment variables or a separate secrets management system for build-time secrets.
• Low · Missing Security Policy — Repository root. No SECURITY.md file was found in the repository. This makes it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file with responsible disclosure guidelines and contact information for reporting security vulnerabilities.
• Low · Potential Audio/Microphone Permissions Not Explicitly Documented — VoiceInk/CoreAudioRecorder.swift, VoiceInk/Recorder.swift, VoiceInk/Info.plist. The app handles audio recording (CoreAudioRecorder.swift, Recorder.swift) and clipboard operations. macOS requires explicit permissions for microphone access, but no clear documentation of privacy/security implications was visible in provided files. Fix: Ensure Info.plist contains proper NSMicrophoneUsageDescription and other privacy descriptors. Document all privacy-sensitive operations clearly for users. Consider implementing privacy-first design patterns.
• Low · Missing Code Signing Verification Documentation — VoiceInk.xcodeproj/project.pbxproj. As a macOS application, code signing is critical for security. No evidence of code signing or notarization documentation was found. Fix: Implement and document code signing for all macOS releases. Use Apple's notarization service for distribution. Document the signing process in BUILDING.md or a dedicated security guide.

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.