Cursor Crane
Overview

Using Scripts

  • Move the pointer to the center of the active window or to a specific element.
  • Find a button, list item, or text field in an app, then click it or trigger one of its actions.
  • Simulate a sequence of key presses or clicks, reducing a repeated task to one trigger.
  • Build a small temporary panel where you enter conditions, choose a target, and inspect results.

Two bundled examples show both directions: one performs a single action, the other opens an interactive query panel. Run them as they are, or duplicate one as a starting point.

Anatomy of a script#

A script is a .js file providing a name, the permissions it needs, and a run(ctx) function. Use async and await whenever it waits on an operation.

/// <reference path="./.cursorcrane/cursorcrane.d.ts" />
 
/** @type {CursorCrane.Meta} */
const meta = {
  type: "action",
  name: "Say Hello",
  permissions: [],
};
 
/** @param {CursorCrane.Context} ctx */
function run(ctx) {
  ctx.toast("Hello from Cursor Crane.");
}

Field meanings and the full list of permissions are in the Script API.

Add a script#

Open Settings → Scripts. The page shows the current script folder, the scripts Cursor Crane found, and the command sequence and shortcut for each.

On first use of the default folder, Cursor Crane prepares:

  • Two examples you can run and modify.
  • Type declarations for editor autocomplete.
  • An AGENTS.md file describing the script structure and API conventions for AI coding assistants.

You can choose another folder, reveal it in Finder, or refresh the list after adding or editing a script. Put script files directly in the selected folder.

Editor autocomplete#

Add this line at the top of a script:

/// <reference path="./.cursorcrane/cursorcrane.d.ts" />

Your editor then suggests methods and arguments as you type ctx., ctx.mouse., or element.. The default script folder is prepared automatically; for a custom folder, choose Install Type Declarations in Settings → Scripts.

Make a script a command#

Every valid script appears in Settings → Scripts, where you record a command sequence or assign a global shortcut just as for a built-in command.

  • Command sequences use English letters only.
  • The settings screen tells you when a sequence or shortcut conflicts with an existing command or script.
  • If a script file is temporarily removed, its command stops running. Put the file back to restore it.

Sequence rules, including the prefix constraint, are covered in Command Mode.

Next#

Updated

Powered by Docsbook