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

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 (global activation and command shortcuts)
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

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.autoSwitchToTextModeOnTextFieldFocus	Auto-enter Text mode when text field is focused.	false	true, false
gridMode.gridType	Grid movement style.	proportional	proportional, nineSquare
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	Text mode shortcut profile.	nano	nano
textMode.autoExitWhenTextFieldLosesFocus	Auto-exit Text mode after focus leaves text field.	false	true, false

You can edit these from:

• Settings > General
• Settings > Mouse Control
• Settings > Grid Movement
• Settings > Element Jump
• Settings > Input

commandSequences.toml

commandSequences.toml defines typed key sequences for command execution.

Format

[commandSequences]
'command.moveCursorToElement' = 'f'
'command.moveCursorToElementAndLeftClick' = 'c'
'command.enterTextMode' = 'i'
'trigger.scrollUp' = 'j'
'trigger.scrollDown' = 'k'

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

Available Keys

command.*: revertCursorLocation, moveCursorToElement, moveCursorToElementAndLeftClick, moveCursorToElementAndDoubleLeftClick, moveCursorToElementAndMiddleClick, moveCursorToElementAndRightClick, dragToElement, enterGridModeAndLeftClick, enterGridModeAndDoubleLeftClick, enterGridModeAndMiddleClick, enterGridModeAndRightClick, moveAndFocusToWindow, moveAndFocusToPreviousWindow, enterTextMode, enterScrollMode

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

In-app entry: Settings > Command.

shortcuts.toml

shortcuts.toml stores keyboard shortcuts.

Format

[activate]
carbonKeyCode = 46
carbonModifiers = 6400

[enterRegularModeMouseStage]
carbonKeyCode = 119
carbonModifiers = 256

['commandIdentifier.command.moveCursorToElement']
carbonKeyCode = 3
carbonModifiers = 4352

Each shortcut is a TOML table with:

• carbonKeyCode: macOS Carbon key code (integer)
• carbonModifiers: Carbon modifier bitmask (integer)

Common top-level shortcut names:

• activate
• enterRegularModeMouseStage
• toggleCheatsheets
• commandIdentifier.command.*
• commandIdentifier.trigger.*

In-app entry: Settings > Keyboard Shortcuts.

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.