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
          • keyLayout.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
keyLayout.toml	Adjust key binding. Not ready yet.

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]
layout = "ijkl"

[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"

[scrollMode]
useDirectionKeysForScroll = true
useRotateKeyForElementSwitching = true

[textMode]
shortcutStyle = "nano"
autoExitWhenTextFieldLosesFocus = false

[searchMode]
recognitionLanguages = ["en-US"]
recognitionSpeed = "accurate"
screenshotScale = "x2"

Fields

Field	Description	Default	Options
version	Config schema version.	1	1
general.layout	Direction key layout.	ijkl	wasd, hjkl, ijkl
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
scrollMode.useDirectionKeysForScroll	Direction keys drive scrolling in Scroll mode.	true	true, false
scrollMode.useRotateKeyForElementSwitching	Rotate key switches element while scrolling.	true	true, false
textMode.shortcutStyle	Input Mode shortcut profile.	nano	nano
textMode.autoExitWhenTextFieldLosesFocus	Auto-exit Input Mode after focus leaves text field.	false	true, false
searchMode.recognitionLanguages	OCR languages used by Search Mode.	["en-US"]	Array of language identifiers such as en-US, zh-Hans, ja-JP
searchMode.recognitionSpeed	OCR speed and accuracy tradeoff for Search Mode.	accurate	accurate, fast
searchMode.screenshotScale	Screenshot scale used before OCR in Search 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'
'trigger.scrollUp' = 'j'
'trigger.scrollDown' = 'k'

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

Available Keys

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

trigger.*: up, down, left, right, leftClick, rightClick, middleClick, scrollDown, scrollUp, 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.

keyLayout.toml

keyLayout.toml overrides physical key bindings on top of the selected layout (wasd/hjkl/ijkl).

Format

primary = []
additionalDirection = []

The file has 2 override groups:

• primary: main actions (direction, gesture, mouse, scroll, function)
• additionalDirection: 9-grid additional direction actions

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

Supported additionalDirection action keys: nineSquareGrid.topLeft, nineSquareGrid.topCenter, nineSquareGrid.topRight, nineSquareGrid.centerLeft, nineSquareGrid.center, nineSquareGrid.centerRight, nineSquareGrid.bottomLeft, nineSquareGrid.bottomCenter, nineSquareGrid.bottomRight

Notes:

• Values are macOS key codes (KeyboardCode raw integer values).
• This is an advanced file; prefer changing layout in app settings first.