Islands sit still and wait for you to visit. A buoy floats, stays quiet, and lights
up only when something is happening on the water. Buoy turns the centre of your top
bar into exactly that: a small black pill that grows when music plays, a file copies,
a charger connects or a coding agent asks for permission — and shrinks back the
moment it's over. You never open a buoy; there is nothing inside. Glance at it and
you know whether something is up. Come closer, and hover, to read what it is. Click,
and you look at the water under it: a single home panel with what's going on, no
assistant to talk to, no setup. Just a mark on the surface telling you what's
happening underneath.
What's in 0.1
- In the pill: music from any player, file copies and browser downloads, volume,
brightness and Caps Lock, notifications, and your Claude Code sessions — permission
prompts answered right from the pill.
- When nothing is going on: the next event, the weather or the time of day, whichever
matters most.
- Home (click the pill): what you missed, what's running, Now playing, the weather and
the rest of today; tabs for media, notifications, transfers and the calendar.
- The top bar: the app and the system menu on rounded backgrounds that follow your
wallpaper, and rounded corners on maximized windows.
Everything in it: release notes.
Requirements
- GNOME Shell 50 — tested on Ubuntu 26.04. Older or newer Shells are refused by the
installer (
--force tries anyway).
- Nothing else to install: Buoy is a plain GNOME Shell extension, with no daemon and no
background program.
Install
From extensions.gnome.org
Buoy has been submitted to extensions.gnome.org and is
waiting for review. Its page, extensions.gnome.org/extension/11684/buoy, opens to
everyone once it is accepted; then it installs from there or from the Extensions app, with
updates from there too. Until then, use one of the ways below.
With one command
curl -fsSL https://murilegus.dev/buoy/install.sh | bash
It downloads the latest release from GitHub and installs it for your user only — no sudo,
nothing outside ~/.local/share/gnome-shell/extensions and GNOME's settings. Then log
out and back in: GNOME on Wayland loads new extensions at login.
The script is install.sh in this repository; read it first if you like, or
run it with --help. A given version: … | bash -s -- --version 0.1.
From a zip
Download [email protected] from the
latest release, then:
gnome-extensions install --force [email protected]
gnome-extensions enable buoy@murilegus
and log out and back in. (./install.sh --zip [email protected] does the
same and checks your GNOME version.)
From source
git clone https://github.com/murilegus/buoy.git
cd buoy
./install.sh --from-source
It builds the zip with gnome-extensions pack and installs it. To work on Buoy instead, see
CONTRIBUTING.md.
Update
curl -fsSL https://murilegus.dev/buoy/install.sh | bash -s -- --update
It installs the latest release only if it is newer than yours, then asks you to log out and
back in. Bu tells you when a newer release is out, with this command ready to copy. Once
Buoy is on extensions.gnome.org, the Extensions app keeps it up to date — the same
extension, so nothing to reinstall.
First run
Bu says hello in the pill the first time and walks you through the basics: hover the pill
to read more, click it for Home, scroll on it when idle to flip through what it can show.
After an update, Bu tells you what's new — once.
Settings
Click the pill, then ⚙ in Home — or run gnome-extensions prefs buoy@murilegus.
- Island — what the pill shows when nothing is going on, and how it behaves.
- Modules — turn each part on or off (music, transfers, notifications, Claude Code…)
and tune it.
- Apps — per-app tweaks: an app's icon, name, priority or what it shows.
- Panel — the left and right clusters of the top bar.
- Windows — maximized windows under the top bar.
- About — the version, Bu, links, and "Support Buoy" when donations are set.
Claude Code
Buoy shows each Claude Code session in the pill — what it is doing and for how long — and
lets you answer its permission prompts (Deny · Allow · Always) from the pill or the
keyboard.
Turn it on in Settings → Modules → Claude Code → Show my Claude Code sessions. That
adds Buoy's hooks to ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json),
keeps everything else in the file, and saves the old one as settings.json.bak. Turning
it off removes exactly Buoy's hooks. Running sessions pick the change up by themselves.
If Buoy is off or removed, the hooks do nothing and Claude Code carries on as without it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
