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/Toxblh/MTMR 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 the board

• Last commit 8w ago
• 29+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• MIT licensed
• CI configured
• Tests present

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

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

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

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

# 4. Critical files exist
test -f "MTMR/AppDelegate.swift" \\
  && ok "MTMR/AppDelegate.swift" \\
  || miss "missing critical file: MTMR/AppDelegate.swift"
test -f "MTMR/TouchBarController.swift" \\
  && ok "MTMR/TouchBarController.swift" \\
  || miss "missing critical file: MTMR/TouchBarController.swift"
test -f "MTMR/ItemsParsing.swift" \\
  && ok "MTMR/ItemsParsing.swift" \\
  || miss "missing critical file: MTMR/ItemsParsing.swift"
test -f "MTMR/AppSettings.swift" \\
  && ok "MTMR/AppSettings.swift" \\
  || miss "missing critical file: MTMR/AppSettings.swift"
test -f "MTMR/CBridge/TouchBarPrivateApi.h" \\
  && ok "MTMR/CBridge/TouchBarPrivateApi.h" \\
  || miss "missing critical file: MTMR/CBridge/TouchBarPrivateApi.h"

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

MTMR is a macOS Touch Bar customization application that lets users completely redesign their MacBook Pro's Touch Bar via JSON configuration files instead of using Apple's limited defaults. It supports custom buttons, system integrations (brightness, volume, music controls), AppleScript execution, and dynamic content plugins—enabling power users to create personalized Touch Bar layouts matching their workflow. Standard Xcode monorepo structure: MTMR/ folder contains the main app (AppDelegate.swift, AppSettings.swift, core TouchBar item classes), MTMR/AppleScripts/ holds ~10 integration scripts for music/weather/system control, and MTMR/Assets.xcassets/ manages app icons and UI images. The codebase is split between Swift (209KB) for modern UI/logic and Objective-C (176KB) for legacy system hooks and Touch Bar integration.

MacBook Pro users (especially developers, power users, musicians, and creative professionals) who want to replace Apple's default Touch Bar with custom buttons, shortcuts, and system controls. Contributors are Swift/Objective-C developers interested in macOS system integration and Touch Bar automation.

Actively maintained with 209KB Swift codebase, published releases available via Homebrew, and CI/CD pipelines in place (build-test.yml, publish.yml workflows). The project has community engagement (Discord/Telegram links in README) and visual tooling (MTMR Designer web editor). This is production-ready software used by thousands, though core stability depends on continued macOS API compatibility.

Single maintainer (Toxblh) creates maintenance risk. The codebase heavily depends on macOS private/public APIs for Touch Bar manipulation and AppleScript execution, which can break with new macOS versions. The reliance on AppleScript files (10+ .scpt files) for integrations adds fragility. No visible test suite or code coverage metrics in the file list suggests limited regression protection.

The project maintains active CI/CD (build-test.yml runs on push/PR, publish.yml handles releases). GitHub Workflows are configured for automated testing and distribution via Homebrew. The presence of a visual designer tool (MTMR Designer) suggests ongoing UX improvements. Community presets are collected in a separate MTMR-presets repository.

Clone the repo and open in Xcode: git clone https://github.com/Toxblh/MTMR.git && cd MTMR && open MTMR.xcodeproj. Then build and run using Xcode's Play button or xcodebuild -scheme MTMR -configuration Release. You'll need macOS 10.12.2+ and must grant Accessibility permissions post-install for system key capture.

Daily commands: Open MTMR.xcodeproj in Xcode, select the MTMR scheme, and press Cmd+R to build and run. Two schemes exist: MTMR (main app) and UnitTests (testing). For release builds, use xcodebuild -scheme MTMR -configuration Release. The app will start in the menu bar; first launch requires Accessibility approval in System Preferences.

• MTMR/AppDelegate.swift — Entry point for the macOS application; initializes the app lifecycle and Touch Bar controller.
• MTMR/TouchBarController.swift — Core orchestrator for building and managing Touch Bar items; every UI element on the bar flows through here.
• MTMR/ItemsParsing.swift — Parses JSON configuration files into Touch Bar item models; responsible for translating user presets into app state.
• MTMR/AppSettings.swift — Manages persistent application settings and user preferences; central state store for app configuration.
• MTMR/CBridge/TouchBarPrivateApi.h — Bridge to Apple's private Touch Bar APIs; enables low-level control over the Touch Bar rendering.
• MTMR/SupportNSTouchBar.swift — Adapter layer providing NSTouchBar protocol implementations and Touch Bar item factories.
• MTMR.xcodeproj/project.pbxproj — Xcode project configuration; defines build targets, dependencies, and code signing for macOS deployment.

Add a new system status widget (Battery, CPU style)

1. Create a new Swift class in MTMR/Widgets/ that inherits from NSView and implements periodic updates (MTMR/Widgets/YourNewWidget.swift)
2. Register the widget type in ItemsParsing.swift's item factory method (around line where BatteryBarItem is instantiated) (MTMR/ItemsParsing.swift)
3. Add a JSON preset example to documentation so users can reference it by type name (e.g., 'type': 'yourwidget') (README.md or docs)

Add a new custom Touch Bar button with shell command execution

1. Define button config in JSON preset with 'type': 'custom', 'action': 'shellScript', and 'script': 'your-command' (User preset JSON (parsed by ItemsParsing.swift))
2. ItemsParsing.swift will route to CustomButtonTouchBarItem or ShellScriptTouchBarItem based on action type (MTMR/ItemsParsing.swift)
3. ShellScriptTouchBarItem executes the shell command and displays output or status (MTMR/ShellScriptTouchBarItem.swift)

Integrate a new system API (e.g., volume control, system preferences)

1. Create Objective-C bridge header in CBridge/ for private macOS API if needed (MTMR/CBridge/YourNewAPI.h)
2. Implement the bridge in corresponding .m file with safe error handling (MTMR/CBridge/YourNewAPI.m)
3. Expose Objective-C methods to Swift via bridging header or wrapper class (MTMR/CBridge/TouchBarPrivateApi-Bridging.h)
4. Use the bridge in a new CustomButtonTouchBarItem or create a dedicated widget (MTMR/CustomButtonTouchBarItem.swift or MTMR/Widgets/YourNewWidget.swift)

Add a new status icon or UI asset

1. Export PNG (1x and 2x scale) or PDF vector graphic matching Touch Bar aesthetic (Design tool output)
2. Drag into Xcode asset catalog or add to MTMR/Assets.xcassets/YourIcon.imageset/ (MTMR/Assets.xcassets/YourIcon.imageset/Contents.json)
3. Reference the asset in code via NSImage(named: 'YourIcon') (MTMR/Widgets/*.swift or MTMR/CustomButtonTouchBarItem.swift)

• Swift + Objective-C hybrid — Swift provides modern syntax and safety for high-level business logic; Objective-C bridges to undocumented/private macOS Touch Bar and system APIs that only C-level headers expose.
• JSON-based preset system — Enables users to define custom Touch Bar layouts without recompiling; easy to share and version presets across the community.
• AppleScript + Shell script execution — Allows users to automate third-party apps (Spotify, Music, Finder) and run arbitrary system commands without requiring native plugins.
• NSView + NSTouchBar framework — Official Apple framework for Touch Bar customization; provides proper rendering, layout, and accessibility support.
• Xcode + Swift Package Manager / CocoaPods-free — Lightweight build with minimal external dependencies; all logic self-contained or bridged directly to system frameworks.

• Use private/undoc
  • Why: undefined
  • Consequence: undefined

AppleScript requires explicit osascript permissions; missing Accessibility grants will silently fail for system keys (Escape, Volume, Brightness). The project hardcodes macOS version checks (10.12.2 minimum) that may not reflect actual NSTouchBar API requirements. Rebuilding after configuration changes may require app restart. The .scpt files are compiled binaries; modifying them requires AppleScript Editor, not plain text editing. Homebrew distribution assumes notarization; unsigned builds won't run on newer macOS with Gatekeeper enabled.

• NSTouchBar API — The core macOS framework that MTMR wraps; understanding Touch Bar item classes, responders, and identifier management is essential to extending the app
• AppleScript Execution & OSA (Open Scripting Architecture) — MTMR uses NSAppleScript to invoke .scpt files for inter-app automation (Spotify, iTunes, Weather); critical for understanding plugin/integration architecture
• macOS Accessibility & User Input Simulation — System keys (Esc, Volume, Brightness) require Accessibility permissions via NSAccessibilityIsUntrustedPromptAsked; failure to grant access silently breaks core functionality
• Status Bar / Menu Bar Integration — MTMR runs as a menu bar app (not Dock); NSStatusBar and NSStatusBarButton manage the persistent menu item and configuration access
• JSON Configuration as Code — Users define Touch Bar layouts via JSON presets parsed by AppSettings.swift; understanding this schema is how contributors support new button types and integrations
• Xcode Build Schemes & CI/CD Workflows — The project uses GitHub Actions (build-test.yml, publish.yml) for automated testing and Homebrew releases; contributors must maintain this pipeline
• Swift-Objective-C Interoperability — Codebase is mixed (209KB Swift + 176KB Objective-C); legacy system hooks are often in Objective-C while UI is Swift; bridging headers enable both languages

• Toxblh/MTMR-presets — Official community preset repository; users and contributors share and discover custom Touch Bar configurations
• BetterTouchTool/BetterTouchTool — Direct competitor offering broader macOS customization; inspired MTMR's plugin-based architecture
• pqrs-org/Karabiner-Elements — Complementary macOS input customization tool; often used alongside MTMR for complete input remapping
• lwouis/alt-tab-macos — Demonstrates similar macOS system integration patterns using Swift and Objective-C for menu bar + system-level hooks

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 AppleScriptTouchBarItem.swift with XCTest coverage

AppleScriptTouchBarItem.swift is a critical component that executes AppleScripts (Battery.scpt, Spotify.next.scpt, etc.), but there are no visible test files in the UnitTests.xcscheme. Adding comprehensive XCTest cases would catch regressions when modifying script execution logic and improve reliability of music/system control features.

• [ ] Create MTMR/Tests/AppleScriptTouchBarItemTests.swift with XCTest framework
• [ ] Add test cases for script file loading from MTMR/AppleScripts/ directory
• [ ] Add test cases for script execution error handling and timeout scenarios
• [ ] Update UnitTests.xcscheme in MTMR.xcodeproj/xcshareddata/xcschemes/ to include new tests
• [ ] Verify tests run in build-test.yml GitHub Action workflow

Create integration tests in build-test.yml for preset configuration parsing

The repo mentions preset sharing (MTMR-presets) but the current build-test.yml workflow only shows basic build steps. Adding integration tests to validate that preset JSON configurations load correctly would prevent breaking changes to the preset format and improve contributor confidence.

• [ ] Extend .github/workflows/build-test.yml with a new test job for preset validation
• [ ] Add schema validation tests for preset JSON structure (referenced in AppSettings.swift)
• [ ] Create sample preset files in Tests/fixtures/ for regression testing
• [ ] Add test assertions to verify preset parsing against known valid/invalid configurations
• [ ] Document preset schema in CONTRIBUTING.md or PRESET_FORMAT.md

Add comprehensive AppleScript error handling and unit tests for MTMR/AppleScripts/ directory

The AppleScripts directory contains 11 scripts (Spotify.next.scpt, Music.nowPlaying.scpt, etc.) but there's no visible error handling mechanism or tests for script failures. Adding OSAKit tests and error callbacks would improve stability when scripts fail or apps aren't installed.

• [ ] Create MTMR/Tests/AppleScriptExecutorTests.swift with tests for each .scpt file in MTMR/AppleScripts/
• [ ] Add timeout handling tests for scripts that hang (e.g., Spotify.nowPlaying.scpt when app is closed)
• [ ] Implement try-catch wrappers in AppleScriptTouchBarItem.swift for failed script execution
• [ ] Add unit tests for graceful fallback UI when scripts return errors
• [ ] Document in README which scripts require which macOS apps to be installed

• Add unit tests for AppSettings.swift JSON parsing—the project has a UnitTests.xcscheme but no visible test files in the file list, so creating XCTest cases for configuration loading and validation would improve reliability.
• Document the JSON preset schema—create a PRESET_SCHEMA.md file with examples of TouchBar item types, properties, and AppleScript binding syntax, since the visual designer exists but schema docs are missing from the repo.
• Extend AppleScripts/ with error handling—current .scpt files (e.g., Spotify.next.scpt, Weather.scpt) likely lack graceful fallbacks when apps are closed; add try-catch wrappers and user notifications.

• High · Use of Private/Undocumented Apple APIs — MTMR/CBridge/TouchBarPrivateApi.h, MTMR/CBridge/TouchBarPrivateApi.m, MTMR/CBridge/DeprecatedCarbonAPI.c, MTMR/CBridge/DeprecatedCarbonAPI.h. The codebase uses private Apple APIs as indicated by files like TouchBarPrivateApi.h, TouchBarPrivateApi.m, and DeprecatedCarbonAPI.c. These private APIs are not officially supported by Apple and may change without notice, leading to compatibility issues and potential security vulnerabilities. The use of deprecated Carbon APIs (DeprecatedCarbonAPI.c) is particularly concerning. Fix: Migrate to official macOS APIs. Use public Touch Bar APIs from NSApplication and NSTouchBar frameworks. Eliminate deprecated Carbon API calls and replace with modern Cocoa equivalents.
• High · Potential Code Injection via AppleScript Execution — MTMR/AppleScriptTouchBarItem.swift, MTMR/AppleScripts/. The presence of AppleScriptTouchBarItem.swift and multiple .scpt files suggest the application executes AppleScript code. If user input or configuration files are not properly sanitized before being passed to AppleScript execution, this could lead to arbitrary code execution. Fix: Implement strict input validation and sanitization for any user-provided data before passing to AppleScript. Use sandboxing where possible. Consider using native Swift APIs instead of AppleScript where feasible. Never execute AppleScript with unsanitized user input.
• High · Insecure Configuration File Handling — MTMR/AppSettings.swift. The AppSettings.swift file likely handles configuration, potentially including user preferences loaded from JSON or plist files. Without proper validation of configuration file contents, an attacker could potentially inject malicious content through crafted configuration files. Fix: Implement strict schema validation for all configuration files. Use secure deserialization methods. Avoid deserializing untrusted data structures that could contain executable code. Implement file permission checks to ensure configuration files have appropriate access controls.
• Medium · Missing Code Signing Verification — MTMR/ (application-wide). No evidence of code signing verification or integrity checks for loaded scripts and configurations. This could allow man-in-the-middle attacks or local file tampering. Fix: Implement code signing for the application and all loaded resources. Verify digital signatures before executing any external scripts. Use cryptographic hashing to verify configuration file integrity.
• Medium · Objective-C Bridging Security — MTMR/CBridge/AMR_ANSIEscapeHelper.h, MTMR/CBridge/AMR_ANSIEscapeHelper.m, MTMR/CBridge/LaunchAtLoginController.h, MTMR/CBridge/LaunchAtLoginController.m. The codebase uses Objective-C bridges (CBridge directory) including AMR_ANSIEscapeHelper and LaunchAtLoginController. Mixed language interfaces increase the attack surface and may introduce memory safety issues if not properly managed. Fix: Review all Objective-C code for memory management issues (retain cycles, use-after-free). Use Swift's stronger type safety where possible. Implement proper error handling at language boundaries. Audit ANSI escape processing for injection vulnerabilities.
• Medium · Privilege Escalation Risk via LaunchAtLoginController — MTMR/CBridge/LaunchAtLoginController.m, MTMR/CBridge/LaunchAtLoginController.h. The LaunchAtLoginController.m suggests the application can be launched at login with elevated privileges. Without proper privilege checking and validation, this could be exploited for privilege escalation attacks. Fix: Implement minimal privilege principle - only request necessary permissions. Validate that launch-at-login operations are user-authorized. Log all privilege-related operations. Use entitlements to restrict what the application can access.
• Medium · Potential ANSI Escape Injection — MTMR/CBridge/AMR_ANSI. The AMR_ANSIEscapeHelper is used to process ANSI escape sequences. If this processes untrusted input without proper validation, it could lead to terminal injection or display manipulation attacks. 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.