Installation

QuotaDeck runs on Linux as a native desktop application, a background service, a Cinnamon applet, or a single CLI/server binary.

Debian or Linux Mint

Download the latest quotadeck_<version>_amd64.deb from GitHub Releases, then install it:

sudo apt install ./quotadeck_0.1.0_amd64.deb

Open QuotaDeck from the application menu. The package includes the daemon, desktop application, systemd user unit, and Cinnamon applet.

The Cinnamon applet uses orange and black for Claude, black on white for Codex, and white on black for Z.ai, each on a circular background. A light-blue rounded frame and slate-blue background highlight the selected Claude subscription’s icon and percentage. Right-click the applet and choose Configure panel indicators to enable or disable the warning icon and adjust its usage threshold (80% by default). A red ring surrounds the icon of any displayed Claude subscription that exhausts its 5-hour window, including when you display its weekly quota; if the selected account is blocked and hidden, its blocked 5-hour indicator appears automatically. Stale data and elapsed reset times do not trigger the red ring.

Open Manage plans on the dashboard and choose Install & set up to prepare cswap, or run the equivalent CLI command:

quotadeck setup cswap

QuotaDeck uses the package's pipx dependency (or an existing uv) to install claude-swap for the current user. If no account exists yet, it asks cswap to add the current Claude Code login; sign in to Claude Code first.

Portable AppImage

Download QuotaDeck-<version>-x86_64.AppImage, make it executable, and launch it:

chmod +x QuotaDeck-0.1.0-x86_64.AppImage
./QuotaDeck-0.1.0-x86_64.AppImage

Server and CLI

The release archive contains the standalone quotadeck binary. Start the local dashboard with:

quotadeck doctor
quotadeck serve

Open http://127.0.0.1:9211. The server refuses non-loopback bind addresses.

First check

Use diagnostics before changing configuration:

quotadeck doctor
quotadeck status --json

doctor reports only paths, versions, source decisions, and secret-presence booleans. It never prints a provider token. Continue with provider setup if a source is missing.

Build from source with Devbox

The repository's Devbox environment pins the language and packaging toolchain:

git clone https://github.com/devthefuture-org/quotadeck.git
cd quotadeck
devbox run bootstrap
devbox run test
devbox run build

Use devbox run setup-cswap to install and initialize cswap in the same portable environment.

The Wails desktop executable is intentionally compiled with the host C compiler and host GTK/WebKitGTK development files, including when the build runs from Devbox. This prevents a Debian package from retaining /nix/store interpreter or library paths. On Debian/Ubuntu, install build-essential, pkg-config, libgtk-3-dev, and libwebkit2gtk-4.1-dev before running devbox run package-deb.

Build from source without Devbox

Building requires Go 1.25+, Node.js 22+, and npm:

git clone https://github.com/devthefuture-org/quotadeck.git
cd quotadeck
npm ci --prefix web
make test build
./dist/quotadeck serve

Native desktop and package builds additionally require GTK 3 and WebKitGTK 4.1 development files, ImageMagick, and dpkg-deb. The Wails Go module is pinned by go.mod; a separate Wails CLI installation is not required.