Configuration Guide

Cursor Crane uses configuration files to manage settings. Most options can be changed directly in the app Settings UI, while TOML files remain useful for manual edits and advanced customization.

Once the app is launched, it will automatically create configuration files at:

• Directory~ Home

  • DirectoryLibrary

    • DirectoryApplication Support

      • Directorycom.expressionloss.CursorClaw automatically created

        • Directoryconf

          • conf.toml
          • commandSequences.toml
          • mouseControlKeyLayout.toml
          • shortcuts.toml
          • inputModeNanoFlavorShortcuts.toml

Change conf folder location in app

You can change the configuration directory directly in the app:

1. Open Settings > General.
2. Find the configuration location section.
3. Click Select Config Directory.
4. Choose a new folder (for example, a folder inside iCloud Drive).

If you move the folder to iCloud Drive, your configuration files can be synced across devices that use the same Apple ID.

Once you make changes, you can reload configurations from app settings or restart the app.

Which file controls what?

File	What it stores
conf.toml	General behavior and mode preferences (layout, gesture, mouse/grid/input behavior, etc.)
commandSequences.toml	Command sequences for commands and trigger keys
shortcuts.toml	Keyboard shortcuts for app activation, command shortcuts, and trigger shortcuts
inputModeNanoFlavorShortcuts.toml	Keyboard shortcuts for Input Mode Nano actions
mouseControlKeyLayout.toml	Adjust Mouse Control key bindings.

If a setting exists in the app UI, prefer editing it there first.

conf.toml

conf.toml controls app behavior preferences.

Full Example

version = 1

[general]
keyboardLayout = "usQWERTY"

[hintGenerator]
generatorType = "fingerFriendly"
minimumHintLength = 2
maximumHintLength = 4
predictionLength = 1
startByLeft = true

[gesture]
naturalPanDirection = false
treatRotateAsMouseButtonWhenNotHoldingFingers = false
treatPinchAsMouseButtonWhenNotHoldingFingers = false

[regularMode]
accurateMovementMode = "bisectionGrid"
defaultDistanceX = 200
defaultDistanceY = 200
autoSwitchToTextModeOnTextFieldFocus = false

[gridMode]
gridType = "proportional"
nineSquareGridKeySide = "left"

[scrollMode]
useDirectionKeysForScroll = true

[scrollMode.supplementaryWindows]
previousWindowLimit = 1
favoriteWindowLimit = 1
windowLimit = 1
priority = ["favoriteWindows", "previousWindows"]

[elementMode.supplementaryWindows]
previousWindowLimit = 1
favoriteWindowLimit = 1
windowLimit = 1
priority = ["favoriteWindows", "previousWindows"]

[textMode]
shortcutStyle = "nano"
autoExitWhenTextFieldLosesFocus = false
allowFindNextPreviousWithoutActiveQuery = true

[findMode]
recognitionSpeed = "accurate"
screenshotScale = "x2"

Fields

Field	Description	Default	Options
version	Config schema version.	1	1
general.keyboardLayout	Physical keyboard layout used to resolve readable key values.	usQWERTY	usQWERTY, colemak, colemakDH, dvorak, workman
hintGenerator.generatorType	Hint generation algorithm.	fingerFriendly	fingerFriendly
hintGenerator.minimumHintLength	Minimum hint length.	2	Integer >= 1
hintGenerator.maximumHintLength	Maximum hint length.	4	Integer >= minimumHintLength
hintGenerator.predictionLength	Extra predicted characters for hints.	1	Integer (0...5 in app UI)
hintGenerator.startByLeft	Prefer left-hand starting keys.	true	true, false
gesture.naturalPanDirection	Use natural direction for pan/scroll behavior.	false	true, false
gesture.treatRotateAsMouseButtonWhenNotHoldingFingers	Rotate gesture behaves like mouse button when not in gesture-hold state.	false	true, false
gesture.treatPinchAsMouseButtonWhenNotHoldingFingers	Pinch gesture behaves like mouse button when not in gesture-hold state.	false	true, false
regularMode.accurateMovementMode	Accurate movement strategy in Mouse Control mode.	bisectionGrid	bisectionGrid, nineSquareGrid
regularMode.defaultDistanceX	Default horizontal movement distance.	200	Positive integer
regularMode.defaultDistanceY	Default vertical movement distance.	200	Positive integer
regularMode.holdSpaceToEnterMoveStage	Hold Space in Command Mode to enter Mouse Control Mode.	true	true, false
regularMode.autoSwitchToTextModeOnTextFieldFocus	Auto-enter Text mode when text field is focused.	false	true, false
gridMode.gridType	Grid movement style.	proportional	bisection, nineSquare, proportional
gridMode.hintStyle	Grid Mode hint style.	default	default, largeText
gridMode.nineSquareGridKeySide	Which side of the keyboard is used for the built-in nine-square bindings shared by Grid Mode and Mouse Control Mode.	left	left, right
scrollMode.useDirectionKeysForScroll	Movement keys drive scrolling in Scroll mode.	true	true, false
scrollMode.supplementaryWindows.previousWindowLimit	Maximum previous windows Scroll Mode can include. Set to 0 to exclude previous windows.	1	Integer >= 0
scrollMode.supplementaryWindows.favoriteWindowLimit	Maximum favorite windows Scroll Mode can include. Set to 0 to exclude favorite windows.	1	Integer >= 0
scrollMode.supplementaryWindows.windowLimit	Total maximum supplementary windows considered by Scroll Mode after per-source limits and deduplication.	1	Integer >= 0
scrollMode.supplementaryWindows.priority	Priority order for supplementary window sources.	["favoriteWindows", "previousWindows"]	Array containing favoriteWindows and previousWindows
elementMode.supplementaryWindows.previousWindowLimit	Maximum previous windows Element Mode can include. Set to 0 to exclude previous windows.	1	Integer >= 0
elementMode.supplementaryWindows.favoriteWindowLimit	Maximum favorite windows Element Mode can include. Set to 0 to exclude favorite windows.	1	Integer >= 0
elementMode.supplementaryWindows.windowLimit	Total maximum supplementary windows considered by Element Mode after per-source limits and deduplication.	1	Integer >= 0
elementMode.supplementaryWindows.priority	Priority order for supplementary window sources.	["favoriteWindows", "previousWindows"]	Array containing favoriteWindows and previousWindows
textMode.shortcutStyle	Input Mode shortcut profile.	nano	nano
textMode.autoExitWhenTextFieldLosesFocus	Auto-exit Input Mode after focus leaves text field.	false	true, false
textMode.allowFindNextPreviousWithoutActiveQuery	Allow find-next and find-previous to reuse the selected text or token under the cursor when no active query exists.	true	true, false
findMode.recognitionSpeed	OCR speed and accuracy tradeoff for Find Mode.	accurate	accurate, fast
findMode.screenshotScale	Screenshot scale used before OCR in Find Mode.	x2	x1, x2

commandSequences.toml

commandSequences.toml defines typed key sequences for command execution.

Format

[commandSequences]
'command.moveCursorToElement' = 'f'
'command.moveCursorToElementAndLeftClick' = 'c'
'command.moveCursorToText' = 'sm'
'command.moveCursorToTextAndLeftClick' = 'sc'
'command.moveCursorToTextAndRightClick' = 'SC'
'command.enterTextMode' = 'i'
'command.enterRawInputMode' = 'I'
'command.createTextAreaPortal' = 'O'
'command.enterElementMenuModeForFocusedWindow' = 'XW'
'command.enterElementMenuModeForElementBelowCursor' = 'XE'
'trigger.scrollUp' = 'j'
'trigger.scrollDown' = 'k'
'trigger.scrollLeft' = 'h'
'trigger.scrollRight' = 'l'

Use empty string ('') to disable one sequence.

Available Keys

command.*: revertCursorLocation, enterMoveStage, moveCursorToElement, moveCursorToElementAndLeftClick, moveCursorToElementAndDoubleLeftClick, moveCursorToElementAndMiddleClick, moveCursorToElementAndRightClick, dragCursorToElement, moveCursorToText, moveCursorToTextAndLeftClick, moveCursorToTextAndRightClick, dragCursorToText, toggleDrag, enterGridModeAndLeftClick, enterGridModeAndDoubleLeftClick, enterGridModeAndMiddleClick, enterGridModeAndRightClick, enterGridModeAndMoveCursor, enterGridModeAndDragCursor, moveAndFocusToWindow, moveAndFocusToPreviousWindow, enterTextMode, enterRawInputMode, enterScrollMode, enterElementMenuModeForFocusedWindow, enterElementMenuModeForElementBelowCursor, createTextAreaPortal

trigger.*: up, down, left, right, leftClick, rightClick, middleClick, scrollDown, scrollUp, scrollLeft, scrollRight, scrollTop, scrollBottom, zoomIn, zoomOut, rotateClockwise, rotateCounterClockwise, smartZoom, forceClick

shortcuts.toml

shortcuts.toml stores keyboard shortcuts.

Format

[activate]
key = "m"
modifiers = ["command", "option", "shift"]

[enterRegularModeMouseStage]
key = "f8"
modifiers = []

['commandIdentifier.command.moveCursorToElement']
key = "f"
modifiers = ["control", "option"]

Each shortcut is a TOML table with:

• key: key identifier such as "a", "m", "return", "space", "escape", "left", "f8"
• modifiers: array of modifier names. Supported values include "command", "control", "option", "shift"

To remove a stored binding, delete that TOML record entirely.

Legacy carbonKeyCode / carbonModifiers values are still accepted for compatibility, but new manual edits should prefer key + modifiers.

inputModeNanoFlavorShortcuts.toml

inputModeNanoFlavorShortcuts.toml stores shortcuts for Input Mode Nano actions separately from the main shortcut file.

Format

['exit']
key = "x"
modifiers = ["control"]

['moveLeft']
key = "b"
modifiers = ["control"]

['scrollCursorToVisibleCenter']
key = "g"
modifiers = ["control"]

This file uses the same shortcut value format as shortcuts.toml.

mouseControlKeyLayout.toml

mouseControlKeyLayout.toml overrides Mouse Control key bindings. Values are resolved using general.keyboardLayout, so the same readable character can map to the correct physical key for QWERTY, Colemak, Dvorak, Workman, and other supported layouts.

The built-in nine-square positions are no longer configured in this file. They are generated automatically from gridMode.nineSquareGridKeySide, which is shared by Grid Mode and Mouse Control Mode.

You can create this file from a preset in Settings > General, then edit the generated TOML file for finer adjustments.

Format

[primary]
"direction.up" = "i"
"direction.left" = "j"
"mouse.left" = "return"

The file has 1 override group:

• primary: main actions (direction, gesture, mouse, scroll, function)

Supported primary action keys: direction.up, direction.left, direction.down, direction.right, gesture.rotateCounterClockwise, gesture.rotateClockwise, gesture.pinchOut, gesture.pinchIn, function.hold, function.undo, mouse.left, mouse.middle, mouse.right, mouse.fourth, mouse.fifth, scroll.up, scroll.down

Notes:

• Values use the same readable key value style as shortcuts.toml, such as "a", "i", "return", "tab", "[", or ";".
• This is an advanced file; prefer changing layout in app settings first.