Concepts

A short tour of the moving pieces. Skim this once and the rest of the docs will land faster.

The bar

ApexDock renders a single horizontal panel at the bottom of every display you've enabled (Settings → Bar → Show Bar on All Displays). It floats above your normal windows but never steals focus when you click it, and it sits below screenshot, screensaver, and Spotlight overlays.

Layout, left to right:

[Start] [Divider] [Pinned apps] [│] [Running apps] [Spacer] [Agents] [System tray]

• Start button — opens the command palette (same as ⌘K).
• Pinned apps — apps you've explicitly pinned. Drag to reorder.
• Section separator — the little vertical pill. Visually divides pinned from running.
• Running apps — non-pinned apps that have a window open right now.
• Agents — live tiles for Claude Code / Codex / custom Hook API sessions when Settings → Agents is enabled.
• System tray — the right-hand cluster: workspaces, folder shortcuts, Wi-Fi, volume, now playing, battery, stats, clock + calendar, focus, notes, bell.

External widgets can target any of these zones (tray, pinned, unpinned, agent, leading, trailing) — see Widget locations.

On narrow or vertical displays the bar collapses overflow apps, agents, and tray items into hover popovers instead of squishing the zones together — see Multi-Monitor → Compact displays.

Popovers

Most tray items open a hover popover with detail: the calendar opens a month grid, battery shows charge state and ETA, CPU stats show per-core usage, agents show transcript and pending tools.

The popover model is shared across the bar, so opening one popover dismisses any other tray popover — no stacking, no "must mouse off everything to switch". A short delay gates open and close to avoid flicker as you sweep across icons.

Workspaces

A workspace is a saved bar configuration:

• A pinned-apps subset (per-workspace pin list)
• An accent color
• A folder shortcut set
• A focus-mode allowlist
• An optional default folder URL

Workspaces are useful when context-switching between roles (Work / Personal / Writing). Activate one and the bar collapses to that subset; deactivate to return to your global pinned apps.

You can switch via the workspaces tray icon, the command palette ("switch to Work"), apexdock workspace switch Work, AppleScript, or Shortcuts.app. See Workspaces feature page.

Focus mode

Focus is a Pomodoro-style timer that dims non-allowlisted apps to ~35% opacity for the duration of a session. The allowlist is workspace-scoped — each workspace has its own list, so "Writing focus" can dim Slack while "Work focus" doesn't.

When the timer ends, all apps return to full brightness and the system Glass sound plays (configurable).

Hotkeys

ApexDock owns a small set of global hotkeys, all configurable:

See Hotkeys settings for the full list and the rebinding flow.

Agents

When Settings → Agents is on, the bar surfaces live tiles for Claude Code, Codex, and custom Hook API sessions. Built-in providers can come from on-disk JSONL streams or hooks; custom providers render from the Hook API. Each tile shows current phase (thinking / tool running / idle), pending tools, and a transcript preview in its hover popover.

A pending approval shakes the tile orange. Click Approve or Decline in the popover; the decision rounds back to the agent over the same socket.

Three permission tiers

ApexDock asks for permissions only when the related feature is used:

1. Bar essentials — Accessibility (window resizing, hotkeys), Automation (opening Notification Center), Location (reading the Wi-Fi network name).
2. Assistant — Microphone, Screen Recording, Speech Recognition.
3. Calendar — read-only access for the next-meeting badge and agenda.

You can grant them all up-front in Settings → Permissions or wait until first use.

Configuration locations

Sockets live in a 700-mode parent dir with 600 permissions, so only your user can read or write them.