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/TheBoredTeam/boring.notch 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 — Single-maintainer risk — review before adopting

• Last commit today
• 8 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 81% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{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 TheBoredTeam/boring.notch repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TheBoredTeam/boring.notch.

What it runs against: a local clone of TheBoredTeam/boring.notch — 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 TheBoredTeam/boring.notch | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.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 ≤ 30 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.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 "boringNotch/ContentView.swift" \\
  && ok "boringNotch/ContentView.swift" \\
  || miss "missing critical file: boringNotch/ContentView.swift"
test -f "boringNotch/BoringViewCoordinator.swift" \\
  && ok "boringNotch/BoringViewCoordinator.swift" \\
  || miss "missing critical file: boringNotch/BoringViewCoordinator.swift"
test -f "boringNotch/MediaControllers/MediaControllerProtocol.swift" \\
  && ok "boringNotch/MediaControllers/MediaControllerProtocol.swift" \\
  || miss "missing critical file: boringNotch/MediaControllers/MediaControllerProtocol.swift"
test -f "BoringNotchXPCHelper/BoringNotchXPCHelper.swift" \\
  && ok "BoringNotchXPCHelper/BoringNotchXPCHelper.swift" \\
  || miss "missing critical file: BoringNotchXPCHelper/BoringNotchXPCHelper.swift"
test -f "boringNotch.xcodeproj/project.pbxproj" \\
  && ok "boringNotch.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: boringNotch.xcodeproj/project.pbxproj"

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

Boring Notch is a macOS menu bar app that repurposes the MacBook notch into a dynamic control center, replacing the native status bar with a customizable space featuring music controls with visualizer, calendar integration, file shelf with AirDrop support, and HUD replacement. It's written primarily in Swift (701KB) and runs on macOS 14 Sonoma+ on Apple Silicon or Intel Macs. Monolithic Xcode project: boringNotch/ contains the main SwiftUI app, BoringNotchXPCHelper/ is a privileged XPC service for system-level operations, Configuration/ holds DMG and build scripts, and .github/workflows orchestrates CI/CD and release automation.

macOS users with notched MacBooks who want to reclaim their notch as a functional, visually-interesting control panel instead of wasted screen space; also contributes to developers interested in native macOS menu bar apps, XPC services, and Core Audio visualization.

Actively developed and production-ready. The project has organized GitHub workflows (CICD, release automation, Crowdin localization), a devcontainer setup for consistent development, and structured issue templates. Supports multiple languages (Swift, Python, Shell for CI). Distributed via signed DMG releases and maintained with regular updates.

Low risk for end-users but medium risk for contributors: the project lacks an Apple Developer account (noted in README), requiring manual security bypass on first install. CI/CD is robust with dependabot enabled, but the monolithic Xcode project structure (.xcodeproj) can create merge conflicts. Single primary team ('TheBoredTeam') but has public contribution framework.

Active release cycle with version management scripts (.github/scripts/extract_version.py, remove_beta.py), Crowdin localization sync, manual and automated builds, and static analysis via GitHub Actions. Recent work includes workflow refactoring (base_ref_check, reusable build templates) and version dropdown updates.

Clone: git clone https://github.com/TheBoredTeam/boring.notch.git && cd boring.notch. Open in Xcode: open boringNotch.xcodeproj. Install Python dependencies for build scripts: pip install -r Configuration/dmg/requirements.txt. Build and run via Xcode (Cmd+R) or xcodebuild -scheme boringNotch -configuration Release.

Daily commands: In Xcode: select boringNotch scheme → Product → Run (Cmd+R). App launches as menu bar item. For development, use the devcontainer (defined in .devcontainer/devcontainer.json) or local Xcode 15+. No separate server needed; app is standalone.

• boringNotch/ContentView.swift — Main UI entry point and root view coordinator for the notch display interface
• boringNotch/BoringViewCoordinator.swift — Core coordinator managing view state transitions and notch UI rendering logic
• boringNotch/MediaControllers/MediaControllerProtocol.swift — Defines the abstraction contract all media controllers must implement (Apple Music, Spotify, YouTube Music)
• BoringNotchXPCHelper/BoringNotchXPCHelper.swift — XPC service handler enabling privileged notch rendering and system integration
• boringNotch.xcodeproj/project.pbxproj — Xcode project configuration, build targets, and framework dependencies
• .github/workflows/cicd.yml — Primary CI/CD pipeline for automated testing, building, and release workflows
• boringNotch/Localizable.xcstrings — Centralized string localization asset for multi-language support via Crowdin

Add a New Media Controller (e.g., Tidal, Amazon Music)

1. Create a new class conforming to MediaControllerProtocol in boringNotch/MediaControllers/ (boringNotch/MediaControllers/MediaControllerProtocol.swift)
2. Implement required methods: getPlaybackState(), getTrackInfo(), play(), pause(), nextTrack(), previousTrack() (boringNotch/MediaControllers/[NewServiceName]Controller.swift)
3. Register the new controller in BoringViewCoordinator to switch between providers (boringNotch/BoringViewCoordinator.swift)
4. Add service-specific icons to Assets.xcassets if needed (boringNotch/Assets.xcassets/)
5. Update CI/CD to test the new controller integration (.github/workflows/cicd.yml)

Add a New Localized Language

1. Add string keys to the centralized localization file (boringNotch/Localizable.xcstrings)
2. Submit translations via Crowdin (linked in CI/CD workflow) (.github/workflows/crowdin.yml)
3. Verify new language renders correctly in ContentView (boringNotch/ContentView.swift)

Extend YouTube Music Integration

1. Update API models to handle new response fields (boringNotch/MediaControllers/YouTube Music Controller/YouTubeMusicModels.swift)
2. Add new networking methods or endpoints (boringNotch/MediaControllers/YouTube Music Controller/YouTubeMusicNetworking.swift)
3. Implement new features in the main controller (boringNotch/MediaControllers/YouTube Music Controller/YouTubeMusicController.swift)
4. Test authentication flow if token handling changes (boringNotch/MediaControllers/YouTube Music Controller/YouTubeMusicAuthentication.swift)

Enhance XPC Helper for New System Capabilities

1. Define new RPC methods in the XPC protocol (BoringNotchXPCHelper/BoringNotchXPCHelperProtocol.swift)
2. Implement handlers in the XPC service (BoringNotchXPCHelper/BoringNotchXPCHelper.swift)
3. Update entitlements if new system permissions are needed (BoringNotchXPCHelper/BoringNotchXPCHelper.entitlements)
4. Test privileged operations in release workflow (.github/workflows/release.yml)

• SwiftUI — Native declarative framework for macOS UI, excellent for notch rendering with dynamic animations
• XPC (inter-process communication) — Enables privileged notch rendering without requiring app to run as root; security-first design
• MediaPlayer.framework — System-level access to now-playing information across all media players without deep integration
• URLSession — Built-in HTTP client for Spotify and YouTube Music API calls; no external dependency bloat
• Crowdin + GitHub Actions — Automated CI/CD-integrated localization workflow for multi-language support

• Protocol-based media controller abstraction

  • Why: Allows pluggable support for multiple streaming services (Spotify, Apple Music, YouTube Music)
  • Consequence: Each controller must implement full interface; harder to add lightweight integrations but ensures consistency

• XPC helper as separate process

  • Why: Isolates privileged notch rendering from main app; improves security and stability
  • Consequence: Adds IPC overhead (~5–10ms per call); requires careful synchronization between processes

• Centralized Localizable.xcstrings instead of per-file strings

  • Why: Simplifies translation management and Crowdin integration
  • Consequence: Single point of failure for localization; requires coordination when adding new UI

• YouTube Music custom API client vs. SDK

  • Why: No official YouTube Music SDK for macOS; custom implementation reduces dependencies
  • Consequence: Maintainability burden if YouTube Music API changes; potential fragility vs. first-party SDK

• Linux or Windows support—macOS-only application leveraging notch hardware
• Real-time streaming audio—only metadata and control integration, no audio mixing
• Headless/CLI mode—GUI-first design for visual notch display
• Database persistence—stateless controller design, relies on user defaults for preferences
• Third-party plugin architecture—fixed set of supported streaming services

XPC entitlements (.entitlements files) must match between main app and helper or IPC will fail silently. Python build scripts (dmgbuild, pyobjc) require exact versions pinned in requirements.txt; version mismatches break DMG creation. No Apple Developer account means each user must manually allow app in System Preferences → Security on first launch (expected but not automated). Xcode workspace has shared SwiftPM Package.resolved; local dependency edits can cause build cache issues.

• XPC (XPC Services) — Boring Notch uses XPC to run privileged helper process (BoringNotchXPCHelper) for system-level music control and HUD features; understanding XPC architecture, entitlements, and IPC is essential for maintainability.
• Core Audio (Audio Visualization) — The music visualizer feature requires real-time audio sampling and FFT processing; Core Audio is the low-level macOS framework for this.
• SwiftUI Menu Bar Apps — Boring Notch is fundamentally a menu bar application (NSStatusBar / SwiftUI equivalent); understanding menu bar lifecycle, event handling, and screen edge constraints is core.
• Code Signing & Entitlements — The XPC helper requires specific entitlements (.entitlements files) and codesigning; mismatches silently break IPC. Critical for distribution and security.
• Crowdin Localization Workflow — Boring Notch uses Crowdin for i18n sync (badge shown in README); understanding how CI pulls translations and where localized strings live is needed for multi-language features.
• DMG Packaging & Installation Distribution — Configuration/dmg/ and dmgbuild create the .dmg users download; understanding DMG structure, background images, and Python build tooling is needed for release workflows.
• GitHub Actions CI/CD Orchestration — Six workflows (CICD, release, manual_build, crowdin sync, static analysis) automate the entire build-test-release pipeline; understanding workflow dependencies and secrets is essential for contributing.

• dwarvesf/hidden — Alternative macOS menu bar customization tool; competes in same space but with different UX and feature set.
• quail-ink/quail — Another notch-aware macOS app using SwiftUI and XPC; reference for architectural patterns in privileged menu bar apps.
• serhii-londar/open-source-mac-os-apps — Curated list of open-source macOS apps; Boring Notch likely listed here; useful for discovering similar projects and best practices.
• apple/swift-syntax — Swift compiler library; used indirectly by Xcode toolchain; relevant if Boring Notch ever needs compile-time code generation or AST manipulation.
• apple/swift-package-manager — Manages dependencies listed in Package.resolved (swiftpm/); understanding SPM crucial for dependency updates and private package integration.

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 BoringNotchXPCHelper Swift modules

The BoringNotchXPCHelper directory contains critical XPC communication code (BoringNotchXPCHelper.swift, BoringNotchXPCHelperProtocol.swift, main.swift) but there are no visible test files. This XPC helper handles privileged operations and deserves comprehensive unit tests to prevent regressions in core functionality. Adding tests would improve reliability and make future contributions safer.

• [ ] Create Tests/BoringNotchXPCHelperTests/ directory
• [ ] Add unit tests for BoringNotchXPCHelperProtocol.swift covering message routing and protocol compliance
• [ ] Add integration tests for BoringNotchXPCHelper.swift validating XPC connection handling
• [ ] Update boringNotch.xcodeproj to include the new test target
• [ ] Add test configuration to .github/workflows/cicd.yml to run tests on every PR

Create GitHub Action workflow for automated code signing and notarization verification

The repo has manual_build.yml and release.yml workflows, but there's no dedicated workflow to validate code signing and notarization compliance before releases. Given this is a macOS app with XPC helper (requiring special entitlements), a pre-release verification workflow would catch signing/notarization issues early and reduce manual release burden.

• [ ] Create .github/workflows/notarization_check.yml workflow
• [ ] Add step to verify code signing on boringNotch.xcodeproj and BoringNotchXPCHelper entitlements
• [ ] Add step to validate BoringNotchXPCHelper.entitlements file structure
• [ ] Configure workflow to run on PRs touching boringNotch.xcodeproj, entitlements files, or build scripts
• [ ] Document notarization requirements in CONTRIBUTING.md with reference to the new workflow

Add localization test workflow and documentation for Crowdin integration

The repo uses Crowdin for translations (see .github/workflows/crowdin.yml and localization badges in README), but there's no visible workflow validating string key consistency across localized strings or documenting the localization process. New contributors often struggle with proper i18n. Adding a validation workflow plus localization guide would improve contributor experience.

• [ ] Create .github/workflows/localization_validate.yml to check for missing/orphaned translation keys
• [ ] Add docs/LOCALIZATION.md documenting the Crowdin workflow, string key naming conventions, and how to add new translatable strings
• [ ] Add pre-commit hook documentation in CONTRIBUTING.md for validating translation file syntax
• [ ] Reference the new localization guide in .github/ISSUE_TEMPLATE/feature_request.md with reminder to update strings

• Add unit tests for BoringNotchXPCHelper/BoringNotchXPCHelperProtocol.swift — currently no test files exist for the XPC layer; a junior could write XCTest cases to verify message serialization and error handling.
• Document the XPC service setup in CONTRIBUTING.md — the repo has great GitHub Actions docs but zero explanation of how the main app communicates with BoringNotchXPCHelper; add a 'Architecture' section with a diagram or walkthrough.
• Add GitHub Action to validate Python script syntax — .github/scripts/ (extract_version.py, remove_beta.py) have no linting; add a workflow step with pylint or black to catch syntax errors before release.

The codebase demonstrates good security practices including dependency hash verification, proper vulnerability reporting procedures (SECURITY.md), and established CI/CD workflows. The primary concerns are: (1) ensuring timely updates of native Python bindings (pyobjc), (2) careful review of XPC helper permissions to prevent privilege escalation, and (3) hardening GitHub Actions workflows. No critical vulnerabilities, hardcoded secrets, SQL injection risks, or obvious infrastructure misconfigurations were detected in the provided file structure. The project should maintain regular dependency audits and security reviews as part of its development process.

• Medium · Outdated PyObjC Dependencies — Configuration/dmg/requirements.txt. The project uses pyobjc-core, pyobjc-framework-cocoa, and pyobjc-framework-quartz version 12.1. While version pinning with hash verification is good practice, these are native Python bindings to macOS frameworks. Ensure these versions are regularly updated to receive security patches from the PyObjC project. Fix: Regularly update pyobjc dependencies to the latest stable versions. Monitor security advisories for pyobjc on GitHub and CVE databases. Consider implementing automated dependency scanning with Dependabot (already configured in .github/dependabot.yml).
• Low · Missing Subresource Integrity for Remote Assets — README.md. The README contains external badge URLs (badges.crowdin.net, dcbadge.limes.pink, srv-cdn.himpfen.io) that are loaded without integrity checks. While these are display badges, they could theoretically be compromised. Fix: Use HTTPS for all external resources (already in place). Consider hosting badges locally or using SVG alternatives. Monitor external dependencies in CI/CD pipelines.
• Low · XPC Helper Entitlements Review — BoringNotchXPCHelper/BoringNotchXPCHelper.entitlements. The project includes a BoringNotchXPCHelper with entitlements configuration. XPC (inter-process communication) components require careful permission management to prevent privilege escalation or unauthorized access. Fix: Review XPC entitlements to ensure only necessary permissions are requested. Follow Apple's principle of least privilege. Validate all IPC messages in BoringNotchXPCHelper.swift and BoringNotchXPCHelperProtocol.swift for injection attacks.
• Low · GitHub Workflow Security — .github/workflows/. Multiple GitHub Actions workflows are configured (.github/workflows/). Need to verify these workflows use pinned action versions and don't expose secrets in logs. Fix: Pin all GitHub Actions to specific commit SHAs instead of tags (e.g., uses: action/repo@abc123def456 instead of @v1). Audit workflows for secret handling. Use GitHub's OIDC token provider instead of long-lived tokens where possible.

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.