Agent setup

Detect coding agents, install cua skills and configure their MCP servers.

cua.agent_setup() onboards coding agents on this machine: skills and MCP configuration.

`AgentSetup`#

Agent onboarding for this machine's user.

Returned by Cua.agent_setup.

Method	Description
`configure_mcp`	Configures the MCP server (default: `cua mcp`, `cua` resolved on PATH; `cua-local mcp` named `cua-local` for the Local app) for `agents`.
`connect_json`	Connect (and Reconnect) for `agents`: Cua's skills and MCP entry (`server`, default this channel's cua), and with `sign_in` the agent's sign-in copied into Keyvault on This Mac (Claude Code's is the sign-in it already has, read from where Claude Code keeps it).
`connection_status_json`	Whether each agent is really connected (CONTRACT §4: `{agents, checked_at_ms}`), as JSON, the same JSON `cua connect status --json` prints and the `connect_status` MCP tool answers.
`device_sign_in_start_json`	Starts `agent`'s device-code sign-in made for Cua (Codex: `codex login --device-auth` in a folder Cua owns).
`device_sign_in_wait_json`	Waits for a device sign-in to be approved and saves it into Keyvault on This Mac.
`disconnect_json`	Disconnect: what Connect did, undone (the previous config entry back from Cua's record, the skills, and with `sign_in` the copy in Keyvault).
`disconnect_parts_json`	Disconnect of some parts only (an app's page's switches): Cua's skills and/or its MCP entry, and with `sign_in` the copy in Keyvault.
`install_skills`	Installs `skills` (empty: all bundled) for `agents`.
`remove`	Removes what cua added for `agents` (skills and/or MCP).
`select`	Resolves `all` (installed agents), `none` or `claude,codex` to ids.
`set_onboarding_declined`	Saves or clears the "never" answer (`~/.cua/config`).
`setup_cua_driver`	Background computer-use for `agents`: the bundled `cua-driver` skill (`skills`) and the `cua-driver mcp` server (`mcp`), launching `command` (default: the installed cua-driver).
`sign_in`	Starts `agent`'s own sign-in on this computer (`codex login`: the browser opens).
`update`	Refreshes installed cua skills and re-points managed MCP entries.

Accessor	Returns	Description
`detect()`	`Vec<AgentInfo>`	Every supported agent, installed or not (read-only).
`onboarding_declined()`	`bool`	Whether the user said "never" to agent onboarding.
`skills()`	`Vec<BundledSkill>`	The skills bundled with this SDK.
`status()`	`Vec<AgentInfo>`	Same as `detect`, named for status displays.

`AgentSetup.configure_mcp`#

Configures the MCP server (default: cua mcp, cua resolved on PATH; cua-local mcp named cua-local for the Local app) for agents. A server without a name gets the channel's.

async def configure_mcp(self, agents: List[str], server: Optional[AgentMcpServer]) -> List[AgentSetupOutcome]

Parameter	Type	Default
`agents`	`Vec<String>`	required
`server`	`Option<AgentMcpServer>`	required

Returns Vec<AgentSetupOutcome> · Async · Raises CuaError

`AgentSetup.connect_json`#

Connect (and Reconnect) for agents: Cua's skills and MCP entry (server, default this channel's cua), and with sign_in the agent's sign-in copied into Keyvault on This Mac (Claude Code's is the sign-in it already has, read from where Claude Code keeps it). With driver, the cua-driver entry the host app wants (the Cua Driver it carries, by absolute path) is written too; driver_permissions_granted says whether Screen Recording and Accessibility are on for it (None: unknown). Each part asked for is reported on its own (parts), so one can be retried by asking for it alone. JSON: one result per agent.

async def connect_json(self, agents: List[str], server: Optional[AgentMcpServer], skills: bool, mcp: bool, sign_in: bool, driver: Optional[AgentMcpServer], driver_permissions_granted: Optional[bool]) -> str

Parameter	Type	Default
`agents`	`Vec<String>`	required
`server`	`Option<AgentMcpServer>`	required
`skills`	`bool`	required
`mcp`	`bool`	required
`sign_in`	`bool`	required
`driver`	`Option<AgentMcpServer>`	required
`driver_permissions_granted`	`Option<bool>`	required

Returns String · Async · Raises CuaError

`AgentSetup.connection_status_json`#

Whether each agent is really connected (CONTRACT §4: {agents, checked_at_ms}), as JSON, the same JSON cua connect status --json prints and the connect_status MCP tool answers. expected is the MCP server this app writes (an entry launching another cua is stale); refresh skips the few-second cache (window focus).

def connection_status_json(self, expected: Optional[AgentMcpServer], refresh: bool) -> str

Parameter	Type	Default
`expected`	`Option<AgentMcpServer>`	required
`refresh`	`bool`	required

Returns String

`AgentSetup.device_sign_in_start_json`#

Starts agent's device-code sign-in made for Cua (Codex: codex login --device-auth in a folder Cua owns). JSON {id, url, code}: show the link and the code, then wait with Self.device_sign_in_wait_json.

async def device_sign_in_start_json(self, agent: str) -> str

Parameter	Type	Default
`agent`	`String`	required

Returns String · Async · Raises CuaError

`AgentSetup.device_sign_in_wait_json`#

Waits for a device sign-in to be approved and saves it into Keyvault on This Mac. JSON: {imported, refused, line} (as Connect's sign_in).

async def device_sign_in_wait_json(self, id: str) -> str

Parameter	Type	Default
`id`	`String`	required

Returns String · Async · Raises CuaError

`AgentSetup.disconnect_json`#

Disconnect: what Connect did, undone (the previous config entry back from Cua's record, the skills, and with sign_in the copy in Keyvault). JSON {outcomes, removed_sign_ins}.

async def disconnect_json(self, agents: List[str], sign_in: bool) -> str

Parameter	Type	Default
`agents`	`Vec<String>`	required
`sign_in`	`bool`	required

Returns String · Async · Raises CuaError

`AgentSetup.disconnect_parts_json`#

Disconnect of some parts only (an app's page's switches): Cua's skills and/or its MCP entry, and with sign_in the copy in Keyvault. JSON {outcomes, removed_sign_ins}.

async def disconnect_parts_json(self, agents: List[str], skills: bool, mcp: bool, sign_in: bool) -> str

Parameter	Type	Default
`agents`	`Vec<String>`	required
`skills`	`bool`	required
`mcp`	`bool`	required
`sign_in`	`bool`	required

Returns String · Async · Raises CuaError

`AgentSetup.install_skills`#

Installs skills (empty: all bundled) for agents. Folders cua did not write are skipped unless force.

async def install_skills(self, agents: List[str], skills: List[str], force: bool) -> List[AgentSetupOutcome]

Parameter	Type	Default
`agents`	`Vec<String>`	required
`skills`	`Vec<String>`	required
`force`	`bool`	required

Returns Vec<AgentSetupOutcome> · Async · Raises CuaError

`AgentSetup.remove`#

Removes what cua added for agents (skills and/or MCP).

async def remove(self, agents: List[str], skills: bool, mcp: bool) -> List[AgentSetupOutcome]

Parameter	Type	Default
`agents`	`Vec<String>`	required
`skills`	`bool`	required
`mcp`	`bool`	required

Returns Vec<AgentSetupOutcome> · Async · Raises CuaError

`AgentSetup.select`#

Resolves all (installed agents), none or claude,codex to ids.

def select(self, selection: str) -> List[str]

Parameter	Type	Default
`selection`	`String`	required

Returns Vec<String> · Raises CuaError

`AgentSetup.set_onboarding_declined`#

Saves or clears the "never" answer (~/.cua/config).

def set_onboarding_declined(self, declined: bool) -> None

Parameter	Type	Default
`declined`	`bool`	required

Raises CuaError

`AgentSetup.setup_cua_driver`#

Background computer-use for agents: the bundled cua-driver skill (skills) and the cua-driver mcp server (mcp), launching command (default: the installed cua-driver). The same step as cua agents setup --cua-driver and the installers' cua-driver item.

async def setup_cua_driver(self, agents: List[str], command: Optional[str], skills: bool, mcp: bool) -> List[AgentSetupOutcome]

Parameter	Type	Default
`agents`	`Vec<String>`	required
`command`	`Option<String>`	required
`skills`	`bool`	required
`mcp`	`bool`	required

Returns Vec<AgentSetupOutcome> · Async · Raises CuaError

`AgentSetup.sign_in`#

Starts agent's own sign-in on this computer (codex login: the browser opens). Returns once it is running; detect reports signed_in when it is done. cua never reads or copies the sign-in.

def sign_in(self, agent: str) -> None

Parameter	Type	Default
`agent`	`String`	required

Raises CuaError

`AgentSetup.update`#

Refreshes installed cua skills and re-points managed MCP entries.

async def update(self, server: Optional[AgentMcpServer]) -> List[AgentSetupOutcome]

Parameter	Type	Default
`server`	`Option<AgentMcpServer>`	required

Returns Vec<AgentSetupOutcome> · Async · Raises CuaError

`AgentInfo` record#

One AI coding agent and what cua configured for it.

Returned by AgentSetup.detect, AgentSetup.status.

Field	Type	Default	Description
`id`	`String`		Registry id (`claude-code`, `codex`, `cursor`, ...).
`name`	`String`		Display name.
`installed`	`bool`		Whether it looks installed.
`evidence`	`Vec<String>`		What gave it away (`bin:<path>`, `path:<dir>`, `app:<bundle>`).
`skills_dir` / `skillsDir`	`Option<String>`		User skills directory, when the agent supports Agent Skills.
`mcp_config` / `mcpConfig`	`Option<String>`		User MCP config file, when the agent supports MCP.
`mcp_format` / `mcpFormat`	`Option<String>`		`json`, `toml` or `yaml`.
`cua_configured` / `cuaConfigured`	`bool`		A `cua` MCP server launching a cua binary is configured.
`cua_managed` / `cuaManaged`	`bool`		That entry is the one cua wrote.
`cua_driver_configured` / `cuaDriverConfigured`	`bool`		A `cua-driver` MCP server (background computer-use) is configured.
`skills_installed` / `skillsInstalled`	`Vec<String>`		Bundled skills present in the skills directory.
`skills_outdated` / `skillsOutdated`	`Vec<String>`		Installed bundled skills that differ from this SDK's copy.
`error`	`Option<String>`		Problem reading the MCP config (for example a malformed file).
`unverified`	`Option<String>`		What could not be verified from the agent's official docs.
`sign_in` / `signIn`	`Option<String>`	`None`	The account the agent signs in with on its own (`ChatGPT` for Codex), when cua can see that sign-in.
`signed_in` / `signedIn`	`bool`	`false`	That sign-in is on this computer.

`AgentMcpServer` record#

The MCP server to register.

Field	Type	Default	Description
`name`	`String`	`"cua"`	Server name (`cua`).
`command`	`String`		Launch command (an absolute `cua` path is best: GUI agents often lack the shell PATH).
`args`	`Vec<String>`		Arguments (`["mcp"]`).
`env`	`HashMap<String, String>`		Extra environment.

`AgentSetupOutcome` record#

One target's outcome.

Returned by AgentSetup.configure_mcp, AgentSetup.install_skills, AgentSetup.remove, AgentSetup.setup_cua_driver, AgentSetup.update.

Field	Type	Description
`agents`	`Vec<String>`	Agents served by this target.
`target`	`AgentSetupTarget`	Kind.
`item`	`String`	Skill or server name.
`path`	`String`	Skill folder or config file.
`change`	`AgentSetupChange`	Result.
`detail`	`String`	Explanation.
`backup`	`Option<String>`	Backup taken before this write.

`BundledSkill` record#

A skill bundled with the SDK.

Returned by AgentSetup.skills.

Field	Type	Description
`name`	`String`	Name.
`description`	`String`	Description.
`version`	`String`	Version.
`files`	`u32`	Number of files.

`AgentSetupChange` enum#

What happened to one target.

AgentSetupChange.CREATED
AgentSetupChange.UPDATED
AgentSetupChange.UNCHANGED
AgentSetupChange.REMOVED
AgentSetupChange.SKIPPED
AgentSetupChange.FAILED

Variant	Description
`Created`	Written where nothing was.
`Updated`	Replaced or edited.
`Unchanged`	Already as wanted.
`Removed`	Removed (or the previous entry restored).
`Skipped`	Deliberately left alone (see detail).
`Failed`	Failed (see detail); the target was left untouched.

`AgentSetupTarget` enum#

What an operation touched.

AgentSetupTarget.SKILL
AgentSetupTarget.MCP

Variant	Description
`Skill`	A skill folder.
`Mcp`	An MCP config entry.

Agent setup

AgentSetup#

AgentSetup.configure_mcp#

AgentSetup.connect_json#

AgentSetup.connection_status_json#

AgentSetup.device_sign_in_start_json#

AgentSetup.device_sign_in_wait_json#

AgentSetup.disconnect_json#

AgentSetup.disconnect_parts_json#

AgentSetup.install_skills#

AgentSetup.remove#

AgentSetup.select#

AgentSetup.set_onboarding_declined#

AgentSetup.setup_cua_driver#

AgentSetup.sign_in#

AgentSetup.update#

AgentInfo record#

AgentMcpServer record#

AgentSetupOutcome record#

BundledSkill record#

AgentSetupChange enum#

AgentSetupTarget enum#

`AgentSetup`#

`AgentSetup.configure_mcp`#

`AgentSetup.connect_json`#

`AgentSetup.connection_status_json`#

`AgentSetup.device_sign_in_start_json`#

`AgentSetup.device_sign_in_wait_json`#

`AgentSetup.disconnect_json`#

`AgentSetup.disconnect_parts_json`#

`AgentSetup.install_skills`#

`AgentSetup.remove`#

`AgentSetup.select`#

`AgentSetup.set_onboarding_declined`#

`AgentSetup.setup_cua_driver`#

`AgentSetup.sign_in`#

`AgentSetup.update`#

`AgentInfo` record#

`AgentMcpServer` record#

`AgentSetupOutcome` record#

`BundledSkill` record#

`AgentSetupChange` enum#

`AgentSetupTarget` enum#