Files

loveuer 1e8b79585f Initial commit: uskey - macOS keyboard remapper

Features:
- Menu bar GUI with enable/disable toggle
- JSON-based configuration system
- File-based logging with debug support
- CGEventTap-based key remapping
- Custom app icon support
- DMG installer packaging

Core Components:
- AppDelegate: Application lifecycle and initialization
- EventTapManager: Event tap creation and management with proper pointer lifetime
- KeyMapper: Key mapping logic and configuration loading
- StatusBarController: Menu bar UI and user interactions
- Logger: File and console logging with configurable levels
- Config: JSON configuration parser with default creation

Build System:
- build-app.sh: Creates macOS .app bundle with icon
- build-dmg.sh: Generates distributable DMG installer
- create-icon.sh: Converts PNG to .icns format

Documentation:
- README.md: User guide and troubleshooting
- BUILD.md: Build instructions and packaging
- DEBUG.md: Debugging guide with log access

🤖 Generated with [Qoder](https://qoder.com)

2025-12-02 17:51:56 +08:00

2.3 KiB

Raw Blame History

Debugging Guide

Log Files

uskey writes detailed logs to help diagnose issues.

Log Location

Directory: ~/.config/uskey/logs/
Current log: uskey-YYYY-MM-DD.log (one file per day)

Accessing Logs

Via Menu Bar:

Click the uskey keyboard icon in the menu bar
Select "Open Logs Folder" (⌘L) - Opens Finder at log location
Select "View Current Log" - Opens today's log in default text editor

Via Terminal:

# View today's log
cat ~/.config/uskey/logs/uskey-$(date +%Y-%m-%d).log

# Follow log in real-time
tail -f ~/.config/uskey/logs/uskey-$(date +%Y-%m-%d).log

Log Levels

Edit ~/.config/uskey/config.json to change log level:

{
  "log": {
    "level": "debug"
  }
}

Available levels (least to most verbose):

error - Only errors
warning - Warnings and errors
info - General information (default)
debug - Detailed debugging info including every key remap

After changing the level, select "Reload Configuration" (⌘R) from the menu.

Common Debug Scenarios

Mapping Not Enabling

Set log level to debug
Reload configuration
Try to enable mapping

Check logs for:

[ERROR] Failed to create event tap
[DEBUG] AXIsProcessTrusted result: false

If you see these errors:

The app doesn't have accessibility permissions
Go to System Preferences > Privacy & Security > Accessibility
Add and enable uskey

Keys Not Remapping

Set log level to debug
Press keys that should be remapped
Look for debug messages like:
```
[DEBUG] Remapping: 42 -> 51
```

If you don't see these messages:

Mapping is disabled (enable it from menu)
Key code is not in your configuration
Event tap is not working

Configuration Issues