Setting up Cursor Crane

When the app launches for the first time, it will guide you through the setup process to enable the necessary permissions and configure the app for your needs. You can also change these settings later in the app settings.

1. Enable Accessibility API Permission

   Cursor Crane requires Accessibility permissions to function properly. Please click “Grant Permissions” to open the Accessibility settings and enable the necessary permissions for Cursor Crane.

   You can also use the “Check Permissions” button in the app settings later to verify your current permission status and learn more about how Cursor Crane uses Accessibility features.

   Enabling Accessibility API Manually

   If you need to enable permissions manually:

   1. Open System Preferences (or System Settings on newer macOS versions)
   2. Navigate to Privacy & Security → Accessibility
   3. Locate Cursor Crane in the list of applications
   4. Toggle the checkbox next to Cursor Crane to grant it permission
   5. You may need to click the lock icon in the bottom-left corner and enter your password to make changes

2. Enable Screen Recording Permission for Find Mode

   If you plan to use Find Mode, Cursor Crane also needs Screen Recording permission so it can capture the current window and run OCR on visible text.

   This permission is not required for the rest of the app, but Find Mode will not work correctly without it.

   Enabling Screen Recording Manually

   If you need to enable it manually:

   1. Open System Preferences (or System Settings on newer macOS versions)
   2. Navigate to Privacy & Security → Screen & System Audio Recording
   3. Locate Cursor Crane in the list of applications
   4. Turn on permission for Cursor Crane
   5. Restart the app if macOS asks you to

3. Set Up a Keyboard Shortcut

   Configure a keyboard shortcut to activate the claw machine. You can also set up shortcuts for individual commands and modes later in Settings.

4. Choose Your Keyboard Layout

   Choose the physical keyboard layout you use, such as QWERTY, Colemak, Colemak-DH, Dvorak, or Workman. Cursor Crane uses this to resolve readable key values and create an initial Mouse Control key layout preset.

   You can still adjust the Mouse Control layout later in Settings or through mouseControlKeyLayout.toml.

5. Configure and Update Settings

   The app uses configuration files to manage its settings. Most settings can be changed in the app, while TOML files are available for advanced customization. Before using the app, you may want to review the generated Mouse Control layout and choose a usage style that suits your workflow.

   For detailed information about available configuration options, see the Configuration Guide.

6. Start the Claw Machine

   Once set up, you can start controling your mouse with keyboard. Simply press or hold your activation shortcut to activate the Claw Machine.

   Please choose a usage style that suits you to use Cursor Crane. You can learn about different usage styles in the Choosing Usage Style guide.

   After activating the claw machine, you will see a status indicator in the top left corner of your screen.

   

   The status indicator will cover the menu bar. But as a keyboard-enthusiast, you may prefer to use Command + Shift + / to search and trigger any menu item without hitting the menu bar.