KeyChord

Switching apps should feel like playing chords — different key chords open different apps.

KeyChord is a high-performance, lightweight native macOS menu-bar app built around a simple design philosophy: making app switching like playing chords on a keyboard. Just as a musician plays different key chords to evoke different harmonies, KeyChord allows you to map unique key combinations ("chords") to instantly activate, toggle, or launch your target applications.

Designed as a sleek, permission-free alternative to heavy application-switching macros (such as Keyboard Maestro setups), KeyChord utilizes native Carbon global hotkeys and AppKit window activation—delivering instant, low-latency app switching without requiring Accessibility or Input Monitoring permissions.

---

🎵 Design Philosophy

KeyChord was born from a desire for seamless, muscle-memory-driven workflow navigation:

• 🎹 Chords as Shortcuts: Map distinct key combinations (chords) to your essential apps. Hitting a chord instantly switches focus to that app.
• 🎶 Musical Fluidity: Move between your code editor, terminal, browser, and notes with the natural rhythm of playing piano chords.
• ⚡ Zero Friction: Low-latency, lightweight execution with zero intrusive accessibility hooks or performance overhead.

---

🌟 Key Features

• ⚡ Instant App Switching: Activate or bring all windows of target applications to the front with configurable global hotkeys.
• 🔄 Smart Window Toggling: Pressing the same hotkey while a target application is active automatically hides it.
• 🛡️ Permission-Free: Operates natively via Carbon hotkeys and AppKit activation services—no Accessibility, Accessibility APIs, or Input Monitoring privileges needed.
• ⚙️ Native SwiftUI Settings: Comprehensive preferences panel to add/remove apps, record hotkeys, toggle launch-on-login, configure Dock & menu-bar icon visibility, and tune per-app activation rules.
• 🚀 Optional App Launching: Per-shortcut setting (launchIfNeeded) to optionally launch stopped target applications upon pressing their hotkey.
• ⚠️ Conflict Detection & Migration: Built-in detection for running Keyboard Maestro instances and system hotkey collisions, with clear UI indicators.
• 🛠️ Rich Command-Line Interface: CLI support for configuration validation, hotkey collision probing, default config dumping, version inspection, and diagnostic self-tests.

---

📋 Requirements

Requirement	Specification
Operating System	macOS 14.0 (Sonoma) or later
Developer Tools	Swift 6.2 / Xcode 15+ toolchain
Permissions	None (No Accessibility or Input Monitoring required)

---

🚀 Quick Start & Installation

1. Build & Run from Source

To run self-tests and start the application in development mode:

# Run internal self-tests
swift run KeyChord --self-test

# Launch KeyChord directly
swift run KeyChord

2. Package as a Native macOS Application

Use the provided packaging script to compile the release binary and assemble a signed .app bundle:

./scripts/package-app.sh

The compiled application bundle will be created at:

.build/KeyChord.app

Note on Code Signing: The build script automatically signs the bundle using the first available local code-signing identity, falling back to ad-hoc signing (-) if none exists.

---

⚙️ Configuration

On initial execution, KeyChord creates a default configuration file at:

~/Library/Application Support/KeyChord/config.json

Configuration Schema

{
  "version": 1,
  "settings": {
    "showDockIcon": true,
    "showMenuBarIcon": true,
    "launchAtLogin": false
  },
  "shortcuts": [
    {
      "id": "finder",
      "name": "Finder",
      "bundleIdentifier": "com.apple.finder",
      "key": "1",
      "modifiers": ["option"],
      "enabled": true,
      "launchIfNeeded": true,
      "hideWhenFrontmost": true,
      "activateAllWindows": true
    }
  ]
}

Configuration Fields

• settings:
  • showDockIcon: Toggles visibility of the application in the macOS Dock.
  • showMenuBarIcon: Toggles visibility of the status item in the menu bar.
  • launchAtLogin: Configures automatic startup via SMAppService.
• shortcuts[]:
  • id: Unique identifier string for the shortcut entry.
  • name: Display label shown in the UI and menu.
  • bundleIdentifier: macOS bundle identifier for target application (e.g., com.apple.finder).
  • key: Key character or code representation.
  • modifiers: Array of modifier strings ("command", "control", "option", "shift").
  • enabled: Boolean toggle to enable or disable the shortcut.
  • launchIfNeeded: If true, launches target application when it is not currently running.
  • hideWhenFrontmost: If true, pressing hotkey when target app is active hides the app.
  • activateAllWindows: If true, brings all app windows to front; if false, brings front window only.

Security & Validation: Configuration files are strictly validated before registering hotkeys. Malformed, duplicate, or invalid definitions fail closed, leaving shortcuts safely unregistered without crashing.

---

💻 Command-Line Options (CLI)

KeyChord includes utility flags for automation, diagnostics, and testing:

Flag	Description
-v, --version	Display application name and version details
--show-settings	Force open the settings window on launch
--probe-hotkeys	Test hotkey registration against system conflicts without starting the app loop
--validate-config <PATH>	Validate a specified config.json file for structural correctness
--print-default-config	Output default configuration JSON to stdout
--self-test	Execute internal diagnostic and behavioral unit tests

Examples

# Check version
KeyChord --version
# Output: KeyChord v1.2.0 (build 5)

# Test shortcut registration for system conflicts
KeyChord --probe-hotkeys

# Validate custom configuration file
KeyChord --validate-config ~/Desktop/my_config.json

---

🔄 Migrating from Keyboard Maestro

If migrating from Keyboard Maestro:

1. Parallel Execution: Both Keyboard Maestro and KeyChord can temporarily receive the same hotkey, which may cause activation races.
2. Conflict Warnings: KeyChord displays a migration banner in the status menu when Keyboard Maestro Engine is detected running.
3. Completing Migration: Disable your Keyboard Maestro App switcher macro group or quit the Keyboard Maestro Engine once KeyChord is tested and configured.

---

📁 Repository Structure

key-chord/
├── Package.swift               # Swift Package Manager manifest
├── README.md                   # Project documentation
├── Sources/
│   └── KeyChord/
│       ├── AppDelegate.swift   # App lifecycle, menu item & Dock management
│       ├── ApplicationSwitcher.swift # Window activation & hide engine
│       ├── ConfigurationStore.swift  # Config storage & JSON persistence
│       ├── HotKeyManager.swift # Carbon global hotkey registration
│       ├── Models.swift        # Data models, validation & version info
│       ├── SelfTest.swift      # Built-in diagnostic test suite
│       ├── SettingsView.swift  # SwiftUI settings panel & preferences
│       ├── SettingsViewModel.swift # Settings state manager
│       ├── SettingsWindowController.swift # Settings window manager
│       ├── ShortcutRecorder.swift # Key recorder control
│       └── main.swift          # Entry point & CLI argument parser
├── packaging/
│   ├── AppIcon.png             # Application logo image
│   ├── AppIcon.icns            # macOS ICNS icon bundle
│   └── Info.plist              # macOS App bundle property list
└── scripts/
    └── package-app.sh          # Build & code-signing script

---

🧪 Testing

To run internal self-tests for hotkey handling, shortcut key code resolution, application state toggling, and configuration validation:

swift run KeyChord --self-test

---

📄 Versioning

Current Version: 1.2.0 (Build 5)

Changes in v1.2.0:

• Added usage statistics: KeyChord now counts the chords it handled itself, with a Statistics pane in settings (today, daily average, 30-day total, per-app leaderboard and a 14-day chart).
• Counters live in a separate usage.json (0600), are kept for 30 days and pruned on every write; no new macOS permissions are required.
• Added a Record usage statistics toggle to turn the counters off entirely.
• Added an app icon resource, richer Info.plist metadata and versioned .zip / .dmg output from the packaging script.
• Added a Statistics section to the landing page.

Changes in v1.1.2:

• Reopen a window when activating a running app whose windows were all closed, matching the behaviour of clicking its Dock icon.
• Added self-test coverage for the workspace reopen path.

Changes in v1.1.1:

• Added an immediate conflict dialog when assigning a shortcut already used by another app.
• Added one-click shortcut reassignment that disables the previous owner and enables the new one.
• Kept validation errors visible in the fixed save bar while scrolling the application list.
• Simplified Keyboard Maestro conflict detection by making its warning automatic.

Changes in v1.1.0:

• Added native SwiftUI settings window with shortcut recorder.
• Added support for launch at login, menu bar / Dock visibility settings.
• Added per-app window activation & hide controls.
• Added --version CLI flag and centralized version management.