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/Caldis/Mos 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
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Caldis/Mos(\\.git)?\\b" \\
  && ok "origin remote is Caldis/Mos" \\
  || miss "origin remote is not Caldis/Mos (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Mos/AppDelegate.swift" \\
  && ok "Mos/AppDelegate.swift" \\
  || miss "missing critical file: Mos/AppDelegate.swift"
test -f "Mos.xcodeproj/project.pbxproj" \\
  && ok "Mos.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: Mos.xcodeproj/project.pbxproj"
test -f "LOCALIZATION.md" \\
  && ok "LOCALIZATION.md" \\
  || miss "missing critical file: LOCALIZATION.md"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f ".github/workflows/pages.yml" \\
  && ok ".github/workflows/pages.yml" \\
  || miss "missing critical file: .github/workflows/pages.yml"

# 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/Caldis/Mos"
  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).

Mos is a lightweight macOS menubar tool that intercepts mouse scroll wheel events and smooths them through interpolation, making cheap scroll wheels feel as fluid as trackpads. It also supports per-application scroll settings, scroll direction inversion, custom button remapping, and Logitech HID++ device integration—all while preserving pixel-perfect control for applications that need it. Monolithic Xcode project structure (Mos.xcodeproj/) with Swift as primary language (~1.3MB). Supporting tooling lives in TypeScript/JavaScript for web documentation and agent-driven CI/CD scripts (.agents/ directory with evals, skills, and rubrics). Settings UI likely driven by SwiftUI; Logitech/HID support via native macOS frameworks. Configuration persisted as user defaults; per-app profiles stored locally.

macOS users with external mice who find scroll wheel input feels jerky or imprecise compared to trackpad scrolling. Developers and power users who want per-app scroll profiles and custom mouse button bindings to their workflows. Logitech device owners seeking native support for proprietary buttons via HID++ protocol.

Actively maintained—the project includes comprehensive agent evals, release preparation skills, multi-language documentation (7+ README translations), and structured CI/CD. The codebase is production-ready with accessibility compliance and real-device testing procedures documented. Latest commits and release workflows are current, indicating ongoing development rather than stable-only maintenance.

Standard open source risks apply.

Active release management (.agents/skills/release-preparation/SKILL.md), ongoing localization (7 README variants in LOCALIZATION.md), and structured evaluation framework for agent-assisted development (.agents/evals/ with test cases for Logi boundary conditions, real-device testing, build commands). Recent agent evals document compliance gates and testing procedures suggesting continued hardening.

Clone the repo: git clone https://github.com/Caldis/Mos.git && cd Mos. Open in Xcode: open Mos.xcodeproj. Build via Xcode menu (Product > Build) or xcodebuild -scheme Mos. No npm/yarn setup required for core app; web docs use TypeScript but are not needed for local testing.

Daily commands: In Xcode: select 'Mos' scheme, set target to 'My Mac', then Cmd+R to build and launch. No additional build steps or dependency install needed. App will request Accessibility permissions on first launch—grant these for scroll interception to work. Check System Preferences > Security & Privacy > Accessibility if scroll events aren't captured.

• Mos/AppDelegate.swift — Entry point for the application lifecycle; initializes the mouse event interceptor and menu bar integration that is core to Mos's scroll-smoothing functionality.
• Mos.xcodeproj/project.pbxproj — Xcode project configuration defining build targets, dependencies, and code signing required to build and release the macOS application.
• LOCALIZATION.md — Defines the localization strategy and file structure for supporting multiple languages; essential for contributors adding new UI strings or modifying existing ones.
• CONTRIBUTING.md — Outlines contribution guidelines, development workflow, and coding standards that all contributors must follow to maintain consistency.
• .github/workflows/pages.yml — CI/CD pipeline configuration that automates testing, linting, and release builds; critical for understanding the automated validation process.
• CHANGELOG.md — Historical record of all releases and feature changes; provides context for understanding the project's evolution and current capabilities.

• AppDelegate (Swift, Cocoa AppKit) — Application entry point; manages app lifecycle, initializes event interceptor, manages menu bar icon and status updates
  • Failure mode: If AppDelegate crashes, entire app terminates and scroll smoothing stops immediately; user loses scroll control until app is restarted
• Event Interceptor (CGEventTap) (Core Graphics (CGEventTap), IOKit) — Low-level system event hook that captures mouse scroll events before they reach applications; applies smoothing algorithm and direction reversal
  • Failure mode: If event tap fails or is blocked by security policies, scroll events bypass the app entirely; requires user to manually re-enable accessibility permissions or restart macOS
• **** — undefined

Add Support for a New Mouse Device

1. Examine the current event interception logic in AppDelegate.swift to understand how mouse scroll events are captured and filtered (Mos/AppDelegate.swift)
2. Add device-specific boundary or behavior detection in the event handling code, similar to existing Logitech boundary handling (Mos/AppDelegate.swift)
3. Update CHANGELOG.md to document the new device support (CHANGELOG.md)

Add a New Language Localization

1. Read LOCALIZATION.md to understand the translation file structure and naming conventions (LOCALIZATION.md)
2. Create translated string resource files following the pattern documented in LOCALIZATION.md (LOCALIZATION.md)
3. Register the new language in the Xcode project's localization settings via the project configuration (Mos.xcodeproj/project.pbxproj)
4. Test the localization by running the Debug scheme with the new language selected (Mos.xcodeproj/xcshareddata/xcschemes/Debug.xcscheme)

Modify Scroll Smoothing Algorithm

1. Locate the scroll event processing logic in AppDelegate.swift where mouse wheel delta values are transformed (Mos/AppDelegate.swift)
2. Update the smoothing algorithm (e.g., acceleration curve, velocity damping, or frame interpolation) in the event handler (Mos/AppDelegate.swift)
3. Test using the Profile scheme to measure performance impact of the new algorithm (Mos.xcodeproj/xcshareddata/xcschemes/Profile.xcscheme)
4. Document the algorithm change and rationale in CHANGELOG.md (CHANGELOG.md)

• Swift 5.0 — Modern, type-safe language with excellent macOS integration via Cocoa frameworks; enables readable event-handling code with strong compile-time guarantees
• Xcode & Swift Package Manager — Native Apple development tools ensure seamless integration with macOS system APIs (Core Graphics, IOKit) and simplified dependency management
• GitHub Actions CI/CD — Native GitHub integration enables automated testing, linting, and release workflows without external services
• Cocoa/AppKit frameworks — Required for low-level mouse event interception, menu bar integration, and native macOS UI components

• Low-level event interception via Cocoa rather than higher-level event taps

  • Why: Achieves fine-grained control over scroll smoothing and per-device customization
  • Consequence: Requires elevated privileges and careful handling of system events; potential stability risk if event handling crashes

• Single macOS-only codebase rather than cross-platform framework

  • Why: Optimal use of macOS-specific APIs (CGEventTap, IOKit) for reliable scroll interception and menu bar integration
  • Consequence: No support for Windows or Linux; all development and testing must occur on macOS

• CC BY-NC 4.0 license (non-commercial) rather than open MIT/Apache

  • Why: Protects author's interests in a niche utility market where commercial forks could compete unfairly
  • Consequence: Limits commercial use and derivative projects; reduces potential for enterprise adoption or paid integrations

• Menu bar status indicator with minimal UI rather than full preferences window

  • Why: Reduces memory footprint and keeps the app lightweight; scroll smoothing is a background utility, not a primary workflow tool
  • Consequence: Limited in-app configurability; users must interact via menu or system preferences

• Does not provide real-time system-wide scroll direction reversal for trackpad (only for external mice)
• Does not implement network synchronization or cloud-based settings sync
• Does not support kinetic scrolling physics simulation (focuses on smooth interpolation)
• Does not provide per-application scroll behavior profiles at the system level

Accessibility permissions must be granted manually in macOS System Preferences; app will not auto-escalate. Scroll event interception is system-wide and can conflict with other input-manipulation tools (e.g., other scroll smoothers, remap utilities)—test thoroughly on user machines. Notarization is required for distribution outside App Store; the build process requires valid Apple developer signing certificates. HID++ protocol implementation is device-specific (Bolt, Unifying, Bluetooth); adding new Logitech device support requires real hardware testing. Per-app configuration keyed by app bundle ID, so app relaunches or renames may orphan old settings.

• CGEvent Tap (Core Graphics Event Tapping) — Mos intercepts system scroll wheel events at the OS level using CGEvent taps—understanding tap locations (pre-/post-keyboard, HID device level) is essential for avoiding conflicts and ensuring scroll events are captured before app-level handlers see them
• HID++ Protocol (Logitech Proprietary) — Mos natively implements Logitech's HID++ protocol for Bolt, Unifying, and Bluetooth devices—this allows capturing proprietary button events and device-specific actions beyond standard USB HID, but requires careful protocol state management and device-specific branching
• Accessibility Permissions & Trusted Process Elevation (macOS) — Scroll interception requires Accessibility framework access, which users must grant manually. Mos must handle permission denial gracefully and educate users on enabling it in System Preferences—failure here makes the app non-functional
• Notarization & Code Signing (macOS App Distribution) — Mos must be code-signed and notarized to run on modern macOS without Gatekeeper warnings. The release-preparation skill documents this workflow; missing steps will prevent user downloads
• Scroll Event Interpolation / Smoothing Curves — The core feature—converting coarse scroll deltas into smooth, continuous motion. Mos likely uses spline or easing-function interpolation with configurable time constants and gain curves; understanding the math is key to tuning scroll feel
• Per-App Configuration Keying by Bundle ID — Mos stores separate scroll and button profiles per macOS app, keyed by CFBundleIdentifier. This requires bundle ID lookup at runtime and careful handling of app renames, updates, and edge cases (e.g., app not yet run)
• Menubar App & Daemon Architecture — Mos runs as a menubar app (visible in status bar) but likely spawns a background daemon or thread for continuous scroll event handling. This pattern avoids blocking the UI and enables long-lived system integration

• Duetdisplay/Duet — Another macOS input-manipulation tool demonstrating accessibility framework patterns and user permission flows for system event handling
• pqrs-org/Karabiner-Elements — Industry-standard macOS keyboard remapper using similar event interception patterns; reference for robust HID handling and per-app configuration design
• Logitech/logi_device_fw — Logitech's own device firmware and protocol documentation—relevant for understanding HID++ spec nuances Mos implements
• SwiftUI-Community/awesome-swiftui — Community curated examples of SwiftUI patterns likely used in Mos's settings/preferences UI
• apple/swift — Swift language repository; Mos targets Swift 5.0 and relies on recent stdlib features for event handling

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 comprehensive unit tests for scroll smoothing algorithms

The repo lacks dedicated unit test coverage for the core scrolling logic. Given that Mos is fundamentally a mouse scroll enhancement tool, testing the scroll smoothing algorithms, acceleration curves, and directional handling is critical. The file structure shows .agents/docs/testing.md exists but there's no visible Tests/ or *Tests.swift files in the Xcode project. Adding unit tests would ensure scroll behavior remains consistent across macOS versions (10.13+) and prevent regressions.

• [ ] Create Tests/ directory structure in Mos.xcodeproj following Xcode conventions
• [ ] Add unit tests for scroll smoothing acceleration/deceleration logic
• [ ] Add unit tests for directional scroll inversion and independent axis handling
• [ ] Add unit tests for device-specific scroll boundary detection (mentioned in .agents/evals/cases/logi-boundary.md)
• [ ] Document testing approach in .agents/docs/testing.md with examples

Implement missing localization files for supported languages

The README shows support for 5+ languages (中文, English, Deutsch, 日本語, 한국어, Русский) but the file structure doesn't show localization bundles (.lproj directories). The LOCALIZATION.md file suggests a localization strategy exists but localization files are missing from the visible project structure. Adding these would enable native language support throughout the UI.

• [ ] Review LOCALIZATION.md to understand the localization strategy and any existing translation sources
• [ ] Create required .lproj directories: en.lproj, de.lproj, ja.lproj, ko.lproj, ru.lproj in Mos/Assets.xcassets
• [ ] Add Localizable.strings files for each language with UI strings extracted from AppDelegate.swift and UI components
• [ ] Update Mos.xcodeproj to reference localization files properly
• [ ] Test localization switching on macOS System Preferences

Add automated release workflow GitHub Action for version bumping and changelog generation

The repo has .agents/evals/cases/release-prep.md and .agents/skills/release-preparation/ indicating releases require manual preparation steps. Currently only .github/workflows/pages.yml exists. Adding a release automation workflow would streamline the release process, reduce human error, and maintain consistency with .last-release-commit and CHANGELOG.md updates. This aligns with the release-preparation skill already documented.

• [ ] Review .agents/skills/release-preparation/SKILL.md and .agents/evals/cases/release-prep.md to understand current release steps
• [ ] Create .github/workflows/release.yml GitHub Action that triggers on version tag push
• [ ] Implement version bump logic in workflow (update package version, git tags, releases)
• [ ] Integrate changelog generation using conventional commits or standard changelog format
• [ ] Add workflow step to update .last-release-commit file
• [ ] Document the release process in CONTRIBUTING.md with new workflow instructions

• Add unit tests for scroll interpolation math in the smoothing algorithm—currently no visible test files in the structure despite complex delta calculations. Start by creating Tests/ScrollingTests.swift with edge cases for negative deltas, zero values, and boundary conditions at max/min scroll speeds.
• Expand the agent evals test suite to cover horizontal scrolling parity with vertical—.agents/evals/cases/ has focus on general scrolling but no explicit case for left/right axis-independent inversion edge cases. Add a test case markdown file documenting expected behavior for simultaneous vertical + horizontal scroll events.
• Add missing documentation for the Logi HID++ button remapping feature in README files—current READMEs mention button binding but .agents/evals/cases/logi-boundary.md suggests extensive HID++ support; write a dedicated guide explaining which Logitech mice are supported and how to map proprietary buttons to system actions.

The Mos macOS application codebase demonstrates reasonable security practices with a clear project structure and documentation. Primary concerns are related to Xcode project file management (.xcuserdata files in version control) and incomplete security test coverage. The project uses Swift and appears to be a legitimate open-source tool with CC BY-NC 4.0 licensing. No critical code injection risks, SQL injection vulnerabilities, or obvious secrets were identified in the visible file structure. Recommendations focus on standard Xcode build hygiene and enhanced security testing documentation.

• Medium · Potential Hardcoded Credentials in Xcode Project Files — Mos.xcodeproj/project.xcworkspace/xcuserdata/, Mos.xcodeproj/xcuserdata/. The repository contains multiple .xcuserdata and user-specific Xcode configuration files that may contain hardcoded credentials, API keys, or sensitive build configurations. These files are typically generated by Xcode and stored in version control, which is a security anti-pattern. Fix: Add .xcuserdata/ to .gitignore to prevent user-specific files from being committed. Ensure all Xcode user data directories are excluded from version control.
• Low · Missing Security Headers in GitHub Pages Configuration — .github/workflows/pages.yml. The GitHub Pages workflow file (.github/workflows/pages.yml) is present but typical security headers (CSP, X-Frame-Options, etc.) may not be properly configured for the published documentation. Fix: Configure security headers in the GitHub Pages deployment, either through _config.yml or a custom headers configuration file.
• Low · Incomplete .gitignore Coverage — .gitignore. While a .gitignore file exists, the file structure reveals multiple build artifacts and user-specific files that should be ignored. The coverage may be incomplete for all Xcode-generated files and build outputs. Fix: Verify .gitignore includes all standard Xcode build artifacts, DerivedData, .DS_Store, and other temporary files. Consider using a comprehensive Swift/Xcode .gitignore template.
• Low · Evaluation and Testing Documentation Without Security Context — .agents/evals/, .agents/docs/testing.md. The .agents/evals directory contains evaluation cases and scripts but there is no explicit security testing or vulnerability assessment documentation visible in the file structure. Fix: Add security-specific testing cases to the evaluation framework, including dependency vulnerability scanning, code signing verification, and entitlements review for macOS app.

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.