Add configurable hotkeys and release automation

Restructure app startup around an app coordinator, improve Input Monitoring permission handling, and make the menu bar shortcut configurable. Also add repo scaffolding for docs, builds, and GitHub Actions release automation.

Author: Rajul

.github/workflows/build.yml

@@ -0,0 +1,41 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build & Verify Universal Binary
+    runs-on: macos-26
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Xcode version
+        run: xcodebuild -version
+
+      - name: Build Universal Binary
+        run: make build
+
+      - name: Verify app bundle
+        run: make verify-app
+
+      - name: Verify Universal Binary (arm64 + x86_64)
+        run: make verify-universal
+
+      - name: Create distribution
+        run: make dist-app
+
+      - name: Upload app artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: kutuk-app
+          path: dist/Kutuk.app
+          retention-days: 14

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build & Release Universal Binary
+    runs-on: macos-26
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Xcode version
+        run: xcodebuild -version
+
+      - name: Build Universal Binary
+        run: make build
+
+      - name: Verify Universal Binary (arm64 + x86_64)
+        run: make verify-universal
+
+      - name: Create distribution
+        run: make dist-app
+
+      - name: Create DMG
+        run: make dmg
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/Kutuk-Release.dmg
+          generate_release_notes: true
+          draft: false
+          prerelease: false

.gitignore

@@ -0,0 +1,40 @@
+# Xcode
+build/
+DerivedData/
+*.xcuserdata
+*.xcscmblueprint
+*.xccheckout
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon?
+._*
+.Spotlight-V100
+.Trashes
+
+# Distribution
+dist/
+
+# Archives
+*.xcarchive
+*.profraw
+*.profdata
+
+# CocoaPods
+Pods/
+
+# Swift Package Manager
+.build/
+Package.resolved
+
+# Carthage
+Carthage/Build/
+
+# IDE
+*.swp
+*.swo
+*~
+.vscode/
+.idea/

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to Kutuk
+
+Thanks for your interest in contributing to Kutuk! Here's how to get started.
+
+## Development Setup
+
+1. **Requirements**: Xcode 15+ and macOS 14+
+2. Clone the repo and open `kutuk.xcodeproj` in Xcode
+3. Build and run with `Cmd+R`, or use `make build` from the terminal
+
+## Building from Terminal
+
+```bash
+# Build the app
+make build
+
+# Create distributable app bundle (ad-hoc signed)
+make dist-app
+
+# Create DMG installer
+make dmg
+
+# Clean build artifacts
+make clean
+```
+
+## Project Structure
+
+- `kutuk/` — Main source directory
+  - `kutukApp.swift` — App entry point
+  - `Views/` — SwiftUI menu bar UI
+  - `Services/` — Keyboard monitoring, audio engine, hotkey management
+  - `Settings/` — UserDefaults persistence
+  - `Models/` — Data models (sound packs, hotkey shortcuts)
+  - `Resources/Sounds/` — Sound pack WAV files
+  - `Assets.xcassets/` — App and menu bar icons
+
+## Adding a Sound Pack
+
+1. Create a new folder under `kutuk/Resources/Sounds/` with your pack ID
+2. Add WAV files following the naming convention: `{packId}_{keyType}_{event}_{variation}.wav`
+3. Register the pack in `SoundPack.swift`
+
+## Submitting Changes
+
+1. Fork the repo and create a feature branch
+2. Make your changes
+3. Test the app locally (`make build && make dist-app`)
+4. Open a pull request with a clear description
+
+## Code Style
+
+- Follow standard Swift conventions
+- Use SwiftUI for all UI components
+- Keep services loosely coupled via the coordinator pattern
+
+## Reporting Issues
+
+Open a GitHub issue with steps to reproduce, expected behavior, and your macOS version.

IMPLEMENTATION.md

@@ -26,7 +26,7 @@ kutuk/
 ├── Info.plist                  # LSUIElement=true (no dock icon)
 ├── kutuk.entitlements          # App sandbox
 ├── Models/
-│   └── SoundPack.swift         # KeyType, KeyEvent, SoundPack struct
+│   └── SoundPack.swift         # KeyType, KeyEvent, single-pack SoundPack struct
 ├── Services/
 │   ├── SoundEngine.swift       # AVAudioEngine, polyphony pool
 │   ├── KeyboardMonitor.swift   # CGEvent tap, key classification
@@ -37,7 +37,7 @@ kutuk/
 │   ├── MenuBarView.swift       # Main dropdown UI
 │   └── OnboardingView.swift    # Permission request
 └── Resources/
-    └── Sounds/                 # 81 MP3 files
+    └── Sounds/                 # 16 Cherry MX Blue WAV files
 ```
 
 ---
@@ -74,11 +74,11 @@ kutuk/
 ```
 
 Examples:
-- `cherry-mx-blue_regular_press_1.mp3`
-- `topre_space_release.mp3`
-- `buckling-spring_enter_press.mp3`
+- `cherry-mx-blue_regular_press_1.wav`
+- `cherry-mx-blue_space_release.wav`
+- `cherry-mx-blue_modifier_press.wav`
 
-Packs: `cherry-mx-blue`, `cherry-mx-brown`, `cherry-mx-red`, `topre`, `buckling-spring`
+Pack: `cherry-mx-blue`
 
 Key types: `regular`, `space`, `enter`, `backspace`, `modifier`
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rajul Jain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,69 @@
+PROJECT := kutuk.xcodeproj
+SCHEME := kutuk
+CONFIGURATION ?= Release
+DESTINATION ?= generic/platform=macOS
+DERIVED_DATA := $(CURDIR)/build/DerivedData
+BUILD_PRODUCTS_DIR := $(DERIVED_DATA)/Build/Products/$(CONFIGURATION)
+APP_NAME := Kutuk
+APP_BUNDLE := $(BUILD_PRODUCTS_DIR)/$(APP_NAME).app
+DIST_DIR := $(CURDIR)/dist
+DIST_APP_BUNDLE := $(DIST_DIR)/$(APP_NAME).app
+DMG_STAGING_DIR := $(DIST_DIR)/dmg
+DMG_VOLUME_NAME ?= Kutuk
+DMG_NAME ?= Kutuk-$(CONFIGURATION).dmg
+DMG_PATH := $(DIST_DIR)/$(DMG_NAME)
+BUNDLE_IDENTIFIER ?= io.github.irajul.kutuk
+
+# Build flags: Universal Binary (Intel + Apple Silicon), no code signing for CI
+XCODEBUILD_FLAGS ?= \
+	CODE_SIGNING_ALLOWED=NO \
+	ONLY_ACTIVE_ARCH=NO \
+	ARCHS="arm64 x86_64"
+
+.PHONY: build dist-app dmg clean verify-app verify-universal
+
+build:
+	xcodebuild \
+		-project "$(PROJECT)" \
+		-scheme "$(SCHEME)" \
+		-configuration "$(CONFIGURATION)" \
+		-destination "$(DESTINATION)" \
+		-derivedDataPath "$(DERIVED_DATA)" \
+		build \
+		$(XCODEBUILD_FLAGS)
+
+verify-app: build
+	@test -d "$(APP_BUNDLE)" || (echo "Expected app bundle not found at $(APP_BUNDLE)" && exit 1)
+
+verify-universal: verify-app
+	@echo "Checking Universal Binary architectures..."
+	@lipo -info "$(APP_BUNDLE)/Contents/MacOS/$(APP_NAME)" | grep -q "arm64" || (echo "Missing arm64 architecture" && exit 1)
+	@lipo -info "$(APP_BUNDLE)/Contents/MacOS/$(APP_NAME)" | grep -q "x86_64" || (echo "Missing x86_64 architecture" && exit 1)
+	@echo "Universal Binary verified: arm64 + x86_64"
+
+dist-app: verify-app
+	rm -rf "$(DIST_APP_BUNDLE)"
+	mkdir -p "$(DIST_DIR)"
+	ditto "$(APP_BUNDLE)" "$(DIST_APP_BUNDLE)"
+	codesign --force --deep --sign - --identifier "$(BUNDLE_IDENTIFIER)" "$(DIST_APP_BUNDLE)"
+	@echo "App bundle created at $(DIST_APP_BUNDLE)"
+
+dmg: dist-app
+	rm -rf "$(DMG_STAGING_DIR)" "$(DMG_PATH)"
+	mkdir -p "$(DMG_STAGING_DIR)"
+	ditto "$(DIST_APP_BUNDLE)" "$(DMG_STAGING_DIR)/$(APP_NAME).app"
+	ln -s /Applications "$(DMG_STAGING_DIR)/Applications"
+	hdiutil create \
+		-volname "$(DMG_VOLUME_NAME)" \
+		-srcfolder "$(DMG_STAGING_DIR)" \
+		-ov \
+		-format UDZO \
+		"$(DMG_PATH)"
+	@if [ -n "$(DMG_CODESIGN_IDENTITY)" ]; then \
+		codesign --force --sign "$(DMG_CODESIGN_IDENTITY)" --timestamp "$(DMG_PATH)"; \
+	fi
+	rm -rf "$(DMG_STAGING_DIR)"
+	@echo "DMG created at $(DMG_PATH)"
+
+clean:
+	rm -rf "$(CURDIR)/build" "$(DIST_DIR)"

README.md

@@ -0,0 +1,76 @@
+# Kutuk
+
+Mechanical keyboard sounds for your Mac. Kutuk plays satisfying Cherry MX Blue click sounds as you type, running quietly in your menu bar.
+
+![macOS](https://img.shields.io/badge/macOS-14.0%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Build](https://img.shields.io/github/actions/workflow/status/irajul/kutuk/build.yml?branch=main)
+
+## Features
+
+- Cherry MX Blue mechanical keyboard sounds with natural variation
+- Universal Binary: runs natively on both Apple Silicon and Intel Macs
+- Menu bar app with no dock icon clutter
+- Global hotkey toggle (default: Option+Command+K)
+- Volume control and sound pack selection
+- Launch at Login support
+
+## Install
+
+### Download
+
+Grab the latest DMG from [Releases](https://github.com/irajul/kutuk/releases), open it, and drag **Kutuk.app** into Applications.
+
+### Important: First Launch
+
+Since Kutuk is not notarized (it's a free open-source app), macOS Gatekeeper will block it. You need to remove the quarantine attribute before the first launch:
+
+```bash
+xattr -cr /Applications/Kutuk.app
+```
+
+Then open the app normally. You'll also need to grant **Input Monitoring** permission when prompted (System Settings > Privacy & Security > Input Monitoring).
+
+### Build from Source
+
+```bash
+git clone https://github.com/irajul/kutuk.git
+cd kutuk
+make build        # Build the app
+make dist-app     # Create ad-hoc signed distribution
+make dmg          # Create DMG installer
+```
+
+Requires Xcode 16+ and macOS 14+.
+
+## Usage
+
+Once running, Kutuk appears as a small icon in your menu bar. Click it to:
+
+- Toggle sounds on/off
+- Adjust volume
+- Switch sound packs
+- Configure the global hotkey
+- Set launch at login
+
+## Permissions
+
+Kutuk requires **Input Monitoring** permission to detect keystrokes. It listens in read-only mode and never records, stores, or transmits any keystrokes. You can verify this in the source code — the event tap uses `.listenOnly` mode.
+
+### Granting Permission
+
+1. When prompted, click **Grant Input Monitoring** in the menu
+2. Toggle Kutuk **ON** in System Settings > Privacy & Security > Input Monitoring
+3. Click **Restart to Apply Permission** in the menu (macOS requires a restart for the permission to take effect)
+
+### Troubleshooting: Multiple Entries in Input Monitoring
+
+If you rebuild from source, macOS may create duplicate Kutuk entries in Input Monitoring. To clean up, open System Settings > Privacy & Security > Input Monitoring, select each old entry, click the **minus (−)** button to remove it, then re-add the current app.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[MIT](LICENSE)