Personalize the Cua cursor

Swap the agent cursor shape and palette: pick a built-in silhouette, override at runtime, or bring your own SVG/PNG/ICO.

The Cua Driver agent cursor ships with two built-in silhouettes:

teardrop (the default)
arrow

teardrop is the default. Opt back into the arrow with --cursor-shape arrow. You can also replace the silhouette entirely with your own SVG / PNG / JPEG / ICO file via --cursor-icon <path>, swap the body palette at runtime, or scale the bloom halo independently.

Pick a built-in silhouette#

cua-driver serve --cursor-shape teardrop   # explicit; same as the default
cua-driver serve --cursor-shape arrow      # opt into the procedural arrow

--cursor-shape is a daemon startup option. Passing it to an MCP proxy or one-shot CLI adapter does not change the already-running daemon's overlay; set it on cua-driver serve.

--cursor-icon <path> always wins over --cursor-shape: if you pass both, the custom file is what renders.

Change the cursor look at runtime#

Every per-instance cursor accepts a runtime style override via the set_agent_cursor_style MCP tool. An agent or harness can call it mid-session; the next paint frame picks up the new style.

{
  "gradient_colors": ["#FF6B6B", "#FFD93D"],
  "bloom_color":     "#FF6B6B"
}

gradient_colors: array of CSS hex strings used as the cursor body's tip-to-tail gradient. An empty array reverts to the palette default (#F0FBFF → #66D9FF → #35C6D8 on the teardrop; the palette's cursor_start/mid/end on the arrow).
bloom_color: hex string for the radial halo behind the cursor. Empty string reverts.
image_path: path to a PNG / JPEG / SVG / ICO file. When set, replaces the built-in silhouette with your asset. Empty string clears the override, reverting to the default silhouette.

Switch between the built-in arrow and teardrop silhouettes at runtime with set_agent_cursor_motion's cursor_icon field. Pass the built-in name or a file path, using the same vocabulary the CLI --cursor-shape / --cursor-icon flags accept. Both the CLI and MCP resolve names through the same BuiltinShape table, so they can never drift.

Use your own cursor asset#

Pass --cursor-icon <path> to cua-driver serve (or set image_path on set_agent_cursor_style at runtime). Supported formats: .svg, .png, .jpeg, .ico. The asset is rasterised once at startup into a 52×52 RGBA buffer and used in place of the built-in silhouette.

cua-driver serve --cursor-icon ~/my-cursor.svg

Tip orientation

Custom cursor assets are rendered with no rotation compensation. The driver assumes your asset's tip points to the right at rest. If your SVG has a tip pointing up, up-left, or anywhere else, the cursor will appear rotated off-axis during motion. Two options:

Re-author your SVG so the tip points right at the unrotated default. The driver's rotation logic then aligns the tip with motion direction automatically.
Stick with PNG / static art if you do not care about motion-aligned rotation. The cursor will render at a fixed orientation regardless of motion direction. This is what most OS cursor packs do.

Recolour at launch#

--cursor-palette <name> picks a built-in colour palette for the cursor at launch. It is the launch-time counterpart to the runtime set_agent_cursor_style palette. Like the other cursor flags it is parsed on serve and mcp only.

cua-driver serve --cursor-palette <name>

Run cua-driver serve --help for the available palette names.

Things that aren't currently personalizable#

Multiple built-in palettes per agent. Runtime overrides can recolour a cursor, but built-in named palettes are shared.
Shape render size. cursor_size controls the dot-style cursor radius. The shape-based render path uses its own fixed size.
Motion-path curve shape. Glide duration, post-click dwell, idle-hide delay, and spring damping are tunable via set_agent_cursor_motion, but the underlying path shape is fixed.