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/jacklandrin/OnlySwitch 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.

GO — Healthy across all four use cases

• Last commit 6w ago
• 5 active contributors
• MIT licensed
• Tests present
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ No CI workflows 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 jacklandrin/OnlySwitch repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jacklandrin/OnlySwitch.

What it runs against: a local clone of jacklandrin/OnlySwitch — 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 jacklandrin/OnlySwitch | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 71 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jacklandrin/OnlySwitch(\\.git)?\\b" \\
  && ok "origin remote is jacklandrin/OnlySwitch" \\
  || miss "origin remote is not jacklandrin/OnlySwitch (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"

# 4. Critical files exist
test -f "Modules/Package.swift" \\
  && ok "Modules/Package.swift" \\
  || miss "missing critical file: Modules/Package.swift"
test -f "Modules/Sources/OnlyAgent/AgentCommand.swift" \\
  && ok "Modules/Sources/OnlyAgent/AgentCommand.swift" \\
  || miss "missing critical file: Modules/Sources/OnlyAgent/AgentCommand.swift"
test -f "Modules/Sources/Defines/NotificationNames.swift" \\
  && ok "Modules/Sources/Defines/NotificationNames.swift" \\
  || miss "missing critical file: Modules/Sources/Defines/NotificationNames.swift"
test -f "Modules/Sources/Extensions/KeychainManager.swift" \\
  && ok "Modules/Sources/Extensions/KeychainManager.swift" \\
  || miss "missing critical file: Modules/Sources/Extensions/KeychainManager.swift"
test -f "Modules/Sources/Networking/GitHub/GitHubInteractor.swift" \\
  && ok "Modules/Sources/Networking/GitHub/GitHubInteractor.swift" \\
  || miss "missing critical file: Modules/Sources/Networking/GitHub/GitHubInteractor.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 71 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~41d)"
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/jacklandrin/OnlySwitch"
  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).

OnlySwitch is a SwiftUI-based macOS menu bar app that provides a unified control panel for system toggles (dark mode, hide notch, AirPods, screen saver, low power mode, night shift, etc.) and allows importing and executing macOS Shortcuts from a single menu bar icon. It reduces menu bar clutter by consolidating dozens of independent system controls into one all-in-one switch with keyboard shortcut support and widget integration (macOS Sonoma+). SPM-based modular structure: Modules/Package.swift defines a reusable Swift package containing Defines/ (SwitchError, UnitType, notifications), Design/ (AppKitProgressView, SecureInputView), Extensions/ (64+ extensions for AppKit/SwiftUI helpers like KeychainManager, NSImage++), and Networking/ (GitHub integration for releases). Main app code resides in root OnlySwitch/ with assets in Assets.xcassets/. Localization centralized in Localization/Localizable.xcstrings.

macOS users who want to streamline their menu bar and quickly toggle system features without cluttering the status bar; contributes welcome from Swift developers familiar with AppKit/SwiftUI integration and system-level macOS automation.

Actively developed and production-ready. Currently at v2.5.6+ with 908KB Swift codebase, published on Homebrew, supports latest macOS (Tahoe), has migrated past auto-update issues (2.5.6 and below), and demonstrates feature velocity (widgets added in 2.5.0, keyboard shortcuts in 2.0, Shortcuts integration in 1.7). Single maintainer (jacklandrin) with visible release cadence.

Single-maintainer project (jacklandrin) with no visible CI/CD pipeline (.github has issue templates but no Actions workflows shown) creates bus-factor risk. Dependency on system-level APIs (AirPods, notch handling, low-power-mode requiring password) means OS updates can break features without warning. Known issue flagged: 'exist some issues' with hide notch feature and auto-update broken below v2.5.6.

Project tracks issues via GitHub templates (bug_report.md, feature_request.md) and accepts community Shortcuts contributions (ShortcutsGalleryContributing.md). Recent focus: widget support (v2.5.0+), keyboard shortcuts, and Only Control appearance redesign (v2.5.4). Active Telegram and Discord communities suggest ongoing user feedback loop.

git clone https://github.com/jacklandrin/OnlySwitch.git
cd OnlySwitch
open OnlySwitch.xcodeproj

Then build in Xcode (⌘B) or install via Homebrew: brew install only-switch.

Daily commands: Open OnlySwitch.xcodeproj in Xcode and press ⌘R to run. The app launches as a background menu bar app; no dev server. Build scheme is OnlySwitch (not OnlyAgent which is a companion daemon in Modules/).

• Modules/Package.swift — SPM package definition for the shared module library; all features depend on this module structure
• Modules/Sources/OnlyAgent/AgentCommand.swift — Core AI agent command execution framework; implements the primary autonomous task-execution paradigm
• Modules/Sources/Defines/NotificationNames.swift — Central event notification registry; enables loose coupling between menu bar switches and system observers
• Modules/Sources/Extensions/KeychainManager.swift — Unified credential storage abstraction; required for API key management across all AI model providers
• Modules/Sources/Networking/GitHub/GitHubInteractor.swift — GitHub API orchestration layer; handles release checking and version management for auto-updates
• Modules/Sources/OnlyAgent/Planning/TaskPlanner.swift — AI task decomposition engine; converts user intent into executable step sequences
• Modules/Sources/OnlyAgent/Execution/StepExecutor.swift — Step-by-step execution runtime; orchestrates AppleScript and system commands during agent execution

Add a new AI model provider (e.g., Anthropic Claude)

1. Create provider-specific settings folder: Modules/Sources/OnlyAgent/Settings/ClaudeSettings/ (Modules/Sources/OnlyAgent/Settings/GeminiSettings/ (reference structure))
2. Implement ClaudeService.swift with HTTP client following GeminiService.swift pattern (Modules/Sources/OnlyAgent/Settings/GeminiSettings/GeminiService.swift)
3. Create ClaudeSettingReducer.swift and ClaudeSettingView.swift for UI configuration (Modules/Sources/OnlyAgent/Settings/GeminiSettings/GeminiSettingReducer.swift)
4. Add provider enum case to ModelTool.swift and update ModelProviderService.swift factory (Modules/Sources/OnlyAgent/Settings/ModelProviderService.swift)
5. Store API key using KeychainManager following existing pattern (Modules/Sources/Extensions/KeychainManager.swift)

Add a new system toggle switch (e.g., Bluetooth, WiFi)

1. Define notification names for toggle state changes (Modules/Sources/Defines/NotificationNames.swift)
2. Create a new switch controller implementing StateObserver pattern (Modules/Sources/OnlyAgent/Observation/StateObserver.swift)
3. Add AppleScript execution logic in TaskPlanner or StepExecutor (Modules/Sources/OnlyAgent/Execution/StepExecutor.swift)
4. Register toggle UI in menu bar view (create or extend existing view) (Modules/Sources/Design/AppKitProgressView.swift)
5. Update system prompts to instruct AI agent how to control new toggle (Modules/Sources/OnlyAgent/Settings/AppleScriptSystemPrompt.swift)

Add a new AI-powered automation task (e.g., email scheduling)

1. Define task intent and decomposition logic in TaskPlanner (Modules/Sources/OnlyAgent/Planning/TaskPlanner.swift)
2. Add execution steps to ExecutionStep enum and implement in StepExecutor (Modules/Sources/OnlyAgent/Execution/ExecutionStep.swift)
3. Create AppleScript templates or system commands for the task (Modules/Sources/OnlyAgent/Settings/AppleScriptSystemPrompt.swift)
4. Add UI dialogue view for task parameters (reference PromptDialogueView) (Modules/Sources/OnlyAgent/Dialogue/PromptDialogueView.swift)
5. Handle state observation and error cases via StateObserver (Modules/Sources/OnlyAgent/Observation/StateObserver.swift)

Extend API credential storage or add a new secure field

1. Define new KeychainStorageKey enum case (Modules/Sources/Extensions/KeychainStorageKey.swift)
2. Add getter/setter methods in KeychainManager following existing pattern (Modules/Sources/Extensions/KeychainManager.swift)
3. Update UserDefaults keys if non-sensitive metadata is needed (Modules/Sources/Extensions/UserDefaultsKeys.swift)
4. Create or update SecureInputView for UI credential entry (Modules/Sources/Design/SecureInputView.swift)
5. Add migration logic if upgrading from plaintext storage (Modules/Sources/Extensions/KeychainMigration.swift)

Keychain storage: Credentials stored via KeychainManager require matching Team ID on code-sign; mismatches silently fail. Low power mode toggle: Requires user password input (flagged as limitation in feature table). Notch hiding: Known buggy behavior (README flags 'exist some issues'). Auto-update migration: v2.5.6 and below have broken auto-update; users must manually update or use Homebrew. Global keyboard shortcuts: NSEvent++ hooking requires Accessibility permissions at runtime; no explicit permission request code visible. Widget deployment: Sonoma+ requirement not enforced in build; older OS targets will silently skip widget features.

• AppKit Menu Bar Integration (NSStatusBar) — OnlySwitch lives as a persistent menu bar icon; understanding NSStatusBar, NSStatusBarButton, and NSMenu lifecycle is fundamental to the entire architecture.
• Global Keyboard Event Interception (NSEvent.addLocalMonitorForEvents) — Keyboard shortcuts feature (v2.0+) requires hooking system-wide key events; NSEvent++.swift uses this to enable global hotkey support without requiring front-window focus.
• Keychain Item Synchronization & Migration — KeychainManager.swift and KeychainMigration.swift handle secure credential storage and v1→v2 data migration; critical for switches requiring password authentication.
• SwiftUI + AppKit Bridging (NSViewRepresentable) — OnlySwitch uses hybrid SwiftUI (primary UI) + AppKit (system integration); AppKitProgressView.swift and SecureInputView.swift demonstrate wrapping AppKit views in SwiftUI.
• AppleScript/OSA Integration via NSAppleEventDescriptor — System commands (e.g., dark mode toggle) often require AppleScript execution; NSAppleEventDescriptor++.swift bridges Swift → AppleScript for low-level macOS automation.
• Swift Package Manager (SPM) Modularization — Modules/Package.swift encapsulates reusable code (extensions, defines, design components) separately from the main app; critical for code organization and widget reuse.
• macOS Widgets & WidgetKit (Sonoma+) — v2.5.0+ adds widget support allowing switches to appear on Lock Screen/Desktop; requires WidgetKit integration separate from main app UI.

• Mach1/stats — Similar menu bar system monitor/control app; cross-reference for menu bar UI patterns and system API usage.
• MonitorControl/MonitorControl — Menu bar app for external monitor brightness/volume control; shares AppKit menu bar integration and system command execution patterns.
• Homebrew/homebrew-cask — OnlySwitch is packaged here; understanding cask formula format important for Homebrew distribution and auto-update strategy.
• Apple/swift-package-manager — OnlySwitch uses SPM for Modules/ library; reference for Package.swift manifest and dependency resolution patterns.
• jacklandrin/OnlySwitch-Widgets — Likely companion repo for widget development (if it exists); would contain WidgetKit integration separate from main app.

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 Extensions Module (Modules/Sources/Extensions/)

The Extensions directory contains 20+ utility extensions (KeychainManager, NSImage++, String++, etc.) but no test coverage. These are critical utility functions used throughout the app. Adding unit tests would improve code reliability and make refactoring safer, especially for security-sensitive code like KeychainManager and KeychainMigration.

• [ ] Create Modules/Tests/ExtensionsTests/ directory structure
• [ ] Add tests for KeychainManager.swift and KeychainMigration.swift (security-critical)
• [ ] Add tests for String++ and Array++ utility extensions
• [ ] Add tests for NSImage++ image processing functions
• [ ] Integrate tests into Modules/Package.swift test target
• [ ] Add GitHub Action workflow in .github/workflows/ to run tests on PR

Add GitHub Actions CI Workflow for SwiftUI Builds

The repo has FUNDING.yml and issue templates but no CI/CD pipeline. Given the macOS (Tahoe) platform requirement and SwiftUI UI framework, a build verification workflow would catch compilation errors early. This is crucial for a user-facing menubar app with multiple features (NotchDrop, dark mode, AirPods, Shortcuts).

• [ ] Create .github/workflows/build.yml for macOS builds using xcodebuild
• [ ] Configure workflow to build the main OnlySwitch app and OnlyAgent module
• [ ] Add SwiftFormat/SwiftLint checks to enforce code style consistency
• [ ] Trigger workflow on pull_request to main branch
• [ ] Add build status badge to README.md

Document OnlyAgent Module Architecture and Execution Flow

The Modules/Sources/OnlyAgent/ directory contains complex functionality (PromptDialogueReducer, StepExecutor, ErrorHandler) suggesting an AI agent system, but there's no architectural documentation. A CONTRIBUTING.md file exists but lacks OnlyAgent-specific details. New contributors need clear guidance on the dialogue, execution, and command flow.

• [ ] Create Modules/Sources/OnlyAgent/README.md documenting the agent architecture
• [ ] Add sequence diagrams or flowcharts for PromptDialogueReducer state management
• [ ] Document StepExecutor and ExecutionStep patterns with examples
• [ ] Update EvolutionGalleryContributing.md with OnlyAgent-specific contribution guidelines
• [ ] Add inline code documentation to Modules/Sources/OnlyAgent/Execution/StepExecutor.swift and PromptDialogueService.swift

• Add unit tests for Modules/Sources/Extensions/ (64 extension files have no visible test coverage); start with KeychainManager.swift or String++.swift to establish test structure.
• Implement CI/CD workflow: create .github/workflows/build.yml to run xcodebuild test on push; currently no GitHub Actions present despite issue templates existing.
• Document the Shortcuts Gallery contribution process more clearly: expand ShortcutsGalleryContributing.md with step-by-step screenshots and CommonJS examples of what a valid Shortcut export looks like.

OnlySwitch is a macOS menu bar application with moderate security posture. The codebase shows good architectural separation with dedicated modules for extensions, networking, and security features. However, several areas require verification: (1) Keychain implementation details for credential storage, (2) Network communication security with potential need for certificate pinning, (3) Proper memory handling in SecureInputView for sensitive data, and (4) API key management across multiple AI model providers. The absence of visible dependency files and detailed implementation review suggests these vulnerabilities are potential rather than confirmed. The MIT license and public repository are appropriate for an open-source tool. No obvious hardcoded secrets, SQL injection risks, or Docker infrastructure issues were identified in the file structure analysis.

• Medium · Keychain Manager Implementation Requires Security Review — Modules/Sources/Extensions/KeychainManager.swift, Modules/Sources/Extensions/KeychainMigration.swift. The codebase contains KeychainManager.swift and KeychainMigration.swift files that handle credential storage. Without reviewing the actual implementation, there's a risk of improper keychain usage patterns such as insufficient access control attributes, missing entitlements validation, or insecure data serialization. Fix: Review keychain implementation to ensure: 1) Proper kSecAttrAccessible attributes are set (preferably kSecAttrAccessibleWhenUnlockedThisDeviceOnly), 2) Sensitive data is not logged, 3) Keychain queries use appropriate error handling, 4) The app has proper entitlements configured
• Medium · Network Communication Security — Modules/Sources/Networking/GitHub/, Modules/Sources/Networking/ModelProvider/. The codebase includes GitHub API integration and ModelProvider networking components. Without visible certificate pinning or strict transport security configuration, there's a potential risk of man-in-the-middle attacks on API communications. Fix: Implement certificate pinning for API communications, ensure all network requests use HTTPS, validate SSL/TLS certificates, and consider implementing App Transport Security (ATS) strictest settings in Info.plist
• Medium · User Input in SecureInputView — Modules/Sources/Design/SecureInputView.swift. SecureInputView.swift is designed for secure input handling (likely passwords/tokens), but implementation details are not visible. Risk exists for improper memory handling, clipboard exposure, or lack of input sanitization. Fix: Verify that: 1) Input is cleared from memory after use, 2) Clipboard interactions are minimized and cleared, 3) Sensitive data is not logged, 4) Proper text field masking is implemented, 5) No unencrypted persistence occurs
• Low · AppleEvent Descriptor Usage — Modules/Sources/Extensions/NSAppleEventDescriptor.swift. The NSAppleEventDescriptor extension may be used for inter-process communication. AppleEvent usage requires careful validation to prevent code injection through malformed events. Fix: Validate all AppleEvent parameters before processing, use proper type checking, avoid eval-like functionality, and sanitize any external AppleEvent data
• Low · Third-Party AI Model Integration — Modules/Sources/OnlyAgent/, Modules/Sources/Networking/ModelProvider/. OnlyAgent module integrates multiple AI providers (OpenAI, Gemini, Ollama, Codex) with API key management. Risk of API key exposure in logs, memory, or insecure storage. Fix: Ensure API keys are stored exclusively in Keychain, never logged or cached in plaintext, implement request signing where possible, use environment-specific keys, and consider implementing request rate limiting
• Low · Missing CODEOWNERS File Review — CODEOWNERS. CODEOWNERS file exists but content is not visible. This file controls who can approve security-relevant changes. Fix: Ensure CODEOWNERS file specifies security-conscious reviewers for sensitive areas like Keychain, Networking, and OnlyAgent modules

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.