# Karabiner Elements: Caps Lock as Hyper Key with iTerm2 Exception
## Summary
Configure Caps Lock to act as a Hyper Key (Cmd+Option+Ctrl+Shift) in all applications except iTerm2, where it functions as Control. This setup optimises keyboard efficiency for both general productivity shortcuts and terminal operations.
## Details
### Overview
Configure Caps Lock to act as:
- **Hyper Key** (Cmd+Option+Ctrl+Shift) in all applications
- **Control Key** specifically in iTerm2
### Configuration Steps
#### 1. Locate Karabiner Configuration File
The configuration file is located at:
```text
~/.config/karabiner/karabiner.json
```
#### 2. Add Custom Rule
Add the following rule to your profile's `complex_modifications` → `rules` array:
```json
{
"description": "Caps Lock to Hyper/Control",
"manipulators": [
{
"type": "basic",
"from": {
"key_code": "caps_lock",
"modifiers": {
"optional": ["any"]
}
},
"to": [
{
"key_code": "left_control"
}
],
"conditions": [
{
"type": "frontmost_application_if",
"bundle_identifiers": [
"^com\\.googlecode\\.iterm2
quot;
]
}
]
},
{
"type": "basic",
"from": {
"key_code": "caps_lock",
"modifiers": {
"optional": ["any"]
}
},
"to": [
{
"key_code": "left_shift",
"modifiers": ["left_command", "left_control", "left_option"]
}
],
"conditions": [
{
"type": "frontmost_application_unless",
"bundle_identifiers": [
"^com\\.googlecode\\.iterm2quot;
]
}
]
}
]
}
```
#### 3. Complete JSON Structure Example
Here's how it fits into the complete configuration file:
```json
{
"profiles": [
{
"name": "Default",
"complex_modifications": {
"rules": [
{
"description": "Caps Lock to Hyper/Control",
"manipulators": [
// ... rules from above ...
]
}
]
}
}
]
}
```
#### 4. System Preferences Setup
1. Open **System Preferences** → **Keyboard** → **Modifier Keys**
2. Set Caps Lock to **No Action**
3. This prevents macOS from interfering with Karabiner
### How It Works
#### Rule 1: iTerm2 Control Key
- **Trigger**: Caps Lock pressed
- **Condition**: iTerm2 is the frontmost application
- **Action**: Send Control key press
- **Bundle ID**: `com.googlecode.iterm2`
#### Rule 2: Hyper Key for Other Apps
- **Trigger**: Caps Lock pressed
- **Condition**: Any application except iTerm2
- **Action**: Send Shift+Cmd+Ctrl+Option (Hyper Key)
### Testing
#### In iTerm2
- `Caps Lock + C` = `Ctrl + C` (interrupt)
- `Caps Lock + A` = `Ctrl + A` (beginning of line)
#### In Other Applications
- `Caps Lock + Key` = `Cmd+Option+Ctrl+Shift + Key`
- Use with apps like Raycast, Alfred, or custom shortcuts
### Customisation Options
#### Add More Terminal Apps
To include other terminal applications, add their bundle identifiers:
```json
"bundle_identifiers": [
"^com\\.googlecode\\.iterm2quot;,
"^com\\.apple\\.Terminalquot;,
"^com\\.microsoft\\.VSCodequot;
]
```
#### Find Bundle Identifiers
Use this command to find an app's bundle identifier:
```bash
osascript -e 'id of app "AppName"'
```
### Troubleshooting
1. **Changes not taking effect**:
- Save the JSON file
- Karabiner should auto-reload
- If not, restart Karabiner Elements
2. **JSON validation errors**:
- Ensure proper comma placement
- Check bracket matching
- Use a JSON validator
3. **Caps Lock still functioning normally**:
- Verify System Preferences modifier key setting
- Check Karabiner Elements is running
- Ensure the profile is active
### Additional Resources
- [Karabiner Elements Documentation](https://karabiner-elements.pqrs.org/docs/)
- [Complex Modifications Examples](https://ke-complex-modifications.pqrs.org/)
- [Bundle Identifier Reference](https://karabiner-elements.pqrs.org/docs/json/complex-modifications-manipulator-definition/conditions/frontmost-application/)
## 🔗 Related Resources
- [[Keyboard Shortcuts]]
- [[macOS Productivity Setup]]
- [[Terminal Configuration]]