Skip to content

Installation

Jump to bottom
The Artifex (4r7if3x) edited this page May 12, 2026 · 6 revisions

Installation

Pick the section that matches your operating system and desktop environment. Each target ships a native artifact — there is no universal binary.

macOS

Install from a release (recommended)

Download claudebar-macos-<version>.dmg from the latest release, open it, and drag ClaudeBar into /Applications.

On first launch, ClaudeBar registers itself as a Login Item via SMAppService, so the menu-bar indicator appears automatically every time you sign in. macOS will show its standard "ClaudeBar was added to Login Items" prompt the first time. You can toggle this later from System Settings → General → Login Items.

Gatekeeper note: the .dmg is not code-signed or notarized. On first launch macOS may refuse to open it ("cannot be opened because the developer cannot be verified"). Right-click ClaudeBar.app → Open → Open to bypass. One-time step.

Build from source

make pack-macos        # → apps/macos/dist/ClaudeBar.app

Drag the resulting ClaudeBar.app into /Applications.

Windows

Install from a release (recommended)

Download claudebar-windows-<version>.msi from the latest release and double-click to run the installer. ClaudeBar will be installed to Program Files\Bilbilak\ClaudeBar\, given a Start Menu shortcut, and registered to auto-start at every user login.

SmartScreen note: the installer is not Authenticode-signed. On first run Windows will show "Windows protected your PC — unknown publisher". Click More info → Run anyway. One-time step.

To disable the auto-start, open Task Manager → Startup apps and disable ClaudeBar. To uninstall, use Settings → Apps → Installed apps → ClaudeBar (the MSI cleans up its registry entries and Start Menu shortcut).

Build from source

make pack-windows      # → apps/windows/publish/ClaudeBar.exe

Run apps/windows/publish/ClaudeBar.exe directly. Note that local builds produce a bare executable, not an .msi installer — the installer is only produced by the release workflow in CI.

Linux — Arch / AUR (easiest)

Pick the front-end matching your desktop environment and install from the AUR:

yay -S claudebar-helper      # Rust helper (required by all but claudebar-gnome)
yay -S claudebar-gnome       # OR claudebar-kde / cinnamon / xfce / mate / budgie / lxqt

_PKGBUILD_s live in the main repo under packaging/arch/.

Linux — other distros

Use make install-<front-end> from the repo root. See each apps/linux/<de>/README.md in the main repo for per-distro build-time dependencies.

make setup                         # npm install for the GNOME extension
make install-helper                # Rust helper → ~/.local/bin
make install-gnome                 # GNOME extension → ~/.local/share/gnome-shell/extensions
make install-kde                   # KDE Plasmoid (via kpackagetool6)
sudo make install-xfce  PREFIX=/usr  # XFCE plugin (meson install, system-wide)
sudo make install-mate  PREFIX=/usr  # MATE applet (system-wide)
sudo make install-budgie PREFIX=/usr # Budgie applet
sudo make install-lxqt  PREFIX=/usr  # LXQt plugin

PREFIX=/usr is required, not optional for the four GTK/Qt panel plugins. Each panel host (mate-panel, xfce4-panel, budgie-panel, lxqt-panel) scans a compile-time-pinned plugin directory ($prefix/share/<panel>/...) baked at the time your distro built the panel — usually /usr/share/..., never anything under XDG_DATA_DIRS. The Makefile default PREFIX=/usr/local lands files in a directory the panel will never look at, and your freshly installed applet won't appear in Add to Panel.

Build-time dependencies — apt on Ubuntu, Linux Mint, Debian

For the Rust helper plus any of the four GTK/Qt panel plugins:

sudo apt install build-essential pkg-config curl libdbus-1-dev libsecret-1-dev

The helper's tray-icon crate (ksni) requires libdbus-1-dev. Secret-service storage requires libsecret-1-dev. The Rust toolchain itself comes from rustup, not the system package — apt's rustc is generally too old for the helper's Cargo.toml (rust-version = "1.75").

Per-plugin GTK / Qt deps on top of that:

# MATE applet (Python applet via MatePanelApplet GIR + GTK3)
sudo apt install python3-gi python3-gi-cairo gir1.2-matepanelapplet-4.0 gir1.2-gtk-3.0 gettext

# XFCE plugin (C, meson)
sudo apt install meson libxfce4panel-2.0-dev libxfce4util-dev libxfce4ui-2-dev libjson-glib-dev libgtk-3-dev gettext

# Budgie applet (Vala, meson)
sudo apt install meson valac libbudgie-1.0-dev libpeas-dev libjson-glib-dev libgtk-3-dev gettext

# LXQt plugin (C++/Qt, cmake) — Qt5 for LXQt 1.x, Qt6 for LXQt 2.x (Lubuntu 25.04+)
sudo apt install cmake lxqt-build-tools qtbase5-dev qttools5-dev liblxqt0-dev               # LXQt 1.x
sudo apt install cmake lxqt-build-tools qt6-base-dev qt6-base-dev-tools qt6-tools-dev liblxqt2-dev libkf6windowsystem-dev   # LXQt 2.x

Reinstalling cleanly

If a prior install landed in the wrong prefix (e.g. you ran the default sudo make install-mate without PREFIX=/usr and ended up with files under /usr/local/share/mate-panel/applets/), sweep both prefixes before reinstalling:

sudo make uninstall -C apps/linux/mate PREFIX=/usr/local 2>/dev/null
sudo make uninstall -C apps/linux/mate PREFIX=/usr        2>/dev/null
sudo make install-mate PREFIX=/usr

Substitute mate with xfce, budgie, or lxqt as appropriate.

After installing or reinstalling the MATE applet, restart mate-panel so it re-reads its applet-definition cache:

nohup mate-panel --replace >/dev/null 2>&1 & disown

Then right-click the panel → Add to Panel… → ClaudeBar.

Uninstall

Each plugin's Makefile has a matching uninstall target. Run with the same PREFIX= you used when installing:

sudo make uninstall -C apps/linux/mate   PREFIX=/usr
sudo make uninstall -C apps/linux/xfce   PREFIX=/usr
sudo make uninstall -C apps/linux/budgie PREFIX=/usr
sudo make uninstall -C apps/linux/lxqt   PREFIX=/usr
make uninstall -C apps/linux/common/claudebar-helper   # removes .mo locale files
rm -f ~/.local/bin/claudebar-helper                    # the binary itself

Pre-built Linux artifacts

The release workflow publishes these native-format artifacts alongside the source tarball:

  • claudebar-helper-<version>-linux-x64.tar.gz — the Rust helper binary (x86_64 only for now). tar xf preserves the executable bit.
  • claudebar-linux-gnome-<version>.zip — GNOME Shell extension, installable with gnome-extensions install <file>.zip.
  • claudebar-kde-<version>.plasmoid — KDE Plasmoid, installable with kpackagetool6 -i <file>.plasmoid. After installing, also copy ~/.local/share/plasma/plasmoids/org.bilbilak.claudebar/contents/icons/claudebar.png into ~/.local/share/icons/hicolor/256x256/apps/ so the About dialog and panel resolve the icon — KPackage doesn't auto-register icons bundled inside the Plasmoid.
  • claudebar-linux-cinnamon-<version>.zip — Cinnamon applet.

Every release artifact is accompanied by a claudebar-<version>-SHA256SUMS file for download verification with sha256sum --check.

Desktop environments not covered above

Run the Rust helper's built-in tray mode as a fallback:

claudebar-helper tray

This registers a cross-DE StatusNotifierItem icon through the Secret Service, giving you the same two-bar indicator on any freedesktop-compliant panel.

Sign-in fails with getting default collection or Secret Service was not provided

The OAuth flow completed in your browser but the helper couldn't persist the token because the system has no usable Secret Service backend. Two common cases:

  • No daemon claims org.freedesktop.secrets. Lubuntu 25.x (and similar minimal Qt-only desktops) ship only the KDE compat shim without a daemon registered for the FreeDesktop name. Install gnome-keyring and the PAM hook, then log out and back in:

    sudo apt install gnome-keyring libpam-gnome-keyring

  • gnome-keyring is running but has no default "Login" collection. First-run state on Solus, Lubuntu after the gnome-keyring install, etc. Install seahorse (Solus already ships it), then in Seahorse File → New → Password Keyring → "Login" (capitalisation matters), leave the password blank, Continue, then right-click the new keyring → Set as Default.

After either fix, re-run sign-in via the panel applet. claudebar-helper status should return "status":"ok" instead of "unauthenticated".

Clone this wiki locally