Step1

Open Launchpad (or open " Applications" folder from Finder).

Then, click KeyRemap4MacBook.


Note If you're using KeyRemap4MacBook 7.8.0 or earlier, Preferences is in System Preferences.

Step2

Activate your favorite settings from prepared settings.

KeyRemap4MacBook provides very finely customization of key repeat rate.
You also can accelerate key repeat rate beyond the limits of OS X.

Open "Key Repeat" tab and change "Initial Wait" and "Wait".

Quit from menu bar.

quit

  1. Press the "launch uninstaller" button from "Misc & Uninstall" tab.
  2. Proceed uninstallation.
  3. Then restart OS X.

You can check for updates from "Misc & Uninstall" tab.

You can examine keyboard and mouse events by using EventViewer.
Launch EventViewer from a menu.

You can add your own settings by "private.xml".

  1. Click "Open private.xml" button on "Misc & Uninstall" tab.
  2. Then, Finder is opened.
  3. Open private.xml with your preferred text editor.
  4. Update the contents of private.xml to private.xml.
  5. Press "ReloadXML" button on "Change Key" tab.
  6. New settings have been added.
  7. Edit private.xml as you like, and press ReloadXML button.
    Then, activate added settings.
  8. Completed!
    Please send your new settings to me. I'll merge them into prepared settings.
    You can send it by either following ways.

KeyRemap4MacBook modifies following behavior of keyboard automatically without any configurations:

Overwrite keyboard repeat rate:

KeyRemap4MacBook overwrites keyboard repeat rate.
Please adjust from Preferences.

Share state of modifier keys with all connected keyboards:

When you are using multiple keyboards, modifier keys are shared with all keyboards.
For example, pressing "shift key on keyboard1" and "space key on keyboard2" sends shift-space.

Add fn-key combinations:

KeyRemap4MacBook adds fn-key combinations:

Fn-Arrow keys:

Key combinationResult
Fn-Up ArrowPageUp
Fn-Down ArrowPageDown
Fn-Left ArrowHome
Fn-Right ArrowEnd

Fn-Return, Fn-Delete:

Key combinationResult
Fn-ReturnEnter
Fn-DeleteForward Delete

Keypad numbers:

Key combinationResult
Fn-MKeypad 0
Fn-JKeypad 1
Fn-KKeypad 2
Fn-LKeypad 3
Fn-UKeypad 4
Fn-IKeypad 5
Fn-OKeypad 6
Fn-7Keypad 7
Fn-8Keypad 8
Fn-9Keypad 9

Keypad symbols:

Key combinationResult
Fn-6Keypad Clear
Fn-/Keypad +
Fn-;Keypad -
Fn-PKeypad *
Fn-0Keypad /
Fn-MinusKeypad =
Fn-.Keypad .

An application named "multi-touch extension" is attached.
You can use this application with multi-touch devices such as MacBook, Magic Mouse and Magic Trackpad.

This application activates specific setting while fingers touch the multi-touch device.
For example, you can activate Complete Vi Mode while two fingers touch the device.

ThumbSense is one of the function which multi-touch extension supplies.

How to use multi-touch extension

  1. Click "Launch multi-touch extension" button in "KeyRemap4MacBook Preference > Misc & Uninstall".
  2. Then application is launched. Click the icon in Dock.
  3. Then the preference window is opened. Change checkboxes and text if needed.
    The value of "Target setting" such as notsave.thumbsense is <identifier> in XML

You can switch activated settings from menu bar.

How to use multiple profiles

  1. Add new configuration from "MenuBar" tab.
  2. Choose the configuration from menu bar.
  3. Set up remapping for the selected configuration.

Switch profile by shortcut.

You can find a setting which switches profile by fn+1,fn+2,fn+3, and fn+4 by searching "switch profile" on Preference.


If you want to assign your own shortcut, this is an example of private.xml.

<?xml version="1.0"?>
<root>
  <item>
    <name>Switch Profile</name>
    <identifier>private.switch_profile</identifier>
    <autogen>__KeyToKey__ KeyCode::KEY_1, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_KeyRemap4MacBook_Profile0</autogen>
    <autogen>__KeyToKey__ KeyCode::KEY_2, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_KeyRemap4MacBook_Profile1</autogen>
    <autogen>__KeyToKey__ KeyCode::KEY_3, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_KeyRemap4MacBook_Profile2</autogen>
    <autogen>__KeyToKey__ KeyCode::KEY_4, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_KeyRemap4MacBook_Profile3</autogen>
  </item>
</root>

KeyRemap4MacBook provides a command line interface. (KeyRemap4MacBook_cli command)

  • You can get a list of changed setting.
  • You can activate/deactivate setting.
  • You can choose a profile from multiple profiles.
  • You can export configuration.

How to show help

Execute KeyRemap4MacBook_cli with no argument.

$ /Applications/KeyRemap4MacBook.app/Contents/Applications/KeyRemap4MacBook_cli.app/Contents/MacOS/KeyRemap4MacBook_cli
Usage:
  KeyRemap4MacBook_cli list
  KeyRemap4MacBook_cli selected
  KeyRemap4MacBook_cli changed
  KeyRemap4MacBook_cli reloadxml
  KeyRemap4MacBook_cli export
  KeyRemap4MacBook_cli select INDEX
  KeyRemap4MacBook_cli set IDENTIFIER VALUE
  KeyRemap4MacBook_cli enable IDENTIFIER (alias of set IDENTIFIER 1)
  KeyRemap4MacBook_cli disable IDENTIFIER (alias of set IDENTIFIER 0)

Example:
  KeyRemap4MacBook_cli list
  KeyRemap4MacBook_cli selected
  KeyRemap4MacBook_cli changed
  KeyRemap4MacBook_cli reloadxml
  KeyRemap4MacBook_cli export
  KeyRemap4MacBook_cli select 1
  KeyRemap4MacBook_cli set repeat.wait 30
  KeyRemap4MacBook_cli enable remap.shiftL2commandL
  KeyRemap4MacBook_cli disable remap.shiftL2commandL

About "list" and "select" option

You can choose a profile from multiple profiles.

  1. Get a list of profiles by "list" option.
    $ /Applications/KeyRemap4MacBook.app/Contents/Applications/KeyRemap4MacBook_cli.app/Contents/MacOS/KeyRemap4MacBook_cli list
    Default
    Don't Remap
    Empty
    Test
    
  2. Choose a profile by "select" option.
    The numeral argument is a profile index. It starts from 0.
    $ /Applications/KeyRemap4MacBook.app/Contents/Applications/KeyRemap4MacBook_cli.app/Contents/MacOS/KeyRemap4MacBook_cli select 1
    

About "export" option

  1. Export configuration by "export" option.
    The output is a shell script.
    $ /Applications/KeyRemap4MacBook.app/Contents/Applications/KeyRemap4MacBook_cli.app/Contents/MacOS/KeyRemap4MacBook_cli export > ~/Desktop/kr4mb-import.sh
    
  2. You can import it from Terminal.
    $ sh ~/Desktop/kr4mb-import.sh
    ...........................................
    

KeyRemap4MacBook settings are stored in the following location.

Home > Library > Preferences > org.pqrs.KeyRemap4MacBook.plist

You can investigate a normal key code by EventViewer.
However, you cannot investigate key events which will be processed on the system side, such as Command + Tab, brightness controls and volume controls.

You have to enable debug mode in order to show these system key events.

  1. Run the following command in Terminal.app.
    $ sudo sysctl -w keyremap4macbook.debug=1
    Password: <enter your password>
    
  2. Then, key events are output to log.
    You can show log by running this command in Terminal.app.
    OS X 10.8+
    $ sudo tail -f /var/log/system.log
    Password: <enter your password>
    
    OS X 10.7
    $ sudo tail -f /var/log/kernel.log
    Password: <enter your password>
    
  3. The following messages are shown when you press keys.
    Mar 21 22:19:52 rapeseed kernel[0]: KeyRemap4MacBook --Debug-- KeyboardEventCallback [ caught]: eventType 12, flags 0x80100008, key 0x0037, kbdType  43, repeat = 0
    Mar 21 22:19:52 rapeseed kernel[0]: KeyRemap4MacBook --Debug-- KeyboardEventCallback [sending]: eventType 12, flags 0x00040001, key 0x003b, kbdType  43, repeat = 0
    
  4. Press the C key while holding down the Control key to stop the message.
  5. Disable debug mode by running this command in Terminal.app.
    $ sudo sysctl -w keyremap4macbook.debug=0
    Password: <enter your password>
    

Usage of the debug mode results

You can convert a raw key code (for example, "key 0x0037") to "KeyCode::COMMAND_L" by using KeyCode.data.

Or use KeyCode::RawValue::0x0037 in private.xml.