Better Duck User Manual

Getting started

System requirements

A Mac with Apple silicon (M-series) running macOS 14 or later. Intel Macs are not supported.

Installing

1. On the website, click "Download free" to get BetterDuck.dmg.
2. Open the DMG and drag Better Duck into your Applications folder.
3. Open Better Duck from Applications. It's notarized by Apple, so it opens like any other app.

The first time it opens, Better Duck copies the apps currently pinned in your native Dock, so the order you're used to is still there.

First launch: the tutorial

After launch a tutorial pops up and walks you through the water dock, permissions, how to organize things, the aquarium, the music card and a few power tips. You can click "Skip" and see it again any time from the 🦆 icon in the menu bar → "Open tutorial".

Grant two permissions (recommended)

The basics need no permissions at all. The two below are extras: grant them to get the matching features, and everything else works fine without them:

You can request them with one click in the tutorial, or under "Settings → General → Permissions". After granting Screen Recording you need to quit and reopen Better Duck before it takes effect; that's a macOS limitation. For the full details, see Permissions.

Let Better Duck take over: hide the native Dock

Menu bar 🦆 → "Hide the native Dock…". Once you confirm, the system Dock is set to auto-hide with a very long delay, so it almost never pops up even when you move to the bottom of the screen, and the water takes its place.

To bring it back, choose menu bar 🦆 → "Restore the native Dock". The same two buttons are also in Settings under "General → Native Dock".

The 🦆 icon in the menu bar

Everything starts here: Pomodoro, Settings…, Open tutorial, License…, Check for Updates…, Hide/Restore the native Dock, Launch at login, and Quit Better Duck.

Free, trial and Pro

The rule is simple: everything the native Dock can do is in the free tier, plus the water and the duck. What the native Dock can't do is Pro.

14-day full trial

The 14-day trial starts as soon as you install. Every Pro feature works, and no credit card is needed. When it ends you drop back to the free tier automatically: no charge, the app isn't locked, the Pro features are simply tucked away. Pro items in Settings then show a PRO tag and an "Unlock Pro" button.

Buying and activating

1. In the pricing section of the website, click "Get Pro". After checkout, your license key arrives by email.
2. Menu bar 🦆 → "License…", paste the key and click "Activate".

One key works on 2 Macs. Activation needs an internet connection; after that it keeps working offline for up to 14 days. Beyond that, Pro is tucked away until you reconnect and it verifies again.

New Mac or reinstalling

On the old Mac, open "License…" and click "Deactivate (before switching Macs or reinstalling)", then activate on the new Mac. If you no longer have the old Mac, sign in at app.lemonsqueezy.com/my-orders to deactivate the old device yourself.

The water dock

Icons float on the water at the bottom of the screen, gently bobbing with the waves. As the pointer glides past, icons grow larger and the water ripples; neighboring icons get pushed by the waves too, then settle back into place once the water calms.

Clicking

• Click an app that isn't running: it opens, with a splash on the water.
• Click a running app: it switches to that app. If the app is running but has no windows (say, Activity Monitor after you closed its window), its main window opens again, just like the native Dock.
• With Pro and Accessibility permission, clicking an app uses the window thumbnail picker instead: it brings forward only the window you want.

What's on the water

• Running indicators: open apps have a small dot beneath them.
• Automatic divider: pinned apps on the left, apps that are open but not pinned on the right.
• Unread badges Accessibility: the red numbers on apps like Mail and Messages. They still show after the native Dock is hidden. You can turn them off under "Settings → Dock → Icons".
• Calendar icon: shows today's date, just like the native one.
• App launcher: on macOS 26, clicking it opens the system's app launcher.
• Downloads tray, Screenshot tray: see Downloads tray and Screenshot tray.
• Trash: click to open it in Finder; right-click for "Empty Trash…" (it asks first, and emptied items can't be recovered).
• Water companion: the duck (or the swim-ring girl) floats at the end of the dock; see Water companion.

When there are too many apps to fit in one row, icons and spacing shrink proportionally, just like the native Dock.

Click-through

Only the icons and the companion catch the mouse. The water and the gaps between icons don't block anything: clicks go straight through to the window behind.

Organize your dock

Reordering, pinning and unpinning

• Hold an icon and drag it left or right; let go to drop it in its new spot.
• Drag a running app to the left of the automatic divider = pin it.
• Drag a pinned app to the right of the automatic divider = unpin it (while the app is still open it stays on the right; once it quits, it disappears).
• Right-clicking an icon also gives you "Pin to Dock" and "Unpin from Dock".

Dragging things in from outside

Removing

Hold ⌥, drag a pinned item up out of the water and let go: plop, it's gone. You can also right-click → "Unpin from Dock" (for the Trash and the Downloads tray it's "Remove from Dock").

Custom dividers

To group your apps, right-click an icon → "Add a divider to the left". Dividers can be dragged to new positions; when you no longer want one, right-click → "Remove divider", or drag it to the right of the automatic divider.

Right-click menu

Right-clicking an app icon shows these items (depending on the situation):

Appearance, position and multiple displays

Size, spacing and water level

"Settings → Dock → Appearance" has three sliders: "Icon size" (20–72), "Icon spacing" (2–28) and "Water level" (30–80). The dock changes live as you drag them.

Auto-hide

"Auto-hide", in the same section, has three options:

• Off: the water is always there.
• Leave a waterline: normally it sinks down to a thin waterline.
• Hide completely: normally you don't see it at all.

Move the pointer to the very bottom edge of the screen and the water rises back; move away and it sinks. It won't hide while you're dragging, or while the Downloads tray or window previews are open.

Water on every display PRO

"Settings → Dock → Appearance → Show the dock on all displays". Each display gets its own independent water surface, and the pinned list stays in sync instantly. When it's off, or on the free tier, the dock appears only on the main display (the one with the menu bar).

Windows avoid the dock Accessibility

The native Dock makes maximized windows stay clear of it automatically. Third-party docks don't get that system treatment, so Better Duck shortens the windows for you. Choose under "Settings → Dock → Windows":

• Off: leaves windows alone.
• Slight overlap (default): the window's bottom edge stops just above the water, so raised icons can sit over the window edge, which looks more blended.
• Fully clear: even the icons won't cover the window.

Double-click the title bar of a shortened window to restore its original size. Truly full-screen apps are unaffected; some fixed-size windows can't be shortened, and Better Duck leaves those alone.

Downloads tray

Click the Downloads icon on the dock: the water rises and the 12 most recent files in your Downloads folder float up in a second row. Images, videos and PDFs show thumbnails.

• Click a file: opens it in its default app and closes the tray.
• Drag a file out: drag it to another window or the Desktop; what you drop is a copy.
• The rightmost tile: opens the whole Downloads folder in Finder.
• Close: click the Downloads icon again, or click anywhere else on the water.

Related settings are under "Settings → Dock → Downloads & Screenshot trays":

• Open the Downloads tray next to its icon: by default files fan out from the center of the screen; on ultra-wide displays you can have them open near the Downloads icon instead.
• Tilt photos slightly in the trays: photos sit a little askew, like they were scattered on a table (up to 5°). Turn it off to keep them all straight.

Screenshot tray PRO

Screenshots no longer pile up on your Desktop; they drop straight into the dock's water. It works like the Downloads tray: click the Screenshot tray icon, the water rises, and your recent screenshots float up in a second row.

First use: take over where screenshots are saved?

The first time you click the Screenshot tray, it asks: "Send screenshots straight to the Screenshot tray?"

• Yes, take over screenshots: from then on, screenshots and screen recordings are saved to Better Duck's own folder (~/Library/Application Support/Better Duck/Screenshots) and no longer appear on the Desktop. The floating thumbnail in the bottom-right corner is turned off too, so you don't wait those 5 seconds for the file to save.
• Not now: your system settings stay exactly as they are, and the Screenshot tray only shows screenshots on the Desktop.

You can change your mind later under "Settings → Dock → Downloads & Screenshot trays → Screenshot tray: screenshots go to the dock, not the Desktop". Turning the feature off or quitting Better Duck restores your system screenshot settings; they're taken over again the next time it launches.

Using it

A new screenshot flies down from above and splashes into the water, and a number badge appears on the Screenshot tray icon. You can turn the animation off in Settings ("New screenshots splash into the water"). Screen recording thumbnails have a play button on top.

How many are kept?

The Screenshot tray shows the latest 12 at a time. By default the folder keeps the latest 100; you can change that to 50, 300 or "Don't clean up". The oldest screenshots beyond that move to the Trash, where you can still recover them. Ones you drag out or save to the Desktop aren't affected.

When the trial ends

Your system screenshot settings are restored, and any screenshots left in the folder are moved back to their original location (usually the Desktop), so they don't get stuck somewhere you can't see.

Window thumbnail picker PRO Accessibility

One click on the native Dock calls up every window of an app at once. Better Duck lets you pick just one.

What happens when you click an app icon

What you can do in the preview row

• Each preview has red, yellow and green buttons in its top-left corner that light up when you hover: red = close that window, yellow = minimize, green = zoom.
• Windows minimized to the Dock are labeled "Minimized"; click one to restore it and bring it forward.
• Click the same icon again, or anywhere else on the screen, to close the preview row.

Related options (Settings → Dock → Windows)

• Click a multi-window app to expand window previews: the main switch. When it's off, clicking an icon behaves natively.
• Hover an icon to expand window previews: no click needed; rest the pointer on an icon and the previews expand, move away and they close. "Show previews even for a single window" below it lets apps with only one window expand too. Off by default.
• Enlarge a window when you hover its preview Screen Recording: rest the pointer on a preview and that window is shown enlarged above it, so you can see its contents before deciding.

We also recommend turning on "Minimize windows into the app icon (recommended)" under "Settings → General → Native Dock": minimized windows won't take up slots in the native Dock, and to get one back you click that app's icon in Better Duck and pick it from the preview row.

Without permissions

Without "Screen Recording": previews become cards showing only the window title, and everything else works as usual. Without "Accessibility": clicking an icon behaves natively and brings the whole app forward.

⌥Tab window switcher PRO Accessibility

⌘Tab can only switch between apps; ⌥Tab switches one window at a time. It raises only the window you pick, and the app's other windows stay where they are.

• Hold ⌥ and keep pressing Tab to move forward.
• ⌥` moves backward.
• You can also just click one with the mouse.
• Release ⌥ to switch.

Thumbnails need the "Screen Recording" permission. For now it only lists windows on the current desktop that aren't minimized. The system's ⌘Tab is completely unaffected. The switch is under "Settings → Shortcuts → Window switcher".

Clipboard ⌃⌥V PRO

Anywhere you can type, press ⌃⌥V and the text and images you copied recently appear right next to your text cursor. Pick one and it's pasted straight in.

Keyboard controls

Pressing any other key while the panel is open closes it and sends your keypress through as usual, so you can keep typing without losing a character. You can also click with the mouse.

Pinning and clearing

• Each row ends with a 📌 (pin) button and a delete button. Pinned items are kept even after you quit the app, with no limit on how many.
• Up to 25 unpinned items are kept, and they're cleared when you quit Better Duck.
• "Clear all" in the title bar only clears unpinned items.

Privacy

Anything a password manager marks as private or transient is never saved. Text is stored along with its formatting (RTF, HTML), so styles survive when you paste it back; single items over 20 MB aren't saved.

Pasting directly needs the "Accessibility" permission. Without it, picking an item only copies it, and you press ⌘V yourself. If the panel says "macOS is blocking clipboard access", go to "System Settings → Privacy & Security" and allow Better Duck to read the clipboard. The switch is under "Settings → Shortcuts → Clipboard".

Music card PRO

Rest the pointer on the Spotify or Apple Music icon and a Now Playing card floats up: album art, track name, artist, album, ⏮ ⏯ ⏭, and ♥ to save.

The first time you use it, macOS asks whether Better Duck may control Music/Spotify. Click Allow (this is the "Automation" permission).

♥ Save

• Apple Music: press ♥ to add the song to your favorites, no extra setup.
• Spotify: Now Playing info and playback controls work with no setup; only ♥ "Save to Liked Songs" needs your own Spotify Client ID.

Setting up Spotify ♥ (Settings → Music → Spotify ♥ Save):

1. Click "Open Spotify Dashboard", sign in and create an app (any name will do).
2. Set the Redirect URI to betterduck://spotify-callback (you can click "Copy Redirect URI").
3. In that app's Users and Access, add your own Spotify account.
4. Copy the Client ID, paste it into the field in Better Duck, click "Connect Spotify…" and approve access in your browser.

Two extras while music plays

• Replace the music app's icon with the album cover: the Spotify/Music icon on the dock turns into the cover of what's playing.
• Use the album cover as the wallpaper: your wallpaper changes to the cover. Turning this option off or quitting Better Duck switches back to your original wallpaper. It isn't applied while you use one of the system's dynamic, aerial or solid-color wallpapers, because those have no image file to restore.

Also, your water companion puts on headphones while music plays.

Aquarium PRO

When your Mac sits idle for a while, the water rises from the bottom of the screen and stops just short of the top, turning your whole desktop into an aquarium. Move the mouse or press any key and the water drains away.

Two looks

• See-through mode Screen Recording: you see your own desktop through the water, refracting and swaying.
• Deep-water scene: without Screen Recording permission, or with see-through mode off, you get deep blue water with bubbles and light rays instead.

Underwater, the icons drift free of their spots, and the companion swims back and forth on the surface. You can turn on "Show a digital clock underwater" to display the time and date.

Settings (Settings → Aquarium)

• Enable aquarium mode
• Start after so many minutes idle: 1–30 minutes, 5 by default
• See-through mode, underwater clock
• Don't start on battery
• Preview now: floods the screen right away so you can see it

When it stays out of your way

• It won't start while a video or presentation is playing (an app is keeping the display awake).
• It won't start when the screen is locked.
• It never keeps your display from sleeping; the system sleeps when it should.
• The mouse movement or keypress that wakes it is swallowed, so it won't accidentally hit the app behind.

Water companion and Pomodoro

Water companion

A yellow duck floats at the end of the dock, half in the water. It sways with the waves, blinks now and then, and paddles from time to time, making little ripples. Click it and it hops up and gives you a "Quack!". It puts on headphones while music plays.

"Settings → General → Water companion":

• Character: None / Duck / Girl PRO. Choose "None" to hide it.
• Size: remembered separately for each character.
• Pin to the right edge: even when you have few icons, the companion stays at the far right of the screen.

The dock and the aquarium share the same companion.

Pomodoro

Menu bar 🦆 → Pomodoro: Start focus, Pause, Resume, Skip, Reset. During a focus session the countdown shows in the menu bar; when time's up, the companion hops up on the dock to remind you to take a break or get back to focusing.

"Settings → Pomodoro":

• Durations: focus 1–90 min, short break 1–30 min, long break 1–60 min, with a long break after every 2–8 focus sessions.
• When time's up: companion animation (opens its mouth, hops, speech bubble), system notification and sound, each switchable on its own.
• Show the countdown in the menu bar.
• Start the next segment automatically: when off, each segment waits for you to press Start.

Water feel and power saving

Water feel PRO

"Settings → Water feel". The free tier uses a tuned default feel; with Pro you can adjust it yourself:

• Water tilts and sloshes as you tilt the laptop: tilt or nudge your laptop and the water flows downhill. Comes with a "Tilt strength" slider. Apple silicon laptops only; desktop Macs have no motion sensor and show it as unavailable.
• Reflections: Off / Soft (default, blurred like real water) / Sharp (full detail, but a busier look).
• Icons interrupt the highlight line: the bright line on the water passes behind the icons; turn it off and it runs straight through.
• Reset the feel to defaults: if you've tweaked things into a mess, one click takes you back to the factory settings.

Power saving

Better Duck is designed to sit on your screen all day: drawing is composited on the GPU, the frame rate drops automatically when the water is calm, and drawing stops when a full-screen app covers it. To save even more, turn on "Settings → Dock → Power saving → Freeze the water when idle": after a few seconds without touching the dock, once the water settles it stops redrawing entirely, and it comes back the moment you move the mouse. It's most noticeable with multiple displays or on battery.

Permissions

Permissions are a bonus, not a barrier. Whichever one is missing, only the part that uses it falls back to a simpler approach; everything else works as usual. Everything on screen stays on your Mac: nothing is uploaded or analyzed.

You can check permission status under "Settings → General → Permissions". It refreshes every two seconds, and any permission you haven't granted has "Request" and "System Settings" buttons next to it.

Settings at a glance

Menu bar 🦆 → "Settings…", or right-click any icon → "Settings…". There are seven tabs on the left:

Troubleshooting

Uninstalling

1. Restore the native Dock first: menu bar 🦆 → "Restore the native Dock". Simply quitting Better Duck doesn't bring the native Dock back; skip this step and you'll be without a Dock for a while.
2. If you used the Screenshot tray, drag out the screenshots you want to keep, or use "Save to Desktop".
3. Menu bar 🦆 → "Quit Better Duck". Your screenshot settings and wallpaper are restored at this point.
4. Move Better Duck from your Applications folder to the Trash.
5. (Optional) Delete ~/Library/Application Support/Better Duck, which holds your screenshots and pinned Clipboard items.

If you bought Pro and will use it on another Mac later, remember to open "License…" and click "Deactivate" before deleting the app.