Agent cursor tools
Show, animate and style the agent cursor.
Show, animate and style the agent cursor.
| Tool | Description | Platforms |
|---|---|---|
set_agent_cursor_enabled | Show or hide the agent cursor owned by a session. | macOS, Linux, Windows |
set_agent_cursor_motion | Configure the movement style, timing, effects and visibility timing for a session cursor. | macOS, Linux, Windows |
set_agent_cursor_theme | Select an already-installed cursor theme for a session. | macOS, Linux, Windows |
get_agent_cursor_state | Return the session cursor's theme, semantic playback, position, visibility, and motion. | macOS, Linux, Windows |
Served by cua-driver mcp; see MCP tools for every tool.
set_agent_cursor_enabled#Show or hide the agent cursor owned by a session.
Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | boolean | required | true shows the session's agent cursor overlay; false hides it. |
session | string | required | Public label of the session that owns the cursor. |
Example arguments
{"session":"<session>","enabled":false}set_agent_cursor_motion#Configure the movement style, timing, effects and visibility timing for a session cursor.
Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
arc_flow | number | Added to the arc asymmetry of signature_arc, spring_settle and comet_swoop: positive moves the apex toward the destination. Clamped to -1..1 (default 0). | |
arc_size | number | Scales the arc of signature_arc, spring_settle and comet_swoop: 0.25 (default) keeps the style's arc, 0 is a straight line, 0.5 doubles it. Clamped to 0..1. | |
dwell_after_click_ms | number | Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80). | |
effects | object | Turn effects on or off. Omit a field to keep it; "default" restores the style default. | |
effects.glow | "on" | "off" | "default" | Soft glow around the cursor that grows with speed. | |
effects.magnet | "on" | "off" | "default" | Target glow when the magnetic style locks on. | |
effects.ripple | "on" | "off" | "default" | Ring that expands from the hotspot on click. | |
effects.squish | "on" | "off" | "default" | Brief scale-down of the cursor on click. | |
effects.trail | "on" | "off" | "default" | Short fading trail behind the cursor. | |
end_handle | number | Arc control-point offset from the end, as a fraction of the distance, for signature_arc, spring_settle and comet_swoop. Clamped to 0..1 (default 0.3). | |
glide_duration_ms | number | Move duration in milliseconds for fixed timing (1430 ms when 0, the default). A nonzero value with native or the default steady timing also fixes the duration. Clamped to 0..5000. | |
idle_hide_ms | number | Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to 0..60000 (default 15000). | |
session | string | required | Public label of the session that owns the cursor. Omitted or null motion fields keep their current value. |
spring | number | Arrival spring damping for classic: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1 (default 0.72). | |
start_handle | number | Arc control-point offset from the start, as a fraction of the distance, for signature_arc, spring_settle and comet_swoop. Clamped to 0..1 (default 0.3). | |
style | "signature_arc" | "spring_settle" | "magnetic" | "comet_swoop" | "adaptive" | "classic" | Trajectory style. signature_arc (default) is one arc with a small follow-through; spring_settle lands with one soft bounce; magnetic is pulled into the target; comet_swoop is a wide arc with a short trail; adaptive picks a careful approach for small targets and a swoop for long moves; classic is the previous Dubins glide. When the theme's reduced motion is on, every move is a short straight glide with no effects. | |
timing | "native" | "fitts" | "fixed" | "relaxed" | "steady" | "calm" | "deliberate" | steady (default) keeps the style's timing but makes every move take at least 600 ms, with a gentler ease; relaxed and calm do the same with a 450 or 750 ms floor. native uses the style's own timing; fitts scales the move time with distance and target size; deliberate is a slower Fitts curve (450..1300 ms); fixed uses glide_duration_ms (1430 ms when 0). | |
turn_radius | number | Minimum turning radius of the classic glide path, in points; smaller turns tighter. Clamped to 1..1000 (default 80). |
Example arguments
{"session":"<session>"}set_agent_cursor_theme#Select an already-installed cursor theme for a session.
Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
reduced_motion | "auto" | "on" | "off" | "auto" | Theme animation policy: on uses the theme's reduced-motion frames, off always animates, auto (default) leaves the choice to the host. |
session | string | required | Public label of the session that owns the cursor. |
theme_id | string | required | Id of an installed cursor theme (see cua-driver cursor-theme list). |
Example arguments
{"session":"<session>","theme_id":"<theme_id>"}get_agent_cursor_state#Return the session cursor's theme, semantic playback, position, visibility, and motion.
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | required | Public label of the session whose cursor to inspect. |
Example arguments
{"session":"<session>"}