The Settings window opens via the menu bar icon's right-click → Settings, the command palette ("settings"), or apexdock settings open <tab>. It has 18 tabs:
| Tab | Covers |
|---|---|
| License | Activation, deactivation, refresh, device list |
| Bar | Layout, behavior, window peek, tray icons, now playing, folders, calendar |
| Themes | Bar height, background material, tint + opacity, theme presets |
| Permissions | Grant buttons and live status for every macOS permission ApexDock uses |
| Agents | Agent activity tray, providers, source modes, hook API |
| Bar Bud | Companion picker, size, reduced-motion, custom pet folder |
| Assistant | Push-to-talk hotkey, API keys, STT/LLM/TTS providers, Computer Use opt-in |
| Workspaces | Create / rename / delete / reorder |
| Focus | Pomodoro timer, allowlist editor, completion sound |
| Stats | CPU / RAM / Network toggles + intervals |
| Clipboard | History limit, hotkey, AI suggestions |
| Notes | Quick Notes panel, hotkey, preview default, storage path |
| Hotkeys | Read-only summary of every registered hotkey |
| Palette | Command palette enable, AI routing, hotkey display |
| Integrations | CLI installer, YAML widgets file |
| Updates | Sparkle channel, automatic check / download toggles, manual check |
| About | Version, tips, copyright |
| Feedback | In-app form for sending feedback to the ApexDock team |
This page enumerates every control. For deep-dive feature docs, follow the linked feature pages.
Bar
The Bar tab is the largest. It groups related settings into sections.
Layout
| Setting | UserDefaults key | Notes |
|---|---|---|
| Hide macOS Dock | apexdock.dock.suppressorEnabled | Parks the macOS Dock with auto-hide + near-infinite delay. Restores on quit. |
| Adjust Windows Around Bar | apexdock.windowMinder.enabled | Resizes intruding windows. Requires Accessibility. |
| Show Bar on All Displays | apexdock.appearance.multiMonitorEnabled | Independent bar per display. See Multi-Monitor. |
Behavior
| Setting | UserDefaults key | Notes |
|---|---|---|
| Click Frontmost App Icon | apexdock.appearance.appClickAction | hide / cycleWindows / doNothing. |
Window Peek
| Setting | UserDefaults key | Notes |
|---|---|---|
| Stack Multi-Window Icons | apexdock.windowPeek.stackingEnabled | Visual layering on multi-window icons. |
| Hover to Preview Windows | apexdock.windowPeek.peekEnabled | Window list popover on hover. |
| Show Live Thumbnails | apexdock.windowPeek.useThumbnails | Live captures. Requires Screen Recording. |
See Window Peek.
Tray Icons
Independent toggles for the default tray cells:
| Setting | UserDefaults key |
|---|---|
| Wi-Fi | apexdock.tray.wifiEnabled |
| Volume | apexdock.tray.volumeEnabled |
| Now Playing | apexdock.nowPlaying.enabled |
| Battery | apexdock.tray.batteryEnabled |
| Clock & Calendar | apexdock.tray.clockEnabled |
| Notifications | apexdock.tray.bellEnabled |
Stats, Focus, and Notes have enable toggles in their respective tabs (they're features, not just tray cells).
Now Playing
| Setting | UserDefaults key |
|---|---|
| Show Now Playing in Tray | apexdock.nowPlaying.enabled |
| Preferred Source | apexdock.nowPlaying.preferredSource (system / appleMusic / spotify) |
| Locate Spotify… | Manual file picker — paths stored under apexdock.nowPlaying.spotifyPath |
See Now Playing.
Folder Shortcuts
| Setting | UserDefaults key | Notes |
|---|---|---|
| Label Font Size | apexdock.folderShortcuts.labelFontSize | 6–16pt. |
See Folder Shortcuts.
Calendar Events
Embeds the calendar permission status row + visible-calendars filter. See Calendar.
Themes
Bar height, background material, tint, and theme presets all live here.
Theme Presets
A horizontal row of preset chips. Picking one sets background material, tint, and tint opacity together.
Appearance
| Setting | UserDefaults key |
|---|---|
| Bar Height | apexdock.appearance.height (step 2) |
| Background Material | apexdock.appearance.material (regular / thin / ultraThin / chrome / dark) |
| Tint | apexdock.appearance.tint (named tint or empty for none) |
| Tint Opacity | apexdock.appearance.tintOpacity (0–60%) |
License
| Field | Notes |
|---|---|
| License key | Paste from email; ApexDock validates the signature locally. |
| Activated devices | Up to 3. Each row shows hostname + activation date. Click ✕ to deactivate that device's grant remotely. |
| Refresh | Force-fetches a new grant. Useful after deactivating a stale device. |
Stored in Keychain under the License account. Never written to disk in plain text.
Permissions
One row per macOS permission. Each row shows current status and a one-click grant button. See Permissions.
Agents
Activity Tray
| Setting | UserDefaults key |
|---|---|
| Show Agent Activity | apexdock.agents.enabled |
Providers
Independent toggles for Claude Code and Codex. Custom Hook API providers render whenever the Hook API is enabled. Pi is reserved.
Behavior
| Setting | UserDefaults key |
|---|---|
| Show Transcript Previews | apexdock.agents.showTranscriptPreviews |
| Notify When Approval Pending | apexdock.agents.notifyOnApproval |
| Consolidate Grouped Icons | apexdock.agents.consolidateGroupedIcons (default off — collapses subagents and same-repo sessions to one parent tile) |
| Idle Timeout | apexdock.agents.idleTimeoutMinutes (1–60) |
Open Here (per provider)
Two identically-shaped sections — Claude Code Open Here and Codex Open Here — control the arrow button on agent popovers. The Show Open Here button toggle hides it for that provider; leave the template field blank to use the built-in router (terminal / app focus / tmux pane). Fill in a URL template to override.
| Setting | UserDefaults key |
|---|---|
| Show Open Here button (Claude Code) | apexdock.agents.openHere.claudeCode.enabled |
| Custom opener template (Claude Code) | apexdock.agents.openHere.claudeCode.template |
| Show Open Here button (Codex) | apexdock.agents.openHere.codex.enabled |
| Custom opener template (Codex) | apexdock.agents.openHere.codex.template |
Templates accept percent-encoded placeholders: {threadId}, {sessionId}, {cwd}, {provider}, {originator}, {clientName}. The settings panel shows a live preview and turns red on an unparseable URL. See Agents → Open Here.
Watched Paths
Per-provider list of directories ApexDock reads. Default + custom roots. See Agents.
Hook API
| Setting | UserDefaults key |
|---|---|
| Enable Hook API | apexdock.agents.api.enabled |
| Install Claude Hooks | One-time installer — wires ~/.claude/settings.json |
| Claude Code source | apexdock.agents.api.source.claudeCode (auto / jsonlOnly / hooksOnly) |
| Codex source | apexdock.agents.api.source.codex (same enum) |
Socket: ~/Library/Application Support/ApexDock/api/api.sock. File-drop: <api>/<sessionId>.jsonl.
Bar Bud
| Setting | UserDefaults key |
|---|---|
| Show Bar Bud | apexdock.pet.enabled |
| Bar Bud (picker) | apexdock.pet.selectedPetID |
| Size | apexdock.pet.displaySize |
| Reduced Motion | apexdock.pet.reducedMotion |
The picker lists every Bud discovered in ~/Library/Application Support/ApexDock/pets/ and ${CODEX_HOME}/pets/. Open Bar Bud Folder reveals the app-support folder so you can drop a new pack in. Refresh rescans without restarting.
See Bar Bud.
Assistant
API Keys
Three rows: Anthropic, ElevenLabs, OpenAI. Each shows "•••• stored" when set + Replace / Trash buttons. Stored in Keychain under per-account names. The Codex via ChatGPT provider does not use an API key — it shells out to your local codex CLI login instead.
Speech-to-Text
| Setting | Notes |
|---|---|
| Provider | Whisper / Deepgram / On-device. |
Language Model
| Setting | Notes |
|---|---|
| Provider | Anthropic / OpenAI / Codex via ChatGPT |
| Model | Per-provider list (Claude Opus / Sonnet / Haiku, GPT-5.5 family, or models reported by your local Codex install) |
| Reasoning Effort (Codex only) | Low / Medium / High — defaults to whatever the selected Codex model reports as its default |
Picking Codex via ChatGPT requires the codex CLI installed and signed in with a ChatGPT account. ApexDock loads the available models and reasoning efforts from the codex app-server; voice-mode queries are filtered to image-capable models so screenshots can ride along.
Push-to-Talk Hotkey
Modifier toggles (Control / Option / Shift / Command). Reset returns to ⌃⌥.
Text-to-Speech
| Setting | Notes |
|---|---|
| Provider | System / ElevenLabs |
| Voice (ElevenLabs) | Voice picker fetched from your account |
See Assistant.
Workspaces
Create / rename / delete / reorder rows. Each row exposes:
- Name
- Accent color
- Default folder URL (optional)
- Pinned-apps editor (the sub-editor opens on double-click)
See Workspaces.
Stats
Per-widget toggle + interval slider:
| Widget | Interval range |
|---|---|
| CPU | 0.5s–10s |
| Memory Pressure | 0.5s–10s |
| Network | 0.5s–10s |
See Stats.
Focus
| Setting | UserDefaults key |
|---|---|
| Show Focus Timer | apexdock.focus.enabled |
| Play Sound on Completion | apexdock.focus.completionSoundEnabled |
| Custom Length | apexdock.focus.customMinutes (5–90, step 5) |
| Allowlist | Per-workspace; see Focus |
Clipboard
| Setting | UserDefaults key |
|---|---|
| Enable Clipboard History | apexdock.clipboard.enabled |
| Enable AI Suggestions | apexdock.clipboard.aiEnabled |
| Hotkey | apexdock.clipboard.hotkey.keyCode + .modifiers |
| History Limit | apexdock.clipboard.historyLimit (10–200, step 10) |
Notes
| Setting | UserDefaults key |
|---|---|
| Enable Quick Notes | apexdock.notes.enabled |
| Open in Preview Mode | apexdock.notes.previewByDefault |
| Hotkey | apexdock.notes.hotkey.keyCode + .modifiers |
| Storage | Reveals ~/Library/Application Support/ApexDock/notes.json |
Hotkeys
Read-only registry. As you enable other features, more rows appear.
Palette
| Setting | UserDefaults key |
|---|---|
| Enable Command Palette | apexdock.commandPalette.enabled |
| Use AI Routing | apexdock.commandPalette.aiEnabled |
| Hotkey | Read-only display; override via apexdock.commandPalette.keyCode + .modifiers |
Integrations
| Section | Notes |
|---|---|
| Command-Line Interface | Status row + Install / Uninstall buttons. Symlinks /usr/local/bin/apexdock to the bundled CLI. |
| YAML Widgets | Opens ~/Library/Application Support/ApexDock/widgets/ for one-widget-per-file .yaml / .yml recipes. |
Updates
| Setting | UserDefaults key | Notes |
|---|---|---|
| Update channel | apexdock.update.channel | stable or beta. The appcast URL switches automatically. |
| Automatically check for updates | Sparkle SUEnableAutomaticChecks | Default on. |
| Automatically download updates | Sparkle SUAutomaticallyUpdate | Default on; installs on next quit. |
| Check for updates now | — | One-shot manual check; surfaces the last error inline if a check fails. |
Status row shows current version, last-checked time, and your "updates included until" date. After the window expires, the row turns into a renew prompt that links to apexdock.app/account.
About
Read-only. Version, copyright, three tip rows.
Feedback
In-app form for sending feedback to the ApexDock team. Falls back to a mailto:feedback@apexdock.app link if your default mail client isn't configured. No telemetry or screenshots are attached automatically — you write the body.
Where settings live
| Type | Location |
|---|---|
| Most preferences | defaults read com.gacntsoftware.apexdock apexdock.* |
| API keys | macOS Keychain (Anthropic, OpenAI, ElevenLabs) |
| License grant | macOS Keychain (License) |
| Notes data | ~/Library/Application Support/ApexDock/notes.json |
| Clipboard history | ~/Library/Application Support/ApexDock/clipboard.json |
| YAML widgets | ~/Library/Application Support/ApexDock/widgets/*.yaml and *.yml |
| File-drop widgets | ~/Library/Application Support/ApexDock/widgets/*.json |
| Hooks | ~/Library/Application Support/ApexDock/hooks/*.sh |
| Themes | ~/Library/Application Support/ApexDock/themes/*.json |