Swift Integration

CuaDriverCore and CuaDriverServer are available as Swift library products directly from the trycua/cua repository. Use this when you want to embed accessibility automation, window capture, or MCP tool handling into your own macOS Swift app or package — without shelling out to the cua-driver CLI.

Add the dependency

In your Package.swift:

dependencies: [
    .package(
        url: "https://github.com/trycua/cua.git",
        from: "cua-driver-v0.1.0"
    ),
],

Then add the products you need to your target:

targets: [
    .target(
        name: "MyApp",
        dependencies: [
            // Accessibility, input synthesis, window capture, recording.
            // No external dependencies — system frameworks only.
            .product(name: "CuaDriverCore", package: "cua"),

            // MCP tool handlers and daemon layer (adds swift-sdk dependency).
            // Use this if you want to expose cua-driver tools over MCP.
            .product(name: "CuaDriverServer", package: "cua"),
        ]
    ),
]

CuaDriverCore depends only on system frameworks (AppKit, CoreGraphics, ScreenCaptureKit, etc.). CuaDriverServer adds modelcontextprotocol/swift-sdk for the MCP protocol types.

What's in each product

CuaDriverCore

Low-level macOS automation primitives:

Module area	What it gives you
`AppStateEngine`	AX tree snapshots with element-index caching
`AppLauncher`	Launch apps without focus steal
`AXInput`	Perform AX actions, read attributes
`MouseInput` / `KeyboardInput`	Synthesize CGEvents
`WindowCapture`	Per-window screenshots via ScreenCaptureKit
`RecordingSession`	Trajectory recording and replay
`AgentCursor`	Animated overlay cursor
`BrowserJS` / `ElectronJS`	Execute JS in browser tabs via Apple Events or CDP
`AXPageReader`	Extract text / query DOM from WKWebView AX trees

CuaDriverServer

Ready-made MCP tool handlers built on CuaDriverCore:

import CuaDriverServer

let registry = ToolRegistry.default
// registry.handlers["click"], ["get_window_state"], ["page"], etc.

Embed the full tool set in your own MCP server:

import MCP
import CuaDriverServer

let server = MCPServer(tools: ToolRegistry.default.allTools) { name, args in
    try await ToolRegistry.default.call(name, arguments: args)
}

Minimum requirements

macOS 14 (Sonoma) or later
Swift 6.0+

TCC permissions

Calling AX or screen-capture APIs from an embedded library still requires the host app to hold the relevant TCC grants:

Accessibility — for any AXUIElement work (snapshots, clicks, AX actions).
Screen Recording — for WindowCapture screenshots.

Grant these under System Settings → Privacy & Security against your app's bundle identifier, the same as for the standalone CuaDriver.app.

Cursor customization

AgentCursorRenderer.shared drives the visual style applied to every click animation. Set it at app startup from the @MainActor context — changes take effect on the next rendered frame.

Custom gradient colors

import CuaDriverCore

await MainActor.run {
    AgentCursorRenderer.shared.style = AgentCursorStyle(
        strokeGradientStops: [
            AgentCursorGradientStop(color: NSColor(hex: "#A855F7")!, location: 0),
            AgentCursorGradientStop(color: NSColor(hex: "#6366F1")!, location: 1),
        ],
        bloomColor: NSColor(hex: "#A855F7")!
    )
}

Custom PNG / SVG cursor image

Replace the default arrow with any image NSImage can load (PNG, JPEG, PDF, SVG on macOS 12+):

import CuaDriverCore

await MainActor.run {
    let img = NSImage(contentsOf: Bundle.main.url(forResource: "cursor", withExtension: "png")!)
    AgentCursorRenderer.shared.style = AgentCursorStyle(image: img)
}

The image is drawn at shapeSize × shapeSize points (default 22 pt), centered on the cursor position and rotated to track the motion heading. To suppress the bloom halo behind it, pass bloomCenterAlpha: 0.

Revert to default

await MainActor.run {
    AgentCursorRenderer.shared.style = .default
}

All style knobs

Parameter	Type	Default	Description
`image`	`NSImage?`	`nil`	Custom cursor image (replaces arrow when non-nil)
`strokeGradientStops`	`[AgentCursorGradientStop]`	ice-blue → cyan → mint	Arrow fill gradient
`bloomColor`	`NSColor`	cyan `#5EC0E8`	Bloom halo and focus-rect color
`bloomCenterAlpha`	`CGFloat`	`0.55`	Center opacity of the bloom glow
`shapeSize`	`CGFloat`	`22`	Width and height of the cursor shape (points)

Was this page helpful?

Swift Integration

On this page