Using Scripts

Scripts let you turn workflows that Cursor Crane does not provide out of the box into your own commands and small tools. For example, you can:

Move the pointer to the center of the active window or to a specific interface 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 mouse clicks to reduce a repeated task to one trigger.
Build a small temporary panel where you enter conditions, choose a target, and inspect results.

The two bundled examples show these directions: one completes a single action, while the other provides an interactive query panel. You can run them as they are or duplicate one as a starting point.

A script is a .js file. It provides a name, the permissions it needs, and a run(ctx) function. Use async / await whenever the script needs to wait for 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.");
}

Add a Script

Open Settings > Scripts. This page shows the current script folder, the scripts Cursor Crane has found, and the command sequence and shortcut available for each script.

When you first use the default folder, Cursor Crane prepares:

Two examples that you can run and modify.
The type declarations used by VSCode autocomplete.

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.

Make Editing Easier with VSCode

Add this line at the top of a script:

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

VSCode can then suggest available methods and arguments as you type ctx., ctx.mouse., or element.. The default script folder is prepared automatically. For a custom script folder, choose Install Type Declarations in Settings > Scripts.

Make a Script a Command

Every valid script appears in Settings > Scripts. You can record a command sequence or assign a global shortcut just as you would 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 with the same name back to make it available again.

Script Types

Choose the experience with meta.type:

Type	Best for	What `run(ctx)` does
`action`	A task that completes in one go.	Performs the work.
`form`	A small tool that needs input, choices, or results.	Returns an array of form items.

Action Scripts

Action scripts are for flows that do not need extra input. They can read the current state, perform an operation, and use a toast to report the result. The bundled example.center-cursor-to-active-window.js is an action script: it finds the active window, moves the pointer, and shows window information.

Form Scripts

Form scripts bring related elements, options, and results from one or more windows together into a native interactive form. They let people enter conditions, choose targets, and continue inspecting or operating on the results in the same panel. run(ctx) returns a group of form items for Cursor Crane to render.

You can combine these form items:

label for instructions, status, or results.
numberInput and textInput for numbers and text.
select for a choice from a list.
checkbox and toggle for on/off options.
button for the next action.

In addition to the regular APIs, a form ctx provides three important capabilities:

Capability	How to use it
Read the current input	Read values from `ctx.formData` by form item `id`.
Respond to changes and events	Give inputs an `onChange` callback and buttons an `onClick` callback. Both receive the current form `ctx`.
Update the interface	Call `ctx.updateForm(...)` with a complete new set of form items, such as replacing a loading status with result buttons.
Close the panel	Call `ctx.closeForm()` when the task is finished, cancelled, or cannot continue.

onChange is useful for revealing or hiding more inputs after a choice. onClick is useful for queries, submission, and element actions. When you update a form, an item with the same id keeps the value the person already entered unless you provide a new value.

Forms use panel by default, which suits small tools that stay open for repeated work. Set presentation to transient for a shorter-lived input panel that closes when it loses focus.

Use Cases

Work with a Specific Element in the Active Window

You can write a script that finds and works with an element in the active window: for example, an available button, a text field with a specific title, or a row in a list. You can either walk through child elements yourself or use an element selector to describe the target directly. After finding it, you can click it, trigger one of its actions, or highlight it first so the person can confirm the target. This can turn a frequently used button in an app into a command, or let a form list several results for the person to choose from.

Activate an App Window

You can find an app by its bundle identifier, choose one of its windows, and activate it. This is useful for workflows that move between a chat window, a notes window, and a particular development tool window.

Give Immediate Feedback with Toasts

You can use ctx.toast(...) after an action to show a short confirmation, an error, or information about the target. It can also explain what to do next when a form cannot continue.

You can use ctx.toast.highlight(...) to highlight an element’s area on screen and show a short hint below it. This is useful when people need to confirm which target a script found or changed.

Permissions

Only declare the permissions a script actually needs:

Permission	Use it for
`accessibilityAPI`	Finding apps, windows, and interface elements, or operating on elements.
`keyboard`	Simulating key presses.
`mouse`	Moving and clicking the pointer.

For example, a script that only shows a toast can use permissions: []; a script that queries elements needs accessibilityAPI. Only run scripts from sources you trust and understand.

For the full API reference, see Script API.