6285cabdd1
Features: - Add auto-enable on startup based on config - Add enabled state persistence in config.json - Add limitations notice in GUI menu - Simplify logging to single file (uskey.log) - Change "Open Logs Folder" to "Open Config Folder" Bug Fixes: - Fix GUI status display mismatch on startup - Fix first toggle click not working issue - Revert password field changes that caused key blocking UI Changes: - Add ⚠️ emoji to "About Limitations" menu item - Remove button action to fix menu refresh 🤖 Generated with [Qoder][https://qoder.com]
156 lines
3.4 KiB
Markdown
156 lines
3.4 KiB
Markdown
# uskey
|
|
|
|
A macOS utility for remapping keyboard keys.
|
|
|
|
## Features
|
|
|
|
- Remap any keyboard key to another key
|
|
- Lightweight and efficient
|
|
- Native macOS integration using CoreGraphics
|
|
- JSON-based configuration
|
|
- Configurable logging levels
|
|
|
|
## Requirements
|
|
|
|
- macOS 13.0+
|
|
- Swift 6.0+
|
|
|
|
## Installation
|
|
|
|
### Option 1: Download DMG (Recommended)
|
|
|
|
1. Download the latest `uskey-x.x.x.dmg` from releases
|
|
2. Open the DMG file
|
|
3. Drag `uskey.app` to the Applications folder
|
|
4. Launch from Applications or Spotlight
|
|
5. Grant Accessibility permissions when prompted
|
|
|
|
### Option 2: Build from Source
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd uskey
|
|
./build-app.sh && ./build-dmg.sh
|
|
```
|
|
|
|
The DMG will be created at `.build/release/uskey-1.0.0.dmg`
|
|
|
|
For detailed build instructions, see [BUILD.md](BUILD.md)
|
|
|
|
## Configuration
|
|
|
|
The configuration file is automatically created at `~/.config/uskey/config.json` on first run.
|
|
|
|
### Configuration Format
|
|
|
|
```json
|
|
{
|
|
"log": {
|
|
"level": "info"
|
|
},
|
|
"mapping": {
|
|
"backslash2backspace": {
|
|
"from": 42,
|
|
"to": 51
|
|
},
|
|
"backspace2backslash": {
|
|
"from": 51,
|
|
"to": 42
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Log Levels
|
|
|
|
- `debug` - Detailed debugging information including every key remap
|
|
- `info` - General information messages (default)
|
|
- `warning` - Warning messages
|
|
- `error` - Error messages only
|
|
|
|
### Key Codes
|
|
|
|
For a complete list of macOS key codes, see [KEY_MAPPING.md](KEY_MAPPING.md).
|
|
|
|
Common examples:
|
|
- Backspace: 51
|
|
- Backslash `\`: 42
|
|
- Enter: 36
|
|
- Tab: 48
|
|
- Space: 49
|
|
|
|
You can add custom mappings by editing the config file and restarting the application.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
uskey
|
|
```
|
|
|
|
**Important:** On first run, you'll be prompted to grant Accessibility permissions in System Preferences > Privacy & Security > Accessibility.
|
|
|
|
## Troubleshooting
|
|
|
|
### Enable Mapping Doesn't Work
|
|
|
|
If you can't enable mapping after installation:
|
|
|
|
1. **Check Accessibility Permissions**
|
|
- Open System Preferences > Privacy & Security > Accessibility
|
|
- Ensure `uskey` is in the list and checked
|
|
- If not, click the `+` button and add the app
|
|
- After granting permissions, restart the app
|
|
|
|
2. **Check Logs**
|
|
- Click the uskey menu bar icon
|
|
- Select "Open Logs Folder" (⌘L)
|
|
- Open the latest log file (e.g., `uskey-2025-12-02.log`)
|
|
- Look for ERROR messages
|
|
|
|
3. **Enable Debug Logging**
|
|
- Edit `~/.config/uskey/config.json`
|
|
- Change `"level": "info"` to `"level": "debug"`
|
|
- Click "Reload Configuration" (⌘R) in the menu
|
|
- Try enabling mapping again
|
|
- Check logs for detailed debug information
|
|
|
|
### Log Files Location
|
|
|
|
Logs are stored at: `~/.config/uskey/logs/uskey.log`
|
|
|
|
The log file is cleared on each application start.
|
|
|
|
You can view logs by:
|
|
- **Menu Bar**: Click uskey icon → "View Current Log"
|
|
- **Finder**: Click uskey icon → "Open Logs Folder" (⌘L)
|
|
- **Terminal**: `tail -f ~/.config/uskey/logs/uskey.log`
|
|
|
|
### Common Issues
|
|
|
|
**"Failed to create event tap"**
|
|
- Cause: Missing accessibility permissions
|
|
- Solution: Grant accessibility permissions and restart the app
|
|
|
|
**Configuration not found**
|
|
- Cause: Config file doesn't exist
|
|
- Solution: The app will auto-create it at `~/.config/uskey/config.json`
|
|
|
|
**Mapping not working**
|
|
- Cause: Event tap is not enabled
|
|
- Solution: Check logs and ensure accessibility permissions are granted
|
|
|
|
## Development
|
|
|
|
Build the project:
|
|
```bash
|
|
swift build
|
|
```
|
|
|
|
Run in debug mode:
|
|
```bash
|
|
swift run
|
|
```
|
|
|
|
## License
|
|
|
|
MIT |