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 Hyprland

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.

The native widget also needs a C compiler, pkg-config, GTK 3 and JSON-GLib development packages.

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 --native waybar

3. Add it to your desktop

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

Merge the generated module definition into your Waybar config and add cffi/usagestat to a module group:

TERMINAL
cat ~/.local/share/usagestat-bar/platforms/waybar/native.jsonc

Include the shipped Waybar style rules and reload Waybar. The native CFFI widget is tested with Waybar 0.15.0. Placement settings can move the widget between groups and panel edges.

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.