Skip to content

kanata-integration.md

Latest commit

 

History

History
114 lines (86 loc) · 4.01 KB

kanata-integration.md

File metadata and controls

114 lines (86 loc) · 4.01 KB

Kanata Integration

OverKeys provides integration with Kanata, allowing you to visualize active keyboard layers when using Kanata's keyboard remapping functionality.

What is Kanata?

Kanata is a keyboard remapper that supports advanced features like layers, tap-hold, and leader keys. The integration between OverKeys and Kanata enables OverKeys to display the active layer from Kanata, making it easier to visualize which keys are available in your current layer.

OverKeys with Kanata Integration Demos

OverKeys_Kanata_Debug.mp4
OverKeysDemoLayers.mp4

Setup Instructions

Configuring OverKeys

  1. Right-click the OverKeys icon in the system tray

  2. Select Preferences

  3. Go to the General tab

  4. Click Open Config to edit the configuration file

  5. Modify the overkeys_config.json file:

    {
    "kanataHost": "127.0.0.1",
    "kanataPort": 4039,
    "userLayouts": [...],
    "defaultUserLayout": "Colemak"
}

  6. Save the file

  7. Toggle the Connect to Kanata option off then on again to apply changes

Configuring Kanata

When running Kanata, use the -p flag to enable TCP communication:

kanata.exe -p 127.0.0.1:4039

For convenience, create a shortcut for kanata_gui.exe:

  1. Right-click > Create Shortcut
  2. Edit the shortcut properties
  3. Add -p 127.0.0.1:4039 to the target field
  4. Place the shortcut in your Windows Startup folder

Note: This feature is only guaranteed to work with Kanata implementations that use Windows LLHOOK (like kanata_gui.exe).

Adding Kanata Layers

To display your Kanata layers in OverKeys, you need to configure them in the userLayouts section of your configuration file:

"userLayouts": [
   {
      "name": "Colemak",
      "keys": [
      ["`", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "-", "=", "BSPC"],
      ["Q", "W", "F", "P", "G", "J", "L", "U", "Y", ";", "[", "]"],
      ["A", "R", "S", "T", "D", "H", "N", "E", "I", "O", "'"],
      ["Z", "X", "C", "V", "B", "K", "M", ",", ".", "/"],
      [" "]
      ]
   },
   {
      "name": "Symbol",
      "keys": [
         ["`", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "-", "=", "BSPC"],
         ["'", "<", ">", ":", "@", "~", "\"", "{", "}", "%", "[", "]"],
         ["!", "-", "+", "=", "`", "|", ".", "(", ")", "?", "'"],
         ["^", "/", "*", "_", "\\", "&", "$", "[", "]", "#"],
         [" "]
      ]
   },
   {
      "name": "Extend",
      "keys": [
         ["`", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", "-", "=", "BSPC"],
         ["UNDO", "CUT", "COPY", "PASTE", "FIND", "DEV", "⇤", "↑", "⇥", "", "", ""],
         ["1", "2", "3", "4", "5", "⤒", "←", "↓", "→", "⤓", ""],
         ["6", "7", "8", "9", "0", "", "", "", "", ""],
         [" "]
      ]
   }
]

How It Works

When configured properly:

  1. Start both OverKeys and Kanata (recommended to start OverKeys first)
  2. OverKeys will automatically detect layer changes in Kanata
  3. When you switch layers in Kanata, OverKeys will update to show the active layer
OverKeys_Kanata_Shortcut.mp4

Implementation Notes

  • The Kanata integration works across all configured layers
  • Layer visualization is immediate when switching with Kanata shortcuts
  • When you switch to a layer other than your default/base layer (defined by defaultUserLayout), OverKeys will temporarily suspend its auto-hide feature, keeping the non-default layer visible for easier reference

Troubleshooting

  • If layer switching doesn't work, ensure both applications are running
  • Check that they're using the same host and port
  • Verify your layer configurations in overkeys_config.json have no errors
  • Try disabling and re-enabling the Kanata integration toggle in Preferences