Window, menu bar and Settings
The window chrome, a Space's toolbar and sections, the menu bar menu, Settings and the coding agents' rows.
The window chrome, a Space's toolbar and sections, the menu bar menu, Settings and the coding agents' rows.
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
app_main_chrome, app_menu_bar and app_settings_page give the window chrome, the menu bar menu and the Settings page. app_space_detail_copy holds the words of a Space's sections; the agent functions turn AgentSetup results into Settings rows. app_login_item_launch_plan decides when the apps turn on launch at login by themselves.
app_display_name#"brave-otter" as "Brave Otter".
func appDisplayName(name: String) -> String| Parameter | Type | Default |
|---|---|---|
name | String | required |
Returns String
app_display_path#Home-relative path (~/x).
func appDisplayPath(path: String, home: String?) -> String| Parameter | Type | Default |
|---|---|---|
path | String | required |
home | Option<String> | required |
Returns String
app_format_bytes#"12 MB".
func appFormatBytes(bytes: UInt64) -> String| Parameter | Type | Default |
|---|---|---|
bytes | u64 | required |
Returns String
AppFact record#| Field | Type | Default | Description |
|---|---|---|---|
label | String | Label. | |
value | String | Value. | |
copy | Option<AppFactCopy> | A copy button after the value (the Space's identifier and image). | |
help | Option<String> | The tooltip: the full value (and an image's digest). | |
warning | Option<AppFactWarning> | A warning symbol after the value, with its tooltip: a local Space emulating another architecture. |
AppFactCopy record#| Field | Type | Default | Description |
|---|---|---|---|
text | String | What is copied (the full value). | |
symbol | String | SF Symbol (doc.on.doc). | |
help | String | Tooltip and accessibility label ("Copy"). | |
done_symbol / doneSymbol | String | The symbol while confirming (checkmark). | |
done_help / doneHelp | String | The tooltip while confirming ("Copied"). | |
confirm_ms / confirmMs | u32 | How long the confirmation shows, in milliseconds. |
app_delete_failed_text#The banner when Delete fails.
func appDeleteFailedText(name: String, error: String) -> String| Parameter | Type | Default |
|---|---|---|
name | String | required |
error | String | required |
Returns String
AppDetailCopy record#Returned by app_space_detail_copy.
| Field | Type | Default | Description |
|---|---|---|---|
stream_loading / streamLoading | String | "Looking for this Space's windows…" | |
stream_empty / streamEmpty | String | "No open windows in this Space yet." | |
stream_failed / streamFailed | String | When the window list could not be read. | |
stream_no_match / streamNoMatch | String | When a filter hides every window. | |
agents_loading / agentsLoading | String | "Looking for this Space's agents…" | |
agents_empty / agentsEmpty | String | "No agents have been started in this Space." | |
agents_failed / agentsFailed | String | When the runs could not be read (not the same as none). | |
agents_no_match / agentsNoMatch | String | When a filter hides every run. | |
drop_caption / dropCaption | String | The drop well's caption. | |
send_file / sendFile | String | "Send file…" | |
teleport_app / teleportApp | String | "Teleport an app…" | |
teleport_symbol / teleportSymbol | String | The teleport icon (TELEPORT_SYMBOL). | |
teleport_symbol_active / teleportSymbolActive | String | The teleport icon while a drag is over a drop target. |
app_space_detail_copy#The words of a Space's sections (Stream, Agents, Teleport).
func appSpaceDetailCopy() -> AppDetailCopyReturns AppDetailCopy
AppDetailAction record#| Field | Type | Default | Description |
|---|---|---|---|
id | AppDetailActionId | What it does. | |
label | String | Label. | |
symbol | Option<String> | SF Symbol (icon buttons). | |
help | String | Tooltip. | |
enabled | bool | Enabled. | |
destructive | bool | Drawn as destructive. | |
primary | bool | The prominent one. | |
busy | bool | Its action runs: a spinner in place of the icon. |
AppDetailActionId enum#.teleport
.pip
.share
.power
.delete
.open
.cancel| Variant | Description |
|---|---|
Teleport | "Teleport an app…" into the Space. |
Pip | The desktop in a picture-in-picture panel. |
Share | "Share": let another cua.ai account watch or edit the Space. |
Power | Turn it off or on (the power button, next to Delete). |
Delete | Delete (or remove from the list). |
Open | The desktop in its own window. |
Cancel | Stop a create that is still running and remove what it made. |
AppDeleteConfirm record#| Field | Type | Default | Description |
|---|---|---|---|
title | String | "Delete Brave Otter?" | |
message | String | What it means, one line. | |
confirm_label / confirmLabel | String | The destructive button. | |
confirm_enabled / confirmEnabled | bool | The destructive button can be pressed (a Space in your cloud that another device created cannot be deleted from here). | |
disabled_reason / disabledReason | Option<String> | Why not, beside the disabled button. | |
remove_label / removeLabel | Option<String> | For a Space in your cloud: "Remove from List", which forgets it and keeps it running there (remove_space). | |
cancel_label / cancelLabel | String | "Keep" (or "Cancel" beside Remove from List). |
AppSentFileInfo record#Returned by app_sent_file, app_sent_files_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | File name. | |
dest | String | Where it landed in the Space. | |
bytes | u64 | Bytes. |
app_sent_file#A send_file report as the files the drop well names.
func appSentFile(report: SpaceSendFileReport) -> AppSentFileInfo| Parameter | Type | Default |
|---|---|---|
report | SpaceSendFileReport | required |
Returns AppSentFileInfo
app_sent_files_from_json#Sent files from JSON (parity flows).
func appSentFilesFromJson(json: String) throws -> [AppSentFileInfo]| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns Vec<AppSentFileInfo> · Raises CuaError
app_drop_sending_text#The drop well's line while files go.
func appDropSendingText(paths: [String]) -> String| Parameter | Type | Default |
|---|---|---|
paths | Vec<String> | required |
Returns String
app_drop_sent_text#The drop well's line once they landed.
func appDropSentText(files: [AppSentFileInfo]) -> String| Parameter | Type | Default |
|---|---|---|
files | Vec<AppSentFileInfo> | required |
Returns String
AppSignInPhase enum#.idle
.starting
.waiting(userCode: String?)
.failed(message: String)| Variant | Description |
|---|---|
Idle | Nothing started. |
Starting | Asking for a code. |
Waiting | The browser is open. Fields: user_code: Option<String> |
Failed | It failed. Fields: message: String |
AppTelemetryInput record#| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | Usage data is shared. | |
locked_by / lockedBy | Option<String> | The environment decides (DO_NOT_TRACK, CUA_TELEMETRY, CI): who. |
app_menu#The menu bar item's menu: the Spaces the user can open (the notch's count), Cua Volume's sync state next to it and its conflicts, then the actions.
func appMenu(input: AppMenuInput) -> [AppMenuItem]| Parameter | Type | Default |
|---|---|---|
input | AppMenuInput | required |
Returns Vec<AppMenuItem>
AppMenuInput record#Returned by app_menu_input_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
spaces | Vec<AppSpace> | The roster (with "This machine"). | |
keyvault | Option<String> | Live Keyvault sign-ins (crate.keyvault.view.sharing_label). | |
sync | Option<AppDriveSyncInput> | Cua Volume's volume_sync_status, when read. | |
now_ms / nowMs | u64 | Now (Unix ms): a feed that has not answered for OFFLINE_AFTER_MS is offline. | |
backend | Option<String> | volume_storage's backend (fs, s3), when read: this machine's store with no other device has nothing to sync. | |
experiments | Option<AppExperiments> | Settings, Experiments: Cua Volume's sync state and conflicts only with Cua Volume on (none: shown, for callers that predate experiments). Off hides them; the volume keeps syncing. |
app_openable_count#The Spaces the user can open (the notch tab and the menu bar item).
func appOpenableCount(spaces: [AppSpace]) -> UInt32| Parameter | Type | Default |
|---|---|---|
spaces | Vec<AppSpace> | required |
Returns u32
AppAgentSettingsRow record#Returned by app_agent_settings_rows.
| Field | Type | Default | Description |
|---|---|---|---|
agent | String | Registry id. | |
name | String | Display name. | |
installed | bool | Installed. | |
configured | bool | cua skills and the cua MCP server are both in place (where supported). | |
detail | String | One line for the row. | |
skills_installed / skillsInstalled | u32 | Bundled skills present. | |
skills_total / skillsTotal | u32 | Bundled skills. | |
mcp_config / mcpConfig | Option<String> | MCP config file. | |
skills_dir / skillsDir | Option<String> | Skills directory. |
AppAgentSetupOutcomeInput record#Returned by app_agent_setup_outcome, app_agent_setup_outcomes_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
agents | Vec<String> | Agents it served. | |
target | String | skill or mcp. | |
item | String | Skill or server name. | |
change | String | created, updated, unchanged, removed, skipped, failed. | |
detail | String | Explanation. |
AppAgentSetupStatus record#Returned by app_agent_setup_status, app_agent_setup_statuses_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | Registry id (claude-code, codex, ...). | |
name | String | Display name. | |
installed | bool | Looks installed. | |
skills_dir / skillsDir | Option<String> | User skills directory, when it supports skills. | |
mcp_config / mcpConfig | Option<String> | MCP config file, when it supports MCP. | |
cua_configured / cuaConfigured | bool | The cua MCP server is configured. | |
skills_installed / skillsInstalled | Vec<String> | Bundled skills present. | |
skills_outdated / skillsOutdated | Vec<String> | Installed skills that differ from the bundled copy. | |
error | Option<String> | Problem reading its config. |
AppAgentSetupSummary record#Returned by app_agent_setup_summary.
| Field | Type | Default | Description |
|---|---|---|---|
text | String | "cua MCP server configured, 3 skills installed". | |
failed | Vec<String> | "name: why" per failed target. | |
line | String | "Claude Code: done" / "Claude Code: failed". |
AppChromeInput record#Returned by app_chrome_input_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
identity | Option<String> | The signed-in account. | |
cloud_configured / cloudConfigured | bool | Cua Cloud works (signed in, or client credentials). | |
can_sign_in / canSignIn | bool | Signing in is possible here (the native shell). | |
experiments | Option<AppExperiments> | Settings, Experiments: the Volume page only with Cua Volume on (none: every page, for callers that predate experiments). |
AppLoginItemInput record#| Field | Type | Default | Description |
|---|---|---|---|
status | AppLoginItemStatus | What the system reports. | |
busy | bool | A change is running. | |
error | Option<String> | Why the last change failed. | |
provides_spaces / providesSpaces | bool | This machine provides Spaces to your other devices (host setup's "A spare machine for Spaces"). | |
runs_agents / runsAgents | bool | This machine runs persistent agents. |
AppLoginItemPlan record#Returned by app_login_item_launch_plan.
| Field | Type | Default | Description |
|---|---|---|---|
register | bool | Register the app as a login item now. | |
record | Option<bool> | Save this as the user's choice (AppSettings::launch_at_login). |
AppMainChrome record#Returned by app_main_chrome.
| Field | Type | Default | Description |
|---|---|---|---|
title | String | Window title when nothing is selected. | |
new_space_label / newSpaceLabel | String | "New Space". | |
new_space_shortcut / newSpaceShortcut | String | "⌘N". | |
search_placeholder / searchPlaceholder | String | The sidebar search's placeholder. | |
keyvault_title / keyvaultTitle | String | The Keyvault section's title. | |
account | String | The account line: the identity, "API key" or "Not signed in". | |
sign_in_label / signInLabel | Option<String> | "Sign in", when signing in is offered. | |
settings_label / settingsLabel | String | "Settings". | |
settings_shortcut / settingsShortcut | String | "⌘,". | |
empty_title / emptyTitle | String | With no Spaces: the heading. | |
empty_action / emptyAction | String | With no Spaces: the button. | |
volume_label / volumeLabel | Option<String> | The sidebar's Volume page entry ("Volume"); none while the Cua Volume experiment is off (the page and its route are hidden; a mounted volume stays mounted). |
AppMenuItem record#Returned by app_menu, app_menu_bar, app_menu_bar_with_keyvault.
| Field | Type | Default | Description |
|---|---|---|---|
id | AppMenuItemId | What it does. | |
label | String | Label (empty for a separator). | |
shortcut | Option<String> | "⌘,", "⌘Q". | |
enabled | bool | Enabled. |
AppSettingsInput record#Returned by app_settings_input_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
identity | Option<String> | The signed-in account. | |
api_key_client / apiKeyClient | Option<String> | Cua Cloud through client credentials (an API key): its client id. | |
sign_in / signIn | AppSignInPhase | The sign-in in progress. | |
can_sign_out / canSignOut | bool | Signing out is possible (a user session). | |
menu_bar / menuBar | bool | The Spaces tab is hidden from the notch (the menu bar item is the entry point). | |
default_location / defaultLocation | AppLocation | Where New Space starts. | |
location_locked_by / locationLockedBy | Option<String> | The environment sets the default location: which variable. | |
telemetry | Option<AppTelemetryInput> | The telemetry switch (none until read). | |
agents | Option<Vec<AppAgentSettingsRow>> | Coding agents (none while detecting). | |
agents_busy / agentsBusy | bool | "Configure all" is running. | |
agents_pending / agentsPending | Vec<String> | Agents with an action running. | |
billing | Option<AppBillingStatus> | The account's Cua Cloud billing, once read (signed in). | |
login_item / loginItem | Option<AppLoginItemInput> | Launch at login, once the system was asked (none: no rows). | |
experiments | AppExperiments | Settings, Experiments (what the page mentions follows them). |
AppSettingsOption record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | show, hide, local, cloud, on, off. | |
label | String | Label. | |
active | bool | Chosen. |
AppSettingsPage record#Returned by app_experiments_page, app_settings_page, app_settings_with_storage.
| Field | Type | Default | Description |
|---|---|---|---|
title | String | "Settings". | |
sections | Vec<AppSettingsSection> | Account, General, Privacy (once read), AI agents. |
AppSettingsRow record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | Stable id (account, sign-in, notch, agent:codex, ...). | |
kind | AppSettingsRowKind | How it draws. | |
label | String | Label (or the note's text). | |
value | Option<String> | Muted value. | |
button | Option<String> | A button's label. | |
options | Vec<AppSettingsOption> | A choice's options. | |
enabled | bool | The button or choice can be used. | |
help | Option<String> | Tooltip. | |
link_label / linkLabel | Option<String> | A note's link: label. | |
link_url / linkUrl | Option<String> | A note's link: URL (or what a Text row's button opens). | |
placeholder | Option<String> | A field's placeholder. |
AppSettingsSection record#Returned by app_storage_section.
| Field | Type | Default | Description |
|---|---|---|---|
id | String | account, general, privacy, agents. | |
title | String | "Account", "General", "Privacy", "AI agents". | |
button | Option<String> | A button in the header. | |
button_enabled / buttonEnabled | bool | That button can be used. | |
button_help / buttonHelp | Option<String> | Its tooltip. | |
rows | Vec<AppSettingsRow> | Rows. |
AppLoginItemStatus enum#.enabled
.notRegistered
.requiresApproval
.notFound| Variant | Description |
|---|---|
Enabled | Registered and allowed: the app opens at login. |
NotRegistered | Not registered. |
RequiresApproval | Registered, waiting for the user to allow it in System Settings, Login Items. |
NotFound | The system cannot find the app as a login item. |
AppMenuItemId enum#.status
.separator
.open
.newSpace
.settings
.quit
.volumeConflicts| Variant | Description |
|---|---|
Status | The status line (disabled). |
Separator | A separator. |
Open | Show the main window. |
NewSpace | The New Space sheet. |
Settings | Settings. |
Quit | Quit. |
VolumeConflicts | Cua Volume's conflicts: opens the Volume page. |
AppSettingsRowKind enum#.text
.choice
.note
.error
.field
.secret
.prompt
.link
.toggle| Variant | Description |
|---|---|
Text | Label, value and an optional button. |
Choice | Label and a segmented choice. |
Note | A muted line (with an optional link). |
Error | An error line. |
Field | Label and a text field (value is its text). |
Secret | Label and a secure text field (value is its text). |
Prompt | A label over read-only text to copy (value), with a Copy button. |
Link | A small link-style button (the label). |
Toggle | Label and a switch: options are on and off, the active one is its state (a choice drawn as a switch). |
app_agent_settings_rows#Settings rows for the coding agents (total: bundled skills).
func appAgentSettingsRows(statuses: [AppAgentSetupStatus], total: UInt32) -> [AppAgentSettingsRow]| Parameter | Type | Default |
|---|---|---|
statuses | Vec<AppAgentSetupStatus> | required |
total | u32 | required |
Returns Vec<AppAgentSettingsRow>
app_agent_setup_outcome#The SDK's setup outcome as the app core reads it.
func appAgentSetupOutcome(outcome: AgentSetupOutcome) -> AppAgentSetupOutcomeInput| Parameter | Type | Default |
|---|---|---|
outcome | AgentSetupOutcome | required |
Returns AppAgentSetupOutcomeInput
app_agent_setup_outcomes_from_json#Agent setup outcomes from JSON (parity flows).
func appAgentSetupOutcomesFromJson(json: String) throws -> [AppAgentSetupOutcomeInput]| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns Vec<AppAgentSetupOutcomeInput> · Raises CuaError
app_agent_setup_status#The SDK's agent detection as the app core reads it.
func appAgentSetupStatus(info: AgentInfo) -> AppAgentSetupStatus| Parameter | Type | Default |
|---|---|---|
info | AgentInfo | required |
Returns AppAgentSetupStatus
app_agent_setup_statuses_from_json#Coding agents' setup states from JSON (fixtures, parity flows).
func appAgentSetupStatusesFromJson(json: String) throws -> [AppAgentSetupStatus]| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns Vec<AppAgentSetupStatus> · Raises CuaError
app_agent_setup_summary#What an agent setup did for one agent.
func appAgentSetupSummary(outcomes: [AppAgentSetupOutcomeInput], agent: String, name: String) -> AppAgentSetupSummary| Parameter | Type | Default |
|---|---|---|
outcomes | Vec<AppAgentSetupOutcomeInput> | required |
agent | String | required |
name | String | required |
Returns AppAgentSetupSummary
app_chrome_input_from_json#The chrome's input from JSON (parity flows).
func appChromeInputFromJson(json: String) throws -> AppChromeInput| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns AppChromeInput · Raises CuaError
app_login_item_launch_plan#What the app does about launch at login at launch (the user's choice, whether the first run finished, whether this machine provides Spaces or runs persistent agents, and what the system reports).
func appLoginItemLaunchPlan(choice: Bool?, onboarded: Bool, serves: Bool, status: AppLoginItemStatus) -> AppLoginItemPlan| Parameter | Type | Default |
|---|---|---|
choice | Option<bool> | required |
onboarded | bool | required |
serves | bool | required |
status | AppLoginItemStatus | required |
Returns AppLoginItemPlan
app_main_chrome#The main window's chrome (account line, New Space, empty state).
func appMainChrome(input: AppChromeInput) -> AppMainChrome| Parameter | Type | Default |
|---|---|---|
input | AppChromeInput | required |
Returns AppMainChrome
app_menu_bar#The menu bar item's menu.
func appMenuBar(spaces: UInt32) -> [AppMenuItem]| Parameter | Type | Default |
|---|---|---|
spaces | u32 | required |
Returns Vec<AppMenuItem>
app_menu_bar_with_keyvault#The menu bar item's menu with the live Keyvault sharing line
(kv_sharing_label) when there is one.
func appMenuBarWithKeyvault(spaces: UInt32, keyvault: String?) -> [AppMenuItem]| Parameter | Type | Default |
|---|---|---|
spaces | u32 | required |
keyvault | Option<String> | required |
Returns Vec<AppMenuItem>
app_settings_input_from_json#The Settings page's input from JSON (parity flows).
func appSettingsInputFromJson(json: String) throws -> AppSettingsInput| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns AppSettingsInput · Raises CuaError
app_settings_page#The Settings page.
func appSettingsPage(input: AppSettingsInput) -> AppSettingsPage| Parameter | Type | Default |
|---|---|---|
input | AppSettingsInput | required |
Returns AppSettingsPage