WAIT — Slowing — last commit 8mo ago

• Last commit 8mo ago
• 4 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Slowing — last commit 8mo ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Ice is a macOS menu bar manager written in Swift that hides, shows, and organizes menu bar items through multiple interaction patterns (hover, click, scroll, swipe). It provides a unified control surface for managing the cluttered macOS menu bar with features like always-hidden sections, rehiding timers, drag-and-drop arrangement, and visual customization (tinting, shadows, borders, custom shapes). Single-target Xcode project structure: Ice/ contains the monolithic app code with Assets.xcassets for UI elements (icons, control images). SwiftLint config (.swiftlint.yml) enforces code style. No visible separation into frameworks or packages—logic, UI, and models coexist in the main target.

macOS power users and developers who want to declutter their menu bar and organize dozens of status bar applications; contributors experienced with Swift/SwiftUI who want to maintain a production macOS utility with direct end-user impact.

Actively developed but pre-1.0: the repo explicitly states 'Ice is currently in active development' with several roadmap features still unimplemented (profiles, spacer items, groups, conditional triggers). CI/linting via .github/workflows/lint.yml is in place, and the project has enough structure for daily use, but should be treated as beta-quality for advanced features.

Single maintainer (jordanbaird) is a significant risk factor for long-term sustainability. The codebase is 602K lines of Swift with no visible test directory in the file list, suggesting minimal automated test coverage—dangerous for a system tool that directly manipulates macOS UI accessibility. Dependency surface is unclear but likely leverages Apple frameworks heavily, reducing external risk.

Active development on menu bar item spacing (marked BETA in README), with roadmap items like profiles, spacer items, and menu item groups in progress. The workflows directory shows linting is automated. No specific recent commits are visible in the file list, but the explicit 'active development' note and unimplemented features suggest ongoing work.

Clone the repo, open Ice.xcodeproj in Xcode, and build/run the scheme: xcodebuild -scheme Ice -configuration Debug. No package manager setup needed—Swift Package Manager dependencies are already resolved in .xcworkspace/xcshareddata/swiftpm/Package.resolved.

Daily commands: Open Ice.xcodeproj in Xcode, select the Ice scheme, and press Cmd+R to build and run. For CLI builds: xcodebuild -scheme Ice. The app will launch as a menu bar utility.

• Ice/Main/IceApp.swift — Entry point for the entire application—defines the main app lifecycle and initializes core services.
• Ice/Main/AppState.swift — Central state manager holding application-wide observable properties; all major features depend on updates from here.
• Ice/MenuBar/ControlItem/ControlItem.swift — Core abstraction for menu bar control items; fundamental to the hiding/showing menu bar items feature.
• Ice/Events/EventManager.swift — Coordinates all system event monitoring and dispatching; critical for hotkey and menu bar interaction handling.
• Ice/MenuBar/Appearance/MenuBarAppearanceManager.swift — Manages menu bar visual styling and overlay behavior; central to customization feature set.
• Ice/Hotkeys/HotkeyRegistry.swift — Registry and orchestration for hotkey binding and handling; essential for user input automation.

• AppState (Combine, @Published, UserDefaults) — Central Observable holding all user-configurable settings, menu bar visibility state, and navigation context
  • Failure mode: Inconsistent state if AppState is modified concurrently without

Add a New Hotkey Action

1. Define new case in HotkeyAction enum (Ice/Hotkeys/HotkeyAction.swift)
2. Add handler logic in EventManager to dispatch on hotkey press (Ice/Events/EventManager.swift)
3. Register hotkey binding in HotkeyRegistry during app initialization (Ice/Hotkeys/HotkeyRegistry.swift)
4. Add settings UI to allow user configuration (if needed) (Ice/Main/Navigation/NavigationIdentifiers/SettingsNavigationIdentifier.swift)

Add a New Menu Bar Appearance Option

1. Define style case in MenuBarShape or MenuBarTintKind enum (Ice/MenuBar/Appearance/MenuBarShape.swift)
2. Implement rendering logic in MenuBarAppearanceManager (Ice/MenuBar/Appearance/MenuBarAppearanceManager.swift)
3. Add configuration storage in MenuBarAppearanceConfiguration (Ice/MenuBar/Appearance/Configurations/MenuBarAppearanceConfigurationV2.swift)
4. Create settings UI panel for option in MenuBarAppearanceEditor (Ice/MenuBar/Appearance/MenuBarAppearanceEditor/MenuBarAppearanceEditor.swift)

Add a New Event Monitor Type

1. Create new EventMonitor subclass (e.g., CustomEventMonitor.swift) (Ice/Events/EventMonitors/)
2. Implement start/stop lifecycle and event publishing (Ice/Events/EventMonitors/UniversalEventMonitor.swift)
3. Register monitor in EventManager initialization (Ice/Events/EventManager.swift)
4. Add AppState publisher to expose monitor output to UI (Ice/Main/AppState.swift)

• SwiftUI — Declarative UI framework native to macOS 14+; simplifies settings panels and live previews
• Combine (Publishers/Subscribers) — Reactive data binding for state changes; enables decoupled event propagation across layers
• Accessibility APIs (AXUIElement) — Required to query and manipulate menu bar items programmatically on macOS
• Objective-C Runtime & Private Frameworks — Deep macOS integration for menu bar overlay control and event tap injection
• NSStatusBar & NSStatusItem — macOS standard APIs for menu bar presence and custom control items

• Use of private/undocumented macOS frameworks (via Bridging)

  • Why: Required to achieve native menu bar visual customization and advanced overlay control not exposed in public APIs
  • Consequence: Increased fragility across macOS versions; requires version-specific testing and potential future refactoring

• Single AppState observable object vs. granular smaller stores

  • Why: Simplifies initialization and avoids dependency injection complexity; single source of truth
  • Consequence: AppState can grow large; requires discipline to avoid God Object anti-pattern

• Global event monitors active continuously vs. on-demand

  • Why: Ensures hotkeys and menu bar changes are responsive even when settings window is closed
  • Consequence: Persistent background activity; slightly higher CPU/memory footprint than event-on-demand

• Cross-platform support (macOS only)
• Automation of non-menu-bar items or system UI elements
• Real-time menu bar activity analytics or logging
• Network synchronization or cloud backup of settings

No test directory visible: Expect zero automated test coverage—changes require manual testing on actual macOS systems with multiple menu bar apps. Xcode workspace required: Use Ice.xcodeproj/project.xcworkspace (not .pbxproj directly) to resolve SPM dependencies correctly. macOS 14+ only: The app targets Sonoma or later—testing on older macOS versions will fail. Menu bar manipulation is fragile: Accessibility API changes in macOS updates can break core functionality; always test after major OS releases.

• macOS Accessibility API (AXUIElement) — Ice's core capability—detecting, identifying, and manipulating menu bar items—relies entirely on the Accessibility framework; understanding AX hierarchy and event forwarding is essential for menu bar logic changes.
• AppKit/SwiftUI Bridge — The app must integrate SwiftUI views with AppKit's NSStatusBar and NSMenu to display in the menu bar; this bridge is non-trivial and likely uses NSHostingController or similar patterns.
• macOS Menu Bar Layout & Constraints — Ice manipulates menu bar geometry (spacing, ordering, notch detection for MacBooks) under tight pixel/timing constraints; understanding macOS safe areas, Screen.main bounds, and menu bar reserved space is critical.
• SwiftUI State Management & Observation — The app must maintain state across hidden/shown items, user preferences, and drag-and-drop operations; understanding @State, @ObservedObject, and @EnvironmentObject patterns is essential for UI changes.
• Gesture Recognition (Hover, Scroll, Swipe) — Ice reveals hidden items via multiple gestures (hover, click, scroll, swipe); implementing these requires understanding NSGestureRecognizer, NSTrackingArea, and SwiftUI's gesture modifiers.
• macOS Preferences/Defaults Persistence — User settings (hidden items, spacing, colors) must survive app restarts; the app likely uses UserDefaults or Codable + file storage to persist state.

• dwarvesf/hidden — Alternative macOS menu bar hider; shows the same problem space and UI patterns (hide/show toggles, always-hidden sections).
• MonitorControl/MonitorControl — macOS menu bar utility for display control; demonstrates similar Accessibility API patterns and SwiftUI menu bar integration.
• Homebrew/homebrew-cask — Ice is distributed via Homebrew cask (brew install --cask jordanbaird-ice); this repo defines packaging and distribution.
• apple/swift — Swift language and stdlib; Ice is a pure Swift project, so language changes and stdlib additions directly affect development.

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 EventManager.swift and event monitoring

The repo has a linting workflow (.github/workflows/lint.yml) but no visible testing workflow. EventManager.swift and the Events/EventMonitors directory are critical for menu bar responsiveness, yet there's no test coverage evident in the file structure. Adding XCTest-based unit tests would catch regressions in event handling, a core feature of this menu bar manager.

• [ ] Create Tests/Events/EventManagerTests.swift with tests for event subscription/notification
• [ ] Add tests for EventMonitors/* to verify menu bar item detection and tracking
• [ ] Create a GitHub Actions workflow (.github/workflows/test.yml) to run tests on PRs
• [ ] Ensure tests cover edge cases like rapid menu bar changes and app launching/termination

Add integration tests for menu bar visibility toggling and item management

Ice's core functionality is hiding/showing menu bar items, but there are no visible integration tests verifying this behavior works across different macOS versions (app targets macOS 14+). This is high-risk functionality that affects user experience directly and deserves automated verification.

• [ ] Create Tests/Integration/MenuBarVisibilityTests.swift with tests that verify hide/show operations
• [ ] Add tests for the control item images (DotFill, EllipsisFill, IceCubeFill) rendering correctly when toggling visibility
• [ ] Test interaction between Ice.xcodeproj main app and menu bar accessibility APIs
• [ ] Document test setup requirements in a new TESTING.md file for contributors

Complete Swift Bridging layer documentation and add missing shims for accessibility APIs

The Ice/Bridging directory has Deprecated.swift and Private.swift shims, suggesting there are ObjC/C interop needs for menu bar access. However, there's minimal documentation about what macOS APIs are being bridged or why. Adding comprehensive documentation and identifying missing shims would reduce contributor friction and expose potential accessibility API improvements.

• [ ] Add Ice/Bridging/README.md documenting all bridged APIs (NSStatusBar, NSMenu, Accessibility framework usage)
• [ ] Audit Ice/Bridging/Shims/Private.swift for undocumented private API usage and add inline comments explaining each
• [ ] Create Ice/Bridging/Shims/Accessibility.swift for menu bar item detection APIs currently in Private.swift
• [ ] Update CODE_OF_CONDUCT.md with guidance on testing bridged APIs across macOS versions

• Add unit tests for menu bar item model classes (e.g., MenuBarItem, ControlItem): currently no Tests/ folder exists, so a contributor could create a test target and add foundational model tests to prevent regressions.
• Document the Accessibility API integration: add a DEVELOPMENT.md explaining how Ice detects and manipulates menu bar items via AXUIElement, since this is the repo's core complexity and currently has no inline guidance.
• Implement profile switching UI: the roadmap lists 'Profiles for menu bar layout' as unimplemented; a contributor could build the SwiftUI settings view and data model to save/load menu bar states.

The Ice menu bar manager codebase demonstrates a reasonable security posture for a macOS utility application. Primary concerns involve the use of accessibility APIs and private/deprecated Apple frameworks, which are common in menu bar tools but require careful permission handling and validation. No critical vulnerabilities were identified in the visible file structure. The application lacks explicit security documentation and update mechanisms. Recommendations focus on improving transparency around private API usage, strengthening accessibility permission flows, and establishing a formal security disclosure process.

• Medium · Potential Accessibility API Misuse — Ice/Events/EventTap.swift, Ice/Events/EventMonitors/. The codebase contains EventTap.swift and multiple EventMonitor implementations that interact with macOS accessibility APIs. These APIs require Accessibility permissions and can be leveraged to monitor or control user input. Without proper validation and user consent flows, this could lead to unintended system monitoring. Fix: Ensure explicit user consent dialogs before requesting accessibility permissions. Implement granular permission checks and log all accessibility API usage. Review entitlements in Ice.entitlements for proper scope.
• Medium · Bridging Code May Expose Private APIs — Ice/Bridging/Shims/Private.swift, Ice/Bridging/Shims/Deprecated.swift. The presence of Ice/Bridging/Shims/Private.swift and deprecated API shims suggests the use of private or deprecated macOS APIs. These are not guaranteed to be stable across OS versions and may contain undocumented security behaviors or restrictions. Fix: Audit all private API usage and migrate to public, stable APIs where possible. Document why private APIs are necessary. Implement feature flags for OS-version-specific code paths.
• Low · Missing Code Signing Configuration — Ice.xcodeproj/project.pbxproj, Ice/Ice.entitlements. While the project uses a standard Xcode project structure, the visible configuration files do not explicitly show code signing certificate pinning or entitlements validation mechanisms. Menu bar management tools should ensure their code signing is robust. Fix: Ensure code signing with a developer certificate. Implement entitlements review process. Consider code signing verification at runtime for critical components.
• Low · Hotkey Registration Without Input Validation — Ice/Hotkeys/HotkeyRegistry.swift, Ice/Hotkeys/KeyCombination.swift, Ice/Hotkeys/KeyCode.swift. The Ice/Hotkeys/ directory contains HotkeyRegistry.swift and KeyCombination.swift. Global hotkey registration requires careful validation to prevent key event hijacking or unintended system shortcuts being registered. Fix: Validate all hotkey combinations against system-reserved shortcuts. Implement whitelist of allowed key codes. Log hotkey registration and provide user control to modify/revoke hotkeys.
• Low · No Visible Security Update Mechanism — .github/, README. The application appears to be distributed via GitHub releases. There is no visible mechanism for security updates or vulnerability disclosure process in the repository structure. Fix: Create a SECURITY.md file with vulnerability disclosure policy. Implement auto-update mechanism with signature verification. Add security policy to GitHub repository.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

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/jordanbaird/Ice 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.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jordanbaird/Ice repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jordanbaird/Ice.

What it runs against: a local clone of jordanbaird/Ice — 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 jordanbaird/Ice | 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 ≤ 261 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jordanbaird/Ice(\\.git)?\\b" \\
  && ok "origin remote is jordanbaird/Ice" \\
  || miss "origin remote is not jordanbaird/Ice (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 "Ice/Main/IceApp.swift" \\
  && ok "Ice/Main/IceApp.swift" \\
  || miss "missing critical file: Ice/Main/IceApp.swift"
test -f "Ice/Main/AppState.swift" \\
  && ok "Ice/Main/AppState.swift" \\
  || miss "missing critical file: Ice/Main/AppState.swift"
test -f "Ice/MenuBar/ControlItem/ControlItem.swift" \\
  && ok "Ice/MenuBar/ControlItem/ControlItem.swift" \\
  || miss "missing critical file: Ice/MenuBar/ControlItem/ControlItem.swift"
test -f "Ice/Events/EventManager.swift" \\
  && ok "Ice/Events/EventManager.swift" \\
  || miss "missing critical file: Ice/Events/EventManager.swift"
test -f "Ice/MenuBar/Appearance/MenuBarAppearanceManager.swift" \\
  && ok "Ice/MenuBar/Appearance/MenuBarAppearanceManager.swift" \\
  || miss "missing critical file: Ice/MenuBar/Appearance/MenuBarAppearanceManager.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 261 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~231d)"
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/jordanbaird/Ice"
  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).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.