BetterTouchTool configuration

[shanscendent]

I'm using the default mouseless cmd tap keybinding, and binding cmd + T as a trackpad action triggers mouseless, no matter what tap_threshold I set. After a few experiments, this set of actions seems to get around the issue, so I'm sharing it for anyone who's interested.

Could this be added somewhere in the documentation, @croian? I think it'd be helpful.

Remember to choose "Send key up only" for the 4th action.

BTT export

btt://jsonimport/WwogIHsKICAgICJCVFRBY3Rpb25DYXRlZ29yeSIgOiAwLAogICAgIkJUVExhc3RVcGRhdGVkQXQiIDogMTc0MjYzMDEwNS45ODc0MDgyLAogICAgIkJUVFRyaWdnZXJUeXBlIiA6IDEwMiwKICAgICJCVFRUcmlnZ2VyVHlwZURlc2NyaXB0aW9uUmVhZE9ubHkiIDogIjMgRmluZ2VyIFN3aXBlIFVwIiwKICAgICJCVFRUcmlnZ2VyQ2xhc3MiIDogIkJUVFRyaWdnZXJUeXBlVG91Y2hwYWRBbGwiLAogICAgIkJUVFVVSUQiIDogIkYwMjFBMEI5LTVDNjQtNERBRC1CNjhBLTVGMTQyQTIzRDI2NyIsCiAgICAiQlRUUHJlZGVmaW5lZEFjdGlvblR5cGUiIDogMTg2LAogICAgIkJUVFByZWRlZmluZWRBY3Rpb25OYW1lIiA6ICLijJggQ01EIEtleSBEb3duIiwKICAgICJCVFRHZW5lcmljQWN0aW9uQ29uZmlnMiIgOiAiMCIsCiAgICAiQlRUR2VuZXJpY0FjdGlvbkNvbmZpZyIgOiAiMTAwMCIsCiAgICAiQlRURW5hYmxlZCIgOiAxLAogICAgIkJUVEVuYWJsZWQyIiA6IDEsCiAgICAiQlRUT3JkZXIiIDogNiwKICAgICJCVFRBZGRpdGlvbmFsQWN0aW9ucyIgOiBbCiAgICAgIHsKICAgICAgICAiQlRUQWN0aW9uQ2F0ZWdvcnkiIDogMCwKICAgICAgICAiQlRUTGFzdFVwZGF0ZWRBdCIgOiAxNzQyNjMwMTU5LjY0MjMxMTEsCiAgICAgICAgIkJUVFRyaWdnZXJQYXJlbnRVVUlEIiA6ICJGMDIxQTBCOS01QzY0LTREQUQtQjY4QS01RjE0MkEyM0QyNjciLAogICAgICAgICJCVFRJc1B1cmVBY3Rpb24iIDogdHJ1ZSwKICAgICAgICAiQlRUVHJpZ2dlckNsYXNzIiA6ICJCVFRUcmlnZ2VyVHlwZVRvdWNocGFkQWxsIiwKICAgICAgICAiQlRUVVVJRCIgOiAiQ0NENTE4NzYtNjFGNi00QTZDLUE2ODktODE1MjI0RkU0RkMzIiwKICAgICAgICAiQlRUTGF5b3V0SW5kZXBlbmRlbnRBY3Rpb25DaGFyIiA6ICJ0IiwKICAgICAgICAiQlRUQWRkaXRpb25hbEFjdGlvbkRhdGEiIDogewogICAgICAgICAgInNlbmRDdXJyZW50TW9kaWZpZXJzIiA6IHRydWUKICAgICAgICB9LAogICAgICAgICJCVFRHZW5lcmljQWN0aW9uQ29uZmlnMiIgOiAib25seURvd24iLAogICAgICAgICJCVFRTaG9ydGN1dFRvU2VuZCIgOiAiMTciLAogICAgICAgICJCVFRTaG9ydGN1dFVwRG93biIgOiAib25seURvd24iLAogICAgICAgICJCVFRFbmFibGVkIiA6IDEsCiAgICAgICAgIkJUVEVuYWJsZWQyIiA6IDEsCiAgICAgICAgIkJUVE9yZGVyIiA6IDAKICAgICAgfSwKICAgICAgewogICAgICAgICJCVFRBY3Rpb25DYXRlZ29yeSIgOiAwLAogICAgICAgICJCVFRMYXN0VXBkYXRlZEF0IiA6IDE3NDI2MzAxMDUuOTg3NDg0LAogICAgICAgICJCVFRUcmlnZ2VyUGFyZW50VVVJRCIgOiAiRjAyMUEwQjktNUM2NC00REFELUI2OEEtNUYxNDJBMjNEMjY3IiwKICAgICAgICAiQlRUSXNQdXJlQWN0aW9uIiA6IHRydWUsCiAgICAgICAgIkJUVFRyaWdnZXJDbGFzcyIgOiAiQlRUVHJpZ2dlclR5cGVUb3VjaHBhZEFsbCIsCiAgICAgICAgIkJUVFVVSUQiIDogIkRFNDZCRjk0LTMwNzYtNEZDNy1CNzlBLTk4N0MwQkFDQkJGRSIsCiAgICAgICAgIkJUVFByZWRlZmluZWRBY3Rpb25UeXBlIiA6IDEyOSwKICAgICAgICAiQlRUUHJlZGVmaW5lZEFjdGlvbk5hbWUiIDogIlBhdXNlIEV4ZWN1dGlvbiAgb3IgIERlbGF5IE5leHQgQWN0aW9uIChibG9ja2luZykiLAogICAgICAgICJCVFREZWxheU5leHRBY3Rpb25CeSIgOiAiMC4zIiwKICAgICAgICAiQlRURW5hYmxlZCIgOiAxLAogICAgICAgICJCVFRFbmFibGVkMiIgOiAxLAogICAgICAgICJCVFRPcmRlciIgOiAxCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiQlRUQWN0aW9uQ2F0ZWdvcnkiIDogMCwKICAgICAgICAiQlRUTGFzdFVwZGF0ZWRBdCIgOiAxNzQyNjMwMTYzLjYxMTIyODksCiAgICAgICAgIkJUVFRyaWdnZXJQYXJlbnRVVUlEIiA6ICJGMDIxQTBCOS01QzY0LTREQUQtQjY4QS01RjE0MkEyM0QyNjciLAogICAgICAgICJCVFRJc1B1cmVBY3Rpb24iIDogdHJ1ZSwKICAgICAgICAiQlRUVHJpZ2dlckNsYXNzIiA6ICJCVFRUcmlnZ2VyVHlwZVRvdWNocGFkQWxsIiwKICAgICAgICAiQlRUVVVJRCIgOiAiOTczODNCNTYtMUVERC00M0E4LTg0RDMtRjMyOTlDQzQ4NjEyIiwKICAgICAgICAiQlRUTGF5b3V0SW5kZXBlbmRlbnRBY3Rpb25DaGFyIiA6ICJ0IiwKICAgICAgICAiQlRUQWRkaXRpb25hbEFjdGlvbkRhdGEiIDogewogICAgICAgICAgInNlbmRDdXJyZW50TW9kaWZpZXJzIiA6IHRydWUKICAgICAgICB9LAogICAgICAgICJCVFRHZW5lcmljQWN0aW9uQ29uZmlnMiIgOiAib25seVVwIiwKICAgICAgICAiQlRUU2hvcnRjdXRUb1NlbmQiIDogIjE3IiwKICAgICAgICAiQlRUU2hvcnRjdXRVcERvd24iIDogIm9ubHlVcCIsCiAgICAgICAgIkJUVEVuYWJsZWQiIDogMSwKICAgICAgICAiQlRURW5hYmxlZDIiIDogMSwKICAgICAgICAiQlRUT3JkZXIiIDogMgogICAgICB9LAogICAgICB7CiAgICAgICAgIkJUVEFjdGlvbkNhdGVnb3J5IiA6IDAsCiAgICAgICAgIkJUVExhc3RVcGRhdGVkQXQiIDogMTc0MjYzMDEwNS45ODczNzE5LAogICAgICAgICJCVFRUcmlnZ2VyUGFyZW50VVVJRCIgOiAiRjAyMUEwQjktNUM2NC00REFELUI2OEEtNUYxNDJBMjNEMjY3IiwKICAgICAgICAiQlRUSXNQdXJlQWN0aW9uIiA6IHRydWUsCiAgICAgICAgIkJUVFRyaWdnZXJDbGFzcyIgOiAiQlRUVHJpZ2dlclR5cGVUb3VjaHBhZEFsbCIsCiAgICAgICAgIkJUVFVVSUQiIDogIjYzMDlDMTFDLTAwNjMtNEU5Qi1BOTYyLTk3NjNGOUMyNjI0RiIsCiAgICAgICAgIkJUVFByZWRlZmluZWRBY3Rpb25UeXBlIiA6IDE4NywKICAgICAgICAiQlRUUHJlZGVmaW5lZEFjdGlvbk5hbWUiIDogIuKMmCBDTUQgS2V5IFVwIiwKICAgICAgICAiQlRURW5hYmxlZCIgOiAxLAogICAgICAgICJCVFRFbmFibGVkMiIgOiAxLAogICAgICAgICJCVFRPcmRlciIgOiAzCiAgICAgIH0KICAgIF0KICB9Cl0=

[cymian]

Awesome, thank you @shanscendent! I don't use BTT, but I'm sure others will find this very helpful. I'll add this to the troubleshooting section of the docs.

[cymian]

Actually, before I share this @shanscendent, can you help me understand what the import process looks like? Does it give you a preview of the config contents before fully importing? Is there a human-readable form you can provide (and is that practical)?

Without being a BTT user, I don't have a full grasp of the security implications of this, but a brief AI chat seems to indicate a BTT config can contain startup (or triggerable) Applescripts etc.

No offense intended of course! Just trying to cover all bases.

[shanscendent]

No offense taken, it's a good point! The config is actually just base64 encoded json, but I found out you can just copy paste a json string directly into the BTT settings page and it'll still work, which is more easily reviewable as well. Also, I've rewritten the whole recommendation so you can include it in the docs easier.

BetterTouchTool configuration

As mouseless is bound to cmd tap, some (not all, for some reason) cmd keyboard shortcut BTT actions will trigger mouseless no matter what tap_threshold you pick. Here's an example of how to work around this. This example maps 3 Finger Swipe Up to Cmd + T, which works exactly the same way but doesn't trigger mouseless.

Remember to include currently pressed modifier keys for both T actions, and Send Key Down only and Send Key Up only for the first and second T action respectively.

Here's a json string you can import as a starting point. Copy the json string, open the BTT settings page and navigate to the Trackpad triggers page, then paste it in, and it'll import this trigger.

BTT json

[
{
"BTTActionCategory" : 0,
"BTTLastUpdatedAt" : 1742697650.905817,
"BTTTriggerType" : 102,
"BTTTriggerTypeDescriptionReadOnly" : "3 Finger Swipe Up",
"BTTTriggerClass" : "BTTTriggerTypeTouchpadAll",
"BTTUUID" : "F021A0B9-5C64-4DAD-B68A-5F142A23D267",
"BTTPredefinedActionType" : 186,
"BTTPredefinedActionName" : "⌘ CMD Key Down",
"BTTGenericActionConfig2" : "0",
"BTTGenericActionConfig" : "1000",
"BTTEnabled" : 1,
"BTTEnabled2" : 1,
"BTTOrder" : 5,
"BTTAdditionalActions" : [
{
"BTTActionCategory" : 0,
"BTTLastUpdatedAt" : 1742630159.6423111,
"BTTTriggerParentUUID" : "F021A0B9-5C64-4DAD-B68A-5F142A23D267",
"BTTIsPureAction" : true,
"BTTTriggerClass" : "BTTTriggerTypeTouchpadAll",
"BTTUUID" : "CCD51876-61F6-4A6C-A689-815224FE4FC3",
"BTTLayoutIndependentActionChar" : "t",
"BTTAdditionalActionData" : {
"sendCurrentModifiers" : true
},
"BTTGenericActionConfig2" : "onlyDown",
"BTTShortcutToSend" : "17",
"BTTShortcutUpDown" : "onlyDown",
"BTTEnabled" : 1,
"BTTEnabled2" : 1,
"BTTOrder" : 0
},
{
"BTTActionCategory" : 0,
"BTTLastUpdatedAt" : 1742630105.987484,
"BTTTriggerParentUUID" : "F021A0B9-5C64-4DAD-B68A-5F142A23D267",
"BTTIsPureAction" : true,
"BTTTriggerClass" : "BTTTriggerTypeTouchpadAll",
"BTTUUID" : "DE46BF94-3076-4FC7-B79A-987C0BACBBFE",
"BTTPredefinedActionType" : 129,
"BTTPredefinedActionName" : "Pause Execution or Delay Next Action (blocking)",
"BTTDelayNextActionBy" : "0.3",
"BTTEnabled" : 1,
"BTTEnabled2" : 1,
"BTTOrder" : 1
},
{
"BTTActionCategory" : 0,
"BTTLastUpdatedAt" : 1742630163.6112289,
"BTTTriggerParentUUID" : "F021A0B9-5C64-4DAD-B68A-5F142A23D267",
"BTTIsPureAction" : true,
"BTTTriggerClass" : "BTTTriggerTypeTouchpadAll",
"BTTUUID" : "97383B56-1EDD-43A8-84D3-F3299CC48612",
"BTTLayoutIndependentActionChar" : "t",
"BTTAdditionalActionData" : {
"sendCurrentModifiers" : true
},
"BTTGenericActionConfig2" : "onlyUp",
"BTTShortcutToSend" : "17",
"BTTShortcutUpDown" : "onlyUp",
"BTTEnabled" : 1,
"BTTEnabled2" : 1,
"BTTOrder" : 2
},
{
"BTTActionCategory" : 0,
"BTTLastUpdatedAt" : 1742630105.9873719,
"BTTTriggerParentUUID" : "F021A0B9-5C64-4DAD-B68A-5F142A23D267",
"BTTIsPureAction" : true,
"BTTTriggerClass" : "BTTTriggerTypeTouchpadAll",
"BTTUUID" : "6309C11C-0063-4E9B-A962-9763F9C2624F",
"BTTPredefinedActionType" : 187,
"BTTPredefinedActionName" : "⌘ CMD Key Up",
"BTTEnabled" : 1,
"BTTEnabled2" : 1,
"BTTOrder" : 3
}
]
}
]

[rh10hd]

This configuration definitely did the trick!! Thank you so much. @shanscendent

[cymian]

Wonderful, thank you so much for this, @shanscendent. For now, I've linked to your comment from the docs.

I'm pretty sure others have raised this exact issue with BTT before, though I can't seem to find it with the issue search right now 🤔. I'm grateful, and I'm sure others will be too! 🙏

[cymian]

Found the issue: #106

Apparently Github issue search only matches on full words (better and even bettertouch won't cut it, yikes 😬)

[apurvarshukla]

Thank you for posting the solution to this. I had CMD W mapped to three finder swipe on my magic mouse which was triggering mouseless. It drove me crazy cos I couldn't figure out the reason. You post saved me!

[bakari45]

Thank you so much, @shanscendent for helping me understand how to configure bettertouchtool actions to avoid triggering mouseless. Without your help, I would have been stuck for days.

[acicovic]

An alternative not requiring BTT reconfiguration that worked for me was to map Mouseless invocation to CommandRight tap.