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/tombonez/noTunes 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 — Stale — last commit 2y ago

• 7 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 76% of 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 tombonez/noTunes repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tombonez/noTunes.

What it runs against: a local clone of tombonez/noTunes — 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 tombonez/noTunes | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 669 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tombonez/noTunes(\\.git)?\\b" \\
  && ok "origin remote is tombonez/noTunes" \\
  || miss "origin remote is not tombonez/noTunes (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master 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 669 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~639d)"
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/tombonez/noTunes"
  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).

noTunes is a lightweight macOS menu bar application written in Swift that intercepts and blocks iTunes or Apple Music from launching, with the ability to redirect launch attempts to an alternative music app. It runs as a persistent background process (typically started at login) and prevents unwanted music app launches—particularly useful when Bluetooth headphones reconnect and trigger automatic app startup. Minimal Xcode project structure: single-view Swift app with AppDelegate.swift as the core entry point, XIB-based UI (MainMenu.xib for menu bar), and asset catalogs for icons (Assets.xcassets). No separation into frameworks or modules—all logic likely lives in AppDelegate and supporting files not listed. Preferences stored via NSUserDefaults (digital.twisted.noTunes key).

macOS users (especially those with Bluetooth headphones) who want to prevent iTunes or Apple Music from launching automatically without uninstalling the apps. Secondary audience: macOS developers building system-level interception utilities or menu bar applications in Swift.

Production-ready and actively maintained. The repo shows v3.5 as the latest release with Homebrew distribution support, indicating stable adoption. However, the codebase is small (4130 lines Swift across 2 main files) suggesting minimal test coverage; CI/CD setup is not visible in the provided file list, which is a minor gap for a utility that intercepts system processes.

Low risk overall: single-maintainer project (tombonez) with straightforward functionality, but lacks visible test coverage and CI automation. No complex dependency tree apparent from the file structure. Main risk: relies on undocumented macOS process monitoring/blocking APIs that could break with OS updates (Ventura+ already required changes to login item setup per the README).

No specific PR or commit data visible, but README indicates recent macOS Ventura+ compatibility work (login item changes documented). No active milestones or open issues listed in provided data.

Check README for instructions.

Daily commands: Open noTunes.xcodeproj in Xcode 12+, select the noTunes scheme, press ⌘R to build and run. The app launches as a menu bar utility; toggle via left-click the status bar icon. For testing without leaving it running, use Product > Scheme > Edit Scheme to disable 'Run' with 'Close on completion'.

• noTunes/AppDelegate.swift: Core application logic for process interception, menu bar management, and toggle state—where iTunes/Music blocking is implemented
• noTunes/Base.lproj/MainMenu.xib: UI definition for the menu bar icon, menu items (quit, hide icon, toggle), and any preferences windows
• noTunes/Info.plist: macOS app metadata, bundle identifier (digital.twisted.noTunes), and system permissions declarations
• noTunes.xcodeproj/project.pbxproj: Xcode project configuration, build settings, and file references—required to compile and modify the app
• noTunes/Assets.xcassets: Icon assets for the app (AppIcon-*.png) and menu bar button states (StatusBarButtonImage, StatusBarButtonImageActive)

AppDelegate.swift is the core file—all event handling, process monitoring, and status bar logic likely resides here. MainMenu.xib (Base.lproj/) controls the menu bar UI. To add new blocking rules: modify the process detection logic in AppDelegate. To add preferences UI: expand MainMenu.xib or create new view controllers. Assets.xcassets contains the status bar icons (StatusBarButtonImage, StatusBarButtonImageActive).

1. Process blocking likely uses private or undocumented macOS APIs (NSRunningApplication or LaunchServices); behavior may change with OS updates. 2. The defaults write commands in README use the key digital.twisted.noTunes—changing the bundle ID breaks all user preferences. 3. Menu bar apps require NSStatusBar which only works when the app runs as a GUI app (LSUIElement or LSBackgroundOnly settings in Info.plist must be balanced with interactive menu needs). 4. Codesigning/notarization required for distribution (not visible in file list, likely handled via CI or manual steps before release).

• NSRunningApplication & process interception — Core mechanism noTunes uses to detect and block iTunes/Music launches; understanding how macOS exposes running processes is essential to modify blocking logic
• NSStatusBar (menu bar integration) — noTunes lives as a persistent menu bar icon; NSStatusBar is the AppKit API that creates and manages status bar buttons and menus
• UserDefaults (NSUserDefaults) for preferences — All user settings (enabled/disabled state, icon visibility, replacement app) are persisted via UserDefaults; the digital.twisted.noTunes domain is the preference key namespace
• Launch Agent / Login Items — noTunes must auto-start at login to block music apps before they launch; understanding SMAppService (Ventura+) vs deprecated APIs is critical for startup logic
• XIB/Interface Builder (AppKit UI) — MainMenu.xib defines the menu bar UI without code; editing XIB files is essential for adding preferences windows or changing menu structure
• Code signing & notarization for macOS distribution — noTunes is distributed as a signed, notarized app; understanding Apple's code signing (developer certificate) and notarization (malware checks) is required to publish releases
• LSUIElement vs foreground app declaration — noTunes must balance menu bar-only UI (no Dock icon) with interactive menus; Info.plist LSUIElement or similar keys control visibility in system UI

• brunophilipe/Cinemagraph — Another lightweight macOS menu bar utility using Swift and AppKit, demonstrating similar patterns for status bar integration and persistent background tasks
• soffes/HyphenApp — macOS app that intercepts system behavior (keyboard shortcuts) similar to noTunes' process interception approach
• objective-see/LuLu — Advanced macOS security utility that monitors and blocks process execution; technical predecessor showing deeper process monitoring patterns that noTunes simplifies
• mas-cli/mas — macOS command-line tool for app management; companion for users who want scriptable control over app installations (noTunes blocks, mas installs)
• Homebrew/homebrew-cask — Distribution mechanism (noTunes is distributed via brew install --cask notunes); understanding cask formulas helps with release/versioning

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 automated code signing and release builds

The repo currently lacks CI/CD automation for building and notarizing macOS releases. With an Xcode project present, a GitHub Actions workflow could automatically build, sign, and notarize the application on each release, reducing manual effort and improving release consistency. This is especially important for macOS apps requiring notarization for distribution.

• [ ] Create .github/workflows/build.yml with xcodebuild steps
• [ ] Configure code signing using GitHub secrets for certificate/provisioning profile
• [ ] Add notarization step using Apple Developer credentials
• [ ] Test workflow on a tag push to verify build artifact generation
• [ ] Update README with CI badge and build status documentation

Create unit tests for AppDelegate.swift core blocking logic

The AppDelegate.swift file likely contains the core logic for preventing iTunes/Music from launching, but there are no test files in the structure. Adding unit tests would verify the application blocking mechanism works correctly across different scenarios (app restart, permission changes, user toggle states) and prevent regressions.

• [ ] Create noTunesTests/ directory with noTunesTests.xctest target
• [ ] Add AppDelegateTests.swift with test cases for blocking logic
• [ ] Test scenarios: app launch interception, toggle enable/disable, multiple rapid launch attempts
• [ ] Integrate tests into Xcode project build phases
• [ ] Document test setup in CONTRIBUTING.md for future contributors

Add comprehensive CONTRIBUTING.md and DEVELOPMENT.md guides

The repo has no CONTRIBUTING.md or DEVELOPMENT.md files. Given that this is an Xcode/Swift project with specific build requirements (code signing, notarization), new contributors need clear setup instructions. This would include Xcode version requirements, provisioning profiles, build configurations, and testing procedures.

• [ ] Create CONTRIBUTING.md with contributor agreement, code style guidelines, and PR process
• [ ] Create DEVELOPMENT.md with macOS/Xcode version requirements and local build setup steps
• [ ] Document how to run and debug the app locally (scheme selection, entitlements)
• [ ] Add troubleshooting section for common Xcode/signing issues on Apple Silicon Macs
• [ ] Reference these files in README.md under 'Development' section

• Add unit tests for process detection logic: Create a Tests/ directory with XCTest cases that mock NSRunningApplication to verify iTunes/Music blocking works correctly across macOS versions (10.13+, 11, 12, 13+). Currently no test files visible.
• Document the replacement app feature in a new SETTINGS.md file: The defaults write digital.twisted.noTunes replacement feature is powerful but buried in the README; create a dedicated guide with examples (Spotify, Doppi, vox, YouTube Music) and edge cases (URL vs app path handling).
• Add accessibility features: Implement VoiceOver support for the menu bar button and menu items by adding NSAccessibility labels to UI elements in MainMenu.xib and AppDelegate—currently no accessibility metadata visible.

noTunes is a relatively simple macOS utility with a focused security scope. The primary concerns relate to code signing/notarization requirements for macOS system utilities and the need for robust process validation mechanisms. No obvious injection vulnerabilities, hardcoded credentials, or dependency issues are apparent from the file structure. The application would benefit from explicit security documentation and verification that macOS API calls for process management use secure, validated approaches. Overall security posture is reasonably good for a small utility application, but macOS-specific signing and notarization requirements must be properly implemented.

• Medium · Missing Code Signing and Notarization Documentation — noTunes.xcodeproj/project.pbxproj, Build Configuration. The application is a macOS executable that interacts with system-level processes (iTunes/Apple Music prevention). Without explicit documentation of code signing and Apple notarization, users may face Gatekeeper warnings or rejection. This could indicate insufficient security controls for a system-level utility. Fix: Ensure the application is properly code-signed with a valid developer certificate and notarized through Apple's notarization service. Document this process in CI/CD pipeline and README.
• Low · Insufficient Input Validation for App Launch Prevention — noTunes/AppDelegate.swift. The application prevents iTunes/Apple Music from launching, but without reviewing AppDelegate.swift, there's potential for insufficient validation of process handling or bundle identifiers. If the blocking mechanism relies on simple string matching or process names, it could be bypassed. Fix: Implement robust validation using bundle identifiers rather than process names. Use proper macOS APIs for process monitoring (e.g., NSWorkspace) with bundle ID verification.
• Low · No Visible Security Policies or Privacy Documentation — README.md, LICENSE, Info.plist. A system utility that monitors and prevents application launches should have clear privacy documentation. No privacy policy or security documentation is visible in the provided file structure. Fix: Add a PRIVACY.md file documenting what data is collected, how process monitoring works, and security guarantees. Update Info.plist with appropriate privacy descriptions.

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.