DeskBuddy
A floating desktop buddy for macOS. A little character sits on top of your screen;
click it and your to-do list unfolds. Visible across every Space and even over
full-screen apps.
Website: deskbuddy.snghnl.com
Install
curl -fsSL https://deskbuddy.snghnl.com/install.sh | sh
Or download DeskBuddy.dmg
and drag the app to Applications.
Requires macOS 14 (Sonoma) or later. Universal binary (Apple Silicon + Intel).
Why two ways
DeskBuddy is not notarized — that needs a paid Apple Developer account. macOS
quarantines anything a browser downloaded, so opening the .dmg build the first
time takes a detour: launch it, dismiss the warning, then System Settings →
Privacy & Security → Open Anyway. Control-clicking the app no longer works;
Apple removed that bypass in macOS 15.
curl does not set the quarantine flag, so the one-liner installs the very same
build with no warning at all. It is a short, readable script — give it a
look before piping it into a shell.
Already installed the hard way? xattr -dr com.apple.quarantine /Applications/DeskBuddy.app
Updating
DeskBuddy asks GitHub for the latest release once a day, and the buddy speaks up
when it finds one. Settings → Updates shows the installed version and installs
the update in place: it downloads the release zip, matches it against the release's
checksums.txt, swaps the app and relaunches.
Every build carries a different ad-hoc signature, so macOS treats an updated
DeskBuddy as a new app and drops its calendar permission along the way. Reconnect
it in Settings → Integrations afterwards — the app says so when it happens.
Build & Run
./make-app.sh # builds build/DeskBuddy.app (native arch)
./make-app.sh --universal # arm64 + x86_64 (what CI ships)
open build/DeskBuddy.app
./make-dmg.sh --build # universal build, then build/DeskBuddy.dmg
make-dmg.sh lays the disk image window out with
dmgbuild (pip install dmgbuild), which
writes the Finder .DS_Store directly instead of scripting Finder — the only way
that also works on a headless CI runner. Without it you still get a plain,
usable image.
During development you can also just swift run. No Xcode project — plain Swift Package Manager.
Features
- One character, or your own image: the built-in buddy is drawn as a shape rather
than an image, so it stays sharp at any size and inverts with your system appearance —
white with a dark outline in light mode, black with a light outline in dark mode. It
blinks, and a badge shows the number of open to-dos. You can also add any image as your
own character and name it in Settings
- Click → list toggle: click the character to open the to-do panel next to it;
drag the character to move (the list follows)
- Throwing: grab and flick the character — it flies with momentum, bounces off the
screen edges, and lands. Catch it mid-air with a click (can be disabled in Settings)
- Wandering: optionally lets the character stroll around the screen, picking random
spots, walking there, and resting. Pauses while the list is open, while being held,
or while a menu is up
- Global shortcut: register a hotkey in Settings to open the list and start typing
from any app (Carbon hotkey — no Accessibility permission needed)
- To Do / Done / Calendar tabs: completed items move to the Done tab, grouped by day
(Today/Yesterday/…) with completion times. ⌘1/⌘2/⌘3 switch tabs while the list is up
- Calendar tab: a monthly grid with a completion heatmap (busier days shaded darker)
plus dots on days that have calendar events. Tap a date to see that day's events and
completed items together
- Calendar integration (EventKit): reads events from any account connected to macOS
Calendar (Google included) — no OAuth. Today's events get "Now" / "in N min" badges.
Managed from the Integrations section in Settings
- Event alerts (speech bubble): 5/10/15/30 minutes (configurable) before an event
starts, the character raises a speech bubble. It stays until clicked, follows the
character around, and repositions above/below/left/right based on screen space
- Language setting: follow the system language or force Korean/English from Settings.
Strings live next to the code that shows them, in
Sources/<target>/Resources/Localizations/*.yml
(the app's and each plugin's), with a few shared ones in DeskBuddyCore — translation fixes and
new languages are welcome as PRs
- Always on top:
NSPanel at .floating level, visible on all Spaces and over
full-screen apps
- Non-activating: clicking the buddy never steals focus from the app you are using
- Add (Enter), check off, hover-to-delete, drag to reorder
- Tooltips show when each item was added; a detail page holds the title, memo, and timestamps
- Character position and list size persist across restarts
Agent Integration (CLI / URL scheme)
External scripts and agents (Claude Code, background workers, cron jobs) can talk to
DeskBuddy:
以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗
