window.desktop API Reference for Cody Renderer

The window.desktop object is the contextBridge API that Cody’s Electron preload script (electron/preload/index.ts) exposes to every renderer window. Because Cody’s BrowserWindow instances run with sandbox: true, contextIsolation: true, and nodeIntegration: false, this bridge is the only way a renderer can communicate with the main process. Every method on window.desktop returns a Promise that resolves once the corresponding ipcRenderer.invoke call settles in the main process.

TypeScript users can augment the global Window interface to get full type safety. Import the types from src/types.ts and declare window.desktop with the shape documented below.

Data

Methods for loading and persisting the entire application state to disk.

`loadData`

window.desktop.loadData(): Promise<AppState | null>

Loads the persisted AppState from cody-data.json in the Electron userData directory. If the primary file is missing or corrupt, the main process automatically falls back to the daily backup (cody-data.backup.json). Returns null when no data exists yet (first launch). Returns: Promise<AppState | null>

`saveData`

window.desktop.saveData(data: AppState): Promise<boolean>

Persists the full AppState to disk using an atomic write (write to a .tmp file then rename). Before writing, the main process takes a once-per-day backup of the previous file.

data

AppState

required

The complete application state to persist. The serialized JSON must not exceed 5 MB — the main process rejects larger payloads with an error.

Returns: Promise<boolean> — true on success; throws on size-limit violations.

Calls that would produce a file larger than 5 MB throw an Error. Wrap saveData in a try/catch and surface the error to the user.

Notifications & Reminders

Methods for showing native Windows notifications and scheduling future alerts.

`notify`

window.desktop.notify(title: string, body: string): Promise<boolean>

Sends a native Windows notification immediately via Electron’s Notification API.

title

string

required

Notification title. Truncated to 180 characters; control characters are stripped.

body

string

required

Notification body text. Same 180-character limit and sanitization as title.

Returns: Promise<boolean> — false if the platform does not support notifications.

Notifications are not suppressed in focus mode — only dnd mode suppresses them. See setFocus for details.

`scheduleReminder`

window.desktop.scheduleReminder(reminder: Reminder): Promise<boolean>

Schedules a native notification to fire at the time specified in reminder.at. If a reminder with the same id already exists, the previous timer is cancelled and replaced.

reminder

Reminder

required

The reminder to schedule. See the Reminder type for the full field list. The at field must be a valid ISO 8601 date-time string in the future; past reminders return false immediately.

Returns: Promise<boolean> — true if the timer was registered, false if the target time is already past or the payload failed validation.

Reminders whose id starts with meeting- are treated as meeting reminders and are not suppressed in focus mode — only dnd mode suppresses them.

`cancelReminder`

window.desktop.cancelReminder(id: string): Promise<boolean>

Cancels a previously scheduled reminder and clears its timer.

string

required

The unique reminder ID to cancel. Truncated to 120 characters.

Returns: Promise<boolean> — always true for trusted senders, even if no reminder with that ID was found.

Window Control

Methods for managing the assistant and pet windows from renderer code.

`openAssistant`

window.desktop.openAssistant(): Promise<boolean>

Shows (and focuses) the main assistant BrowserWindow. Hides the pet window. If the assistant window does not yet exist it is created first. Returns: Promise<boolean>

`showPet`

window.desktop.showPet(): Promise<boolean>

Hides the assistant window and shows the floating pet window. The pet is clamped to the nearest display’s work area. Returns: Promise<boolean>

`minimizeWindow`

window.desktop.minimizeWindow(): Promise<boolean>

Minimizes the assistant window. When the window is minimized the minimize event fires and Cody automatically transitions back to the pet view. Returns: Promise<boolean>

`toggleMaximizeWindow`

window.desktop.toggleMaximizeWindow(): Promise<boolean>

Maximizes the assistant window if it is currently in the normal state, or restores it to normal size if it is already maximized. Returns: Promise<boolean> — false if the assistant window does not exist.

`closeWindow`

window.desktop.closeWindow(): Promise<boolean>

Closes the assistant window. Because isQuitting is false during normal use, the close event is intercepted and the window transitions to the pet view rather than destroying itself. Returns: Promise<boolean>

`openExternal`

window.desktop.openExternal(url: string): Promise<boolean>

Opens a URL in the user’s default system browser via shell.openExternal.

url

string

required

The URL to open. Must begin with https:// — any other scheme is rejected and the method returns false.

Returns: Promise<boolean> — false if the URL does not pass the https:// check.

Only HTTPS URLs are accepted. HTTP, file://, javascript:, and all other schemes are silently blocked.

Pet Control

Methods for controlling the desktop pet widget — its context menu, drag behavior, and live state updates.

`showPetMenu`

window.desktop.showPetMenu(): Promise<boolean>

Displays the pet’s native context menu. The menu includes options to open Cody, start Focus / DND modes (or deactivate the current one), and quit the application. Returns: Promise<boolean>

`startPetDrag`

window.desktop.startPetDrag(): Promise<boolean>

Begins a drag session for the pet window. Records the cursor start position and the pet’s current bounds. A 16 ms polling interval is started to track cursor movement. Returns: Promise<boolean> — only callable from the pet window; returns false from the assistant window.

`movePetDrag`

window.desktop.movePetDrag(): Promise<boolean>

Delivers an intermediate drag position update. Moves the pet window to follow the cursor, clamped to the display’s work area with a small edge overhang allowance. Returns: Promise<boolean> — false if no drag session is active or the call did not originate from the pet window.

`endPetDrag`

window.desktop.endPetDrag(): Promise<boolean>

Ends the active drag session, stops the polling interval, performs a final position update, and clamps the pet within the work area. Returns: Promise<boolean> — resolves to true if the pet actually moved during the drag, false if the pointer never travelled far enough to be considered a drag (e.g. a click).

`petUpdate`

window.desktop.petUpdate(payload: PetUpdate): Promise<boolean>

Pushes a PetUpdate from the assistant window to the pet window. The main process forwards the payload via petWindow.webContents.send('pet-update', payload).

payload

PetUpdate

required

Either a { type: 'state' } mood/badge update or a { type: 'celebrate' } celebratory animation trigger. See PetUpdate.

Returns: Promise<boolean> — false if the call does not originate from the assistant window (this channel is one-directional: assistant → pet).

Outlook Sync

`syncOutlookClassic`

window.desktop.syncOutlookClassic(options?: { ai?: AiConfig }): Promise<OutlookSyncResult>

Triggers a full Outlook Classic COM synchronization. The main process dynamically imports electron/main/outlook and spawns a PowerShell script that reads the user’s calendar and inbox via the Outlook COM API. When an AiConfig is provided the sync pipeline runs AI classification on the inbox items.

options

object

Optional configuration object.

Show options fields

options.ai

AiConfig

AI provider configuration for email classification. When omitted, emails are imported without AI-generated categorization. See AiConfig.

Returns: Promise<OutlookSyncResult> — see OutlookSyncResult.

This method is only meaningful on Windows with Outlook Classic (COM) installed. It throws Error('Origen no autorizado') if called from an untrusted sender.

File Operations

`exportFile`

window.desktop.exportFile(defaultName: string, content: string): Promise<string | null>

Opens the native Save File dialog pre-populated with defaultName and writes content to the path the user selects.

defaultName

string

required

Suggested filename shown in the Save dialog. Path-traversal characters (<>:"/\|?* and control chars) are stripped via safeFileName() and the result is capped at 120 characters.

content

string

required

Text content to write. Must not exceed 10 MB in UTF-8 encoded size; larger payloads return null without opening the dialog.

Returns: Promise<string | null> — the absolute file path written, or null if the user cancelled or the content exceeded the size limit.

`exportDiagnostics`

window.desktop.exportDiagnostics(): Promise<string | null>

Builds a diagnostics report and opens the native Save File dialog so the user can store it. The report includes app version, runtime versions (Electron, Chrome, Node.js), window visibility, data file sizes and timestamps, focus state, and a data summary. No sensitive data (API keys, email content, task text) is included. Returns: Promise<string | null> — the absolute path of the saved file, or null if the user cancelled.

App Info

`getAppVersion`

window.desktop.getAppVersion(): Promise<string>

Returns the application version string as defined in package.json (via app.getVersion()). Returns: Promise<string> — e.g. "1.3.0".

`setLaunchAtLogin`

window.desktop.setLaunchAtLogin(enabled: boolean): Promise<boolean>

Adds or removes Cody from the Windows startup programs list via Electron’s app.setLoginItemSettings.

enabled

boolean

required

true to register Cody to start with Windows; false to remove the startup entry.

Returns: Promise<boolean> — false in development builds (where the binary path would point to electron.exe rather than the installed app).

This method always returns false in unpackaged development builds. It only takes effect in a production build installed via the installer.

Focus Mode

Methods for activating, deactivating, and querying Cody’s Focus and Do Not Disturb modes.

`setFocus`

window.desktop.setFocus(mode: FocusMode | null, minutes: number): Promise<boolean>

Activates a focus session for the given duration, or deactivates the current session when mode is null.

mode

FocusMode | null

required

The focus mode to activate — 'focus' or 'dnd' — or null to deactivate. See FocusMode.

minutes

number

required

Duration in minutes. Clamped to the range 1–480. Ignored when mode is null.

Returns: Promise<boolean>

Focus vs DND behaviour

Mode	Non-meeting reminders	Meeting reminders	Ad-hoc notifications
`focus`	Suppressed	Delivered	Delivered
`dnd`	Suppressed	Suppressed	Suppressed

When focus ends, a summary notification shows how many notifications were suppressed while the session was active.

`getFocus`

window.desktop.getFocus(): Promise<FocusState | null>

Returns the current focus state. Returns: Promise<FocusState | null> — a FocusState object when a session is active, or null when no focus session is running.

Event Subscriptions

These methods register listeners for events broadcast from the main process. Each returns an unsubscribe function — call it to remove the listener and avoid memory leaks.

`onShortcut`

window.desktop.onShortcut(callback: (action: string) => void): () => void

Fires whenever the user triggers a registered global keyboard shortcut that targets the renderer. The action string identifies the shortcut:

Action	Shortcut	Description
`"new-task"`	`Win+Shift+T`	Quick-add a new task
`"sync"`	`Win+Shift+S`	Trigger an Outlook sync

callback

(action: string) => void

required

Called with the shortcut action string each time a hotkey fires.

Returns: () => void — call to unsubscribe.

const unsubscribe = window.desktop.onShortcut((action) => {
  console.log('Shortcut triggered:', action)
})

// Later, to remove the listener:
unsubscribe()

`onFocusChanged`

window.desktop.onFocusChanged(callback: (state: FocusState | null) => void): () => void

Fires whenever the focus state changes — either because a new session started, or because one ended (naturally via the timer, or manually via setFocus(null, 0)).

callback

(state: FocusState | null) => void

required

Called with the new FocusState, or null when focus ends.

Returns: () => void — call to unsubscribe.

const unsubscribe = window.desktop.onFocusChanged((state) => {
  if (state) {
    console.log(`Focus active: ${state.mode} until ${state.until}`)
  } else {
    console.log('Focus ended')
  }
})

// Later, to remove the listener:
unsubscribe()

`onPetUpdate`

window.desktop.onPetUpdate(callback: (payload: PetUpdate) => void): () => void

Fires in the pet window when the assistant window sends a PetUpdate via petUpdate(). Use this in the pet renderer to react to mood changes and celebration triggers.

callback

(payload: PetUpdate) => void

required

Called with the PetUpdate payload each time the assistant pushes an update.

Returns: () => void — call to unsubscribe.

const unsubscribe = window.desktop.onPetUpdate((payload) => {
  if (payload.type === 'state') {
    console.log(`Pet mood: ${payload.mood}, urgent tasks: ${payload.urgent}`)
  } else if (payload.type === 'celebrate') {
    console.log('Celebration triggered!')
  }
})

// Later, to remove the listener:
unsubscribe()

API & Types

Legal

window.desktop API Reference for Cody Renderer

Data

`loadData`

`saveData`

Notifications & Reminders

`notify`

`scheduleReminder`

`cancelReminder`

Window Control

`openAssistant`

`showPet`

`minimizeWindow`

`toggleMaximizeWindow`

`closeWindow`

`openExternal`

Pet Control

`showPetMenu`

`startPetDrag`

`movePetDrag`

`endPetDrag`

`petUpdate`

Outlook Sync

`syncOutlookClassic`

File Operations

`exportFile`

`exportDiagnostics`

App Info

`getAppVersion`

`setLaunchAtLogin`

Focus Mode

`setFocus`

`getFocus`

Event Subscriptions

`onShortcut`

`onFocusChanged`

`onPetUpdate`

Build docs developers (and LLMs) love

API & Types

Legal

Documentation Index

​Data

​loadData

​saveData

​Notifications & Reminders

​notify

​scheduleReminder

​cancelReminder

​Window Control

​openAssistant

​showPet

​minimizeWindow

​toggleMaximizeWindow

​closeWindow

​openExternal

​Pet Control

​showPetMenu

​startPetDrag

​movePetDrag

​endPetDrag

​petUpdate

​Outlook Sync

​syncOutlookClassic

​File Operations

​exportFile

​exportDiagnostics

​App Info

​getAppVersion

​setLaunchAtLogin

​Focus Mode

​setFocus

​getFocus

​Event Subscriptions

​onShortcut

​onFocusChanged

​onPetUpdate

Build docs developers (and LLMs) love

Data

`loadData`

`saveData`

Notifications & Reminders

`notify`

`scheduleReminder`

`cancelReminder`

Window Control

`openAssistant`

`showPet`

`minimizeWindow`

`toggleMaximizeWindow`

`closeWindow`

`openExternal`

Pet Control

`showPetMenu`

`startPetDrag`

`movePetDrag`

`endPetDrag`

`petUpdate`

Outlook Sync

`syncOutlookClassic`

File Operations

`exportFile`

`exportDiagnostics`

App Info

`getAppVersion`

`setLaunchAtLogin`

Focus Mode

`setFocus`

`getFocus`

Event Subscriptions

`onShortcut`

`onFocusChanged`

`onPetUpdate`