usagestat.
GitHub
UsageStat/Install

MAKE YOURSELF AT HOME.

Install UsageStat.
Find your flow.

Start with the backend, connect your providers, then add Bar to keep your usage in sight. Find your setup for Windows, macOS, or Linux.

Start with the backend ↓Already have UsageStat? Add Bar ↓

Choose your operating system.

01

Install the backend

Choose the package manager for your Linux system. Each package includes the CLI, daemon, and bundled providers.

Full backend installation guide ↗
Arch Linux · x86-64
TERMINAL
yay -S usagestat-bin

Use your existing AUR helper. Installs the CLI, daemon, and provider plugins.

Review the AUR package
Prefer a direct download?x86-64 & ARM64 archives Linux · glibc 2.39+ · Installation instructions
02

Connect your providers

Sign in to a supported provider CLI or app, or configure its credentials. Then check your first provider.

Find your provider and sign-in method ↗
TERMINAL
usagestat list
usagestat config validate
usagestat usage claude

This example checks Claude. Replace claude with an installed provider ID.

Want the local dashboard and HTTP API?

Add the providers you want to poll to ~/.config/usagestat/config.toml:

TERMINAL
[[providers]]
id = "claude"
enabled = true

Then start the daemon in a systemd user session:

TERMINAL
usagestat daemon enable
usagestat dashboard

Without systemd, run usagestatd in a terminal instead.

The dashboard opens at http://127.0.0.1:6736/dashboard.

03 OPTIONAL

Add Bar to your desktop.

Choose your Linux desktop or window manager. Bar uses the backend from step 1.

1. Get UsageStat Bar

The Linux integrations are currently published on the linux-ports branch.

TERMINAL
git clone --branch linux-ports https://github.com/hashimkarim/usagestat-bar.git
cd usagestat-bar

2. Install for bspwm

Install Python 3, GJS, GTK 4.12+, libadwaita 1.4+, dconf, GObject introspection, librsvg, and the Adwaita icon theme from your distribution. Wayland popups also need gtk4-layer-shell.

TERMINAL
./platforms/linux/build.sh artifacts/usagestat-bar-linux.tar.gz
mkdir -p artifacts/linux-install
tar -xzf artifacts/usagestat-bar-linux.tar.gz -C artifacts/linux-install
python3 artifacts/linux-install/usagestat-bar/platforms/linux/install.py

3. Add it to your desktop

The default install is under ~/.local. Include ~/.local/bin in your session’s PATH.

Merge the shipped module into your Polybar config, add usagestat to your bar, and reload Polybar:

TERMINAL
cat ~/.local/share/usagestat-bar/platforms/polybar/config.ini

The i3 and bspwm profiles support top and bottom bars.

4. Make it yours

TERMINAL
usagestat-bar preferences

Enable your providers and choose usage windows, colors, and display options. Set an explicit CLI path if your desktop cannot find the backend.

Linux installation and desktop requirements ↗

GNOME’s extension is installed from source while its Extensions directory listing is pending. Try the Linux desktop demos ↗

A note on compatibility. Linux release archives support x86-64 and ARM64 with glibc 2.39+. Package availability varies by distro. Bar requires a working backend and the dependencies for your selected integration. Check desktop support.