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/nchudleigh/vimac 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 3y ago

• 3 active contributors
• GPL-3.0 licensed
• ⚠ Stale — last commit 3y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ 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 nchudleigh/vimac repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nchudleigh/vimac.

What it runs against: a local clone of nchudleigh/vimac — 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 nchudleigh/vimac | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1256 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "ViMac-Swift/AppDelegate.swift" \\
  && ok "ViMac-Swift/AppDelegate.swift" \\
  || miss "missing critical file: ViMac-Swift/AppDelegate.swift"
test -f "ViMac-Swift/ModeCoordinator.swift" \\
  && ok "ViMac-Swift/ModeCoordinator.swift" \\
  || miss "missing critical file: ViMac-Swift/ModeCoordinator.swift"
test -f "ViMac-Swift/Modes/HintModeController.swift" \\
  && ok "ViMac-Swift/Modes/HintModeController.swift" \\
  || miss "missing critical file: ViMac-Swift/Modes/HintModeController.swift"
test -f "ViMac-Swift/Accessibility/HintMode/HintModeQueryService.swift" \\
  && ok "ViMac-Swift/Accessibility/HintMode/HintModeQueryService.swift" \\
  || miss "missing critical file: ViMac-Swift/Accessibility/HintMode/HintModeQueryService.swift"
test -f "ViMac-Swift/InputListener.swift" \\
  && ok "ViMac-Swift/InputListener.swift" \\
  || miss "missing critical file: ViMac-Swift/InputListener.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 1256 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1226d)"
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/nchudleigh/vimac"
  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).

Vimac is a macOS productivity app that enables keyboard-driven GUI navigation and control using a Vim-inspired workflow. Users activate modes (Hint-mode for clicking UI elements, Scroll-mode for scrolling) and interact via keyboard shortcuts; Hint-mode generates labeled hints (e.g., 'ka') for interactive elements that can be clicked/double-clicked/right-clicked without touching the mouse. Single-app project structure: ViMac-Swift/ contains the core app code organized by feature (Accessibility/, HintMode/, etc.), with Carthage managing the LaunchAtLogin external dependency. The app follows a mode-based architecture where HintModeQueryService, ScrollModeQueryService, and related classes traverse the accessibility tree to generate interactive hints.

macOS power users and keyboard enthusiasts who want Vim-like navigation across any application's GUI without reaching for the mouse; developers who appreciate terminal-first workflows and want that productivity in graphical applications.

The project is production-ready but dormant—the creator has moved on to a commercial successor called Homerow (announced in README). The codebase is substantial (199KB Swift) and was actively maintained, but the README explicitly states 'Vimac is now Homerow,' indicating the original project is no longer the focus of development.

Single-maintainer risk is high: the original creator has shifted to a commercial product (Homerow), leaving this repo in maintenance-only mode with no active development signals. Dependency on Carthage (LaunchAtLogin framework) and CocoaPods adds maintenance burden; the accessibility API integration with macOS is version-sensitive and could break on major OS updates.

No active development—the repo appears frozen in favor of the commercial Homerow successor. No recent commits, PRs, or milestones are visible from the provided file structure. This is a snapshot of a completed, unmaintained open-source project.

git clone https://github.com/nchudleigh/vimac.git
cd vimac
pod install
carthage build
open Vimac.xcworkspace

Then modify code signing (disable library validation) and grant Vimac accessibility permissions in System Preferences.

Daily commands: Open Vimac.xcworkspace in Xcode and build. The app runs as a macOS productivity daemon—once running, hold Space (default binding) to activate Hint-mode. Follow the 'Building' section in README: grant accessibility permissions, then build. The grant-accessibility-permission-dev.scpt script automatically re-grants permissions after each build.

• ViMac-Swift/AppDelegate.swift — Application entry point and lifecycle management; sets up the mode coordinator and overlay window that drive all keyboard-driven navigation features.
• ViMac-Swift/ModeCoordinator.swift — Core orchestrator that switches between Hint-mode and Scroll-mode; manages activation/deactivation lifecycle that all features depend on.
• ViMac-Swift/Modes/HintModeController.swift — Primary Hint-mode implementation; generates hints for UI elements and processes user input—the flagship feature of Vimac.
• ViMac-Swift/Accessibility/HintMode/HintModeQueryService.swift — Service that discovers and traverses accessible UI elements; foundation for hint generation on any macOS window.
• ViMac-Swift/InputListener.swift — Global event tap and keyboard input handler; captures user key presses that activate modes and control navigation.
• ViMac-Swift/OverlayWindow.swift — Renders hint labels and visual overlays on top of the frontmost application; critical for hint visibility and interaction feedback.
• ViMac-Swift/Modes/ScrollModeController.swift — Scroll-mode implementation for keyboard-driven scrolling; demonstrates secondary mode pattern used in the application.

Add a New Mode (e.g., Focus-mode for window selection)

1. Create a new ModeController subclass in ViMac-Swift/Modes/NewModeController.swift that inherits from ModeController and implements enter(), exit(), and handleInput() methods. (ViMac-Swift/Modes/NewModeController.swift)
2. Add a new case to the mode enum and register the controller instance in ModeCoordinator.swift's initialization or activate() method. (ViMac-Swift/ModeCoordinator.swift)
3. Create a new preference view controller in ViMac-Swift/Preferences/NewModePreferenceViewController.swift to expose mode-specific settings. (ViMac-Swift/Preferences/NewModePreferenceViewController.swift)
4. Register the preference pane in PreferencesPaneIdentifiers.swift and add it to the preferences window in Main.storyboard. (ViMac-Swift/Preferences/PreferencesPaneIdentifiers.swift)
5. Update InputListener.swift or create a NewModeInputListener.swift to handle mode-specific keybindings and route them to the new mode controller. (ViMac-Swift/InputListener.swift)

Add Support for a New UI Element Type in Hint-mode

1. Create a new traversal service in ViMac-Swift/Accessibility/HintMode/ (e.g., TraverseCustomElementService.swift) that implements the ElementTraversalService protocol. (ViMac-Swift/Accessibility/HintMode/TraverseElementService.swift)
2. Implement filtering logic to identify and collect your custom UI element type from the accessibility tree, checking role, subrole, and actionability. (ViMac-Swift/Accessibility/HintMode/TraverseGenericElementService.swift)
3. Register the new service in TraverseElementServiceFinder.swift so HintModeQueryService discovers and uses it during element traversal. (ViMac-Swift/Accessibility/HintMode/TraverseElementServiceFinder.swift)
4. Test hint generation on windows containing your element type; verify hints appear and clicks are routed correctly via HintModeController.swift. (ViMac-Swift/Modes/HintModeController.swift)

Add a New User Preference Setting

1. Define the preference key and default value in the appropriate BindingsConfig.swift or a new config file. (ViMac-Swift/Bindings/BindingsConfig.swift)
2. Add getter/setter methods in BindingsRepository.swift to read/write the preference to UserDefaults with type safety. (ViMac-Swift/Bindings/BindingsRepository.swift)
3. Create or update a preference view controller (e.g., GeneralPreferenceViewController.swift) to expose the new setting in the preferences window UI. (ViMac-Swift/Preferences/GeneralPreferenceViewController.swift)
4. Observe the preference change in the relevant controller (HintModeController.swift or ScrollModeController.swift) using KVO or reactive bindings and apply the setting immediately. (ViMac-Swift/Modes/HintModeController.swift)

Customize Hint Appearance (Font, Colors, Size)

1. Add new preference keys to HintModePreferenceViewController.swift for font size, text color, background color, and corner radius. (ViMac-Swift/Preferences/HintModePreferenceViewController)

1. Accessibility permission reset on clean build: The grant-accessibility-permission-dev.scpt script must succeed or Vimac loses accessibility permissions and becomes non-functional—keep System Preferences open with Accessibility unlocked during development. 2. Signing entitlements drift: ViMac_Swift.entitlements and project.pbxproj will be modified during setup (you must disable library validation); avoid committing these changes. 3. Carthage checkout size: LaunchAtLogin is a large external dependency pulled into Carthage/Checkouts/; first build is slow. 4. macOS version fragility: Accessibility API behavior varies significantly between macOS versions (e.g., menu bar structure changed in Big Sur+); hints may fail to generate on unsupported OS versions.

• AXUIElement (Accessibility API) — Core of Vimac—AXUIElement is the macOS framework for querying and interacting with UI elements programmatically; understanding its capabilities and limitations is essential for modifying hint generation
• Accessibility Tree Traversal — Vimac must recursively walk the accessibility hierarchy to find all interactive elements; inefficient traversal causes performance problems and missed UI elements
• Mode-Based State Machine — Vimac's architecture (Hint-mode, Scroll-mode, etc.) is a finite state machine where each mode has different keyboard bindings and behaviors; understanding state transitions is critical for adding new modes
• Hint Label Generation Algorithm — Vimac must assign unique, memorable labels (e.g., 'ka', 'jx') to interactive elements; the algorithm balances brevity with uniqueness—this is non-trivial for windows with 50+ elements
• macOS Accessibility Permissions Model — Vimac cannot function without being listed in System Preferences > Security & Privacy > Accessibility; the permission model is strict and resets on clean builds, requiring the grant-accessibility-permission-dev.scpt workaround
• Carthage Dependency Management — Vimac uses Carthage (not CocoaPods exclusively) for binary dependency management of LaunchAtLogin; understanding Carthage is needed for updating or replacing external dependencies
• AppleScript Integration for Build Automation — The grant-accessibility-permission-dev.scpt script automates permission re-granting post-build; understanding AppleScript UI automation is valuable for extending developer tooling

• philc/vimium — Direct inspiration for Vimac; Vimium brings Vim navigation to web browsers, proving the concept that hint-based keyboard control is intuitive for power users
• subhaditya-mukherjee/vimium-c — Modern maintained fork of Vimium with extended features; demonstrates active development in the keyboard-navigation space while Vimac is dormant
• jhawthorn/fzf.vim — Complements Vimac ecosystem—fzf provides fuzzy search in Vim, addressing the file/command discovery problem while Vimac handles GUI element navigation
• homerow/homerow — The official successor to Vimac; built by the same author with lessons learned, now commercial, represents the evolution of this project
• sindresorhus/LaunchAtLogin-Modern — Modern alternative to the LaunchAtLogin dependency used here; useful for understanding contemporary macOS auto-launch patterns

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 Element.swift and ElementTree.swift accessibility layer

The Accessibility module (ViMac-Swift/Accessibility/) contains critical core logic for traversing UI elements and building element trees, but there are no visible test files in the repo. This is high-risk code that directly impacts hint generation and element detection. Adding unit tests would catch regressions early and make refactoring safer.

• [ ] Create ViMac-Swift/AccessibilityTests/ directory with test target
• [ ] Write tests for Element.swift covering element property access, filtering, and equality
• [ ] Write tests for ElementTree.swift covering tree construction, traversal, and filtering logic
• [ ] Add tests for TraverseGenericElementService.swift to validate element discovery heuristics
• [ ] Integrate tests into build scheme and verify they run on CI

Add GitHub Actions workflow for Swift linting and build verification

The repo uses Carthage for dependency management and CocoaPods (Podfile exists), but there's no visible CI/CD pipeline (no .github/workflows/ directory shown). A basic Swift lint + build verification workflow would catch syntax errors and integration issues before merge, especially important given the macOS accessibility API complexity.

• [ ] Create .github/workflows/swift-ci.yml
• [ ] Add steps to run swiftlint on ViMac-Swift/ directory (configure .swiftlint.yml if needed)
• [ ] Add steps to build with xcodebuild (targeting macOS)
• [ ] Add step to run any test suite created in previous PR
• [ ] Configure workflow to trigger on push and pull requests to main branch

Extract and document HintMode service layer architecture

The HintMode/ directory contains 7 specialized services (QueryMenuBarExtrasService, TraverseElementService, etc.) with interdependent responsibilities, but there's no architecture documentation explaining their purpose, dependencies, or how they compose. This is a barrier to new contributors understanding how hint generation works.

• [ ] Create ViMac-Swift/Accessibility/HintMode/ARCHITECTURE.md documenting the service pattern
• [ ] Map out the dependency graph between HintModeQueryService, TraverseElementService, and specialized traversal services
• [ ] Document why TraverseSearchPredicateCompatibleWebAreaElementService exists separately (web area special handling)
• [ ] Add inline documentation comments to each service's key methods explaining responsibility and inputs/outputs
• [ ] Create a diagram (ASCII or image) showing service composition and data flow

• Add unit tests for TraverseElementService.swift hint labeling algorithm (currently no test files visible in HintMode/)—test edge cases like deeply nested elements, hidden elements, and duplicate labels.
• Document the accessibility tree traversal order in a code comment or developer guide; new contributors struggle to understand why certain UI elements get hints before others.
• Extend QueryMenuBarItemsService.swift to support custom menu bar apps (e.g., third-party status bar apps)—currently only handles system menu bar, missing many common productivity tools.

The Vimac codebase demonstrates moderate security posture. Primary concerns include dependency management practices (checked-in Carthage dependencies, use of shell scripts), extensive accessibility API usage requiring careful input validation, and lack of formal security disclosure policy. The application's core functionality relies on system-level event interception which requires careful implementation. No critical vulnerabilities were identified in the visible codebase structure, but the use of multiple dependency managers and checked-in dependency code increases maintenance complexity. The project has been succeeded by Homerow, which should be considered for new deployments. Recommended improvements focus on consolidating dependency management, documenting security practices, and conducting thorough security audits of accessibility and input handling modules.

• Medium · Carthage Dependency Management Risk — Carthage/Checkouts/LaunchAtLogin/Sources/LaunchAtLogin/. The project uses Carthage with checked-in dependencies in the Carthage/Checkouts directory. This includes the LaunchAtLogin framework with multiple shell scripts (copy-helper.sh, copy-helper-swiftpm.sh). Checked-in dependencies and shell scripts increase the attack surface and make it difficult to audit dependency updates. Fix: Consider using SPM (Swift Package Manager) instead of Carthage, add Carthage/Checkouts to .gitignore to avoid checking in dependencies, and regularly audit shell scripts for security issues. Verify the integrity of LaunchAtLogin framework versions.
• Medium · Shell Scripts in Dependencies — Carthage/Checkouts/LaunchAtLogin/Sources/LaunchAtLogin/copy-helper.sh and copy-helper-swiftpm.sh. The LaunchAtLogin dependency contains shell scripts (copy-helper.sh, copy-helper-swiftpm.sh) that execute during build time. These scripts are not visible in the provided analysis but represent a potential vector for supply chain attacks if the dependency is compromised. Fix: Audit these shell scripts for security issues, verify their necessity, consider replacing with Swift-based build scripts where possible, and implement strict code review processes for any changes.
• Medium · Accessibility Framework Usage — ViMac-Swift/Accessibility/. The application extensively uses macOS Accessibility APIs (multiple files in ViMac-Swift/Accessibility/). While necessary for the application's functionality, this requires broad system permissions and could be exploited if input handling is not carefully implemented. Fix: Implement strict input validation and sanitization in all accessibility-related modules. Conduct security review of Element.swift, ElementTree.swift, and all TraverseElementService implementations to prevent injection attacks through UI elements.
• Low · Global Event Tap Usage — ViMac-Swift/GlobalEventTap.swift. The application uses GlobalEventTap.swift to intercept global keyboard events. This is a sensitive operation that requires careful implementation to prevent unintended behavior or security issues. Fix: Review implementation for proper event filtering, ensure sensitive information (passwords, tokens) is not logged or captured inadvertently, and validate all event processing logic.
• Low · No Visible Security Policy or Disclosure — Repository root. The repository does not include a SECURITY.md or security policy file for responsible vulnerability disclosure. The README mentions the project has been succeeded by Homerow but lacks security guidance. Fix: Create a SECURITY.md file with vulnerability disclosure procedures. Include security best practices documentation for users and contributors.
• Low · CocoaPods Dependency Management — Podfile and Podfile.lock. The project uses CocoaPods (Podfile present) in addition to Carthage, which adds complexity to dependency management. Multiple dependency managers increase the risk of inconsistent versions or missed security updates. Fix: Consolidate to a single dependency manager (preferably SPM). Keep Podfile.lock committed and regularly audit dependencies for known vulnerabilities using tools like CocoaPods Security Advisory.

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.