Skip to content
CoolDock Docs
← Back to site

AI Assistant#

CoolDock can connect to an AI assistant running on your Mac so it can inspect your Dock, recommend a layout, and, when you allow it, apply changes for you. Everything happens locally through a bundled helper; CoolDock does not send your configuration to a cloud service of its own.

Open Settings → AI Assistant to set it up.

Enable the connection#

Turn on Enable AI connection. The connection is available only to apps running under your macOS user account, and it starts read-only: an assistant can read your profiles, apps, widgets, and settings but cannot change them.

The status line shows Ready for connections · read-only, editing allowed, or YOLO mode, or Connection off while the switch is off. Connection unavailable means the switch is on but the helper could not start; choose Retry Connection.

Allow changes#

Turn on Allow changes to let assistants edit Dock content and settings and operate supported controls. Consequential actions, such as removing widgets or profiles, closing windows, restoring backups, reading clipboard text, or taking screenshots, show a separate CoolDock approval sheet for that exact operation. Choose Allow for This Session there to approve the rest of that chat.

Turn Allow changes off at any time to return the connection to read-only. Account connections and macOS permissions still use CoolDock's own setup panels; an assistant cannot grant them.

YOLO mode: skip approval prompts runs consequential actions without asking. macOS permission prompts still appear. Leave it off unless you are comfortable with the assistant acting on its own.

Install in your AI app#

Under Install in your AI app, pick the client:

  • Claude Desktop, Cursor, and VS Code support Install for, which adds CoolDock to that client's configuration once the connection is enabled. Copy Configuration copies the same entry for manual editing. Use Remove to take it out again; other servers and settings are preserved.
  • Codex and Claude Code show a command to Copy Command and run in Terminal, with a matching Copy Removal Command.

Restart the client afterwards so it loads CoolDock's tools. Keep CoolDock in a stable location such as Applications; if you move the app, install the connection again. Disabling the connection stops access immediately.

Teach your assistant CoolDock#

Install or Update Skill installs the bundled cooldock-assistant skill for Codex or Claude Code. It walks the assistant through connecting, choosing a layout, and setting up profiles, apps, widgets, style, and behavior, and it works before the connection is enabled.

After installing, start a new chat and use Copy Setup Prompt, or invoke $cooldock-assistant in Codex or /cooldock-assistant in Claude Code. Show Bundled Skill reveals the copy inside the app, and Remove Installed Skill removes only an unchanged skill that CoolDock installed. Other MCP clients can read the same workflow through CoolDock's prompts and resources.

Try it#

The Try it group copies starter prompts you can paste into your AI app:

  • Recommend a layout asks for a proposal before anything changes.
  • Create a work profile builds a new profile from the apps on your Mac.
  • Organize my dock reviews the active profile and suggests improvements.

Assistants can also pick a wallpaper for you by mood, style, color, time of day, season, or weather when the Wallpaper widget is in your Dock. The catalog is searched on your Mac without a network request.

What assistants can reach#

CoolDock advertises its tools in focused groups, and an assistant starts by reading status and picking the group that fits the request:

  • dock — profiles, global Dock settings, and layout
  • widgets — native widget discovery, configuration, and order
  • apps — installed apps, launchers, and the Applications widget
  • system — preferences, shortcuts, displays, permissions, and native actions
  • runtime — active timers, tasks, media, and audio
  • content — Bookmarks, File Shelf, clipboard, and saved colors
  • windows — window discovery, focus, snap, close, and pin
  • providers — Notes, Mail, Calendar, Reminders, and contacts
  • home — configured Home controls
  • files_media — Trash, screenshots, and voice memos
  • wallpapers — wallpaper search and applying desktop wallpapers
  • recovery — checkpoints, backups, and profile packages

Read-only tools work as soon as the connection is enabled; everything that changes the Dock requires Allow changes.

Undo an AI change#

Under Recent AI changes, choose Undo Last Dock Configuration Change to restore the previous profiles, widget configuration, and Dock settings when no conflicting edit has happened since. Assistants can also create private local backups and profile packages. Undo does not restore removed runtime data, account connections, or other app preferences.

Privacy#

  • The connection is local to this Mac and only reachable by apps under your account.
  • Read-only is the default; nothing changes until you turn on Allow changes.
  • The local activity log records tool names and outcomes without arguments, credentials, or widget content.
  • Credentials and macOS permission grants are entered in CoolDock, never through the assistant.

Troubleshooting#

  • No tools appear — confirm Enable AI connection is on and CoolDock is running, then restart or reconnect the client.
  • Reads work but changes fail — turn on Allow changes. An assistant cannot enable its own access.
  • The app was moved — install the connection again so the helper path is current.
  • Unclear failure — choose Check Connection for a diagnostic, or Show Connection Files to open the helper's folder.