Desktop App Usage

The desktop app is a Tauri v2 + Svelte frontend over the same Rust core as the TUI. It shares the local archive, config, currency, pricing, refresh, session drill-down, and report logic.

Install And Open

Install on Apple Silicon macOS with Homebrew Cask:

brew install --cask russmckendrick/tap/tokenuse-desktop
open -a "Token Use"

The macOS desktop app also ships as a signed and notarized Apple Silicon DMG. Linux desktop builds are published as unsigned AppImage, deb, and rpm assets for AMD64 and ARM64. Windows desktop builds are published as unsigned AMD64 NSIS and MSI installers. Verify the matching .sha256 file before running or installing unsigned assets.

Main Tabs

• Overview: command-center view with KPIs, a chronological Activity Pulse, project/tool spend, model spend, shell commands, and MCP servers.
• Deep Dive: analysis workbench with a larger activity trend, project rankings, top sessions, project/tool spend, model efficiency, core tools, shell commands, and MCP servers.
• Session: per-call session drill-down with clickable rows for full stored prompt, tool, command, and token metadata.
• Usage: per-tool consoles with 24-hour activity pulses, call/token/cost summaries, plan limit gauges when available, and top model bars. Opening this tab automatically selects 24 Hours so the filter row matches the console window.
• Model tables show observed cache-hit percentage separately from cache-read price rate. Session call details show cache read/write price rates for the call model.
• Config: currency selection, desktop behavior toggles, explicit Windows/Linux desktop update checks, confirmed local downloads for currency and pricing books, Claude/Copilot limit sidecar sync actions, and a confirmed clear-data action that rebuilds the archive.

The desktop header mirrors the TUI filters: period, tool, sort mode, and project. In-window keyboard shortcuts are resolved through the same embedded keymap as the TUI; sort mode can be changed from the header or with g, and cycles between spend, latest date, and token use. Shift-D toggles between live and bundled sample data. The app polls snapshots in the background so completed refreshes appear without blocking the UI.

Dashboard sections render the full sorted row set. Sections with more rows than fit in the current window scroll inside the section so the header, filters, and footer remain visible.

Reading The Dashboard

The Activity Pulse and Activity Trend panels use D3-backed SVG charts. Orange/red bars show relative spend by bucket, cyan/blue line and area marks show call-volume cadence, and hovering a bucket shows the period label, cost, and call count without changing filters. D3-backed heat strips in ranking tables use stepped blue/yellow/red cells for relative magnitude. The footer summarizes the visible range, peak bucket, latest bucket, and total calls. 24 Hours and 7 Days use hourly buckets so short views do not collapse into one or two bars. This Month stays hourly during the first 14 days of the month, then switches to daily buckets from the 15th onward; 30 Days and All Time use daily buckets. The 24 Hours period is rolling from the current time, not a calendar-day midnight cutoff.

Ranked table bars use the same stepped color ramp as the TUI: blue is lower relative volume, yellow/orange is hotter, and red marks the current high end of the table. These bars are relative to the visible table, not generated report images.

Usage consoles switch the visible period to 24 Hours when opened and ignore the project filter because they are rolling 24-hour tool monitors. Empty tools stay visible with compact idle rows so you can still confirm that Codex, Claude Code, Cursor, Copilot, and Gemini were checked.

Background Alerts

Closing the desktop window keeps Token Use running in the background. Left-click the tray or menu-bar icon for a compact 24-hour usage popover with a D3 sparkline, then choose Open to show the full dashboard. Right-click the icon and choose Show Token Use to open the dashboard directly, or choose Quit Token Use to stop the app. When the Dock/taskbar icon is visible, the Dock icon or launching Token Use again also restores the window.

While the app is running, the desktop backend keeps polling completed archive refreshes even if the window is hidden. If an automatic refresh imports a significant amount of new usage since the last alert baseline, Token Use sends a native desktop notification. Notifications are driven by all live imported usage, independent of the visible period, tool, project, or sort filters. Manual refreshes reset the alert baseline without sending a notification.

Background alert thresholds are configured in the shared config.json file:

{
  "currency": "USD",
  "background_alerts": {
    "enabled": true,
    "min_cost_usd": 1.0,
    "min_tokens": 100000,
    "min_calls": 25,
    "cooldown_minutes": 30
  },
  "desktop": {
    "open_at_login": false,
    "show_dock_or_taskbar_icon": true
  }
}

The defaults are conservative: notify after at least $1.00, 100k tokens, or 25 calls of new usage, with a 30-minute cooldown. Linux tray click behavior depends on the desktop environment, so use the tray menu when a left-click does not open the popover. Windows notifications are most reliable from an installed build.

Desktop Settings

The Config tab includes desktop-only toggles for opening Token Use at login and showing the Dock/taskbar icon. Open at login is off by default; the Dock/taskbar icon is visible by default so the app keeps normal window-switcher behavior until you opt into a tray-first setup.

On Windows and Linux, the Config tab also includes an explicit update check against GitHub Releases. Windows updates use the NSIS setup installer. Linux in-app updates target AppImage installs; .deb and .rpm package users should update manually with the matching GitHub Release asset. macOS desktop updates continue through Homebrew Cask.

Refresh

Use the refresh button or keyboard shortcut r to sync the archive. Refreshes use the same background archive refresher as the TUI and keep the previous data visible if a sync fails.

The Config tab’s clear-data action shows a native warning, deletes archive.db, and immediately reimports from local tool history. Config, rates, pricing books, legacy pricing snapshots, and reports are kept. Archive-only rows disappear if the original source files are gone, and rebuilt rows use the current configured pricing.

If sample data is selected manually with Shift-D, refreshes update the cached live data without switching the visible dashboard back until Shift-D is pressed again.

Project, Session, Currency, And Report Pickers

The desktop app uses native dialogs where that makes sense:

• Project and session pickers include search.
• Session call rows open a detail modal with Enter, Space, or a mouse click.
• Currency selection writes the same config.json setting used by the TUI.
• Report generation writes executive HTML/PDF report decks, one-page SVG/PNG visual summaries, plus raw JSON, Excel, or CSV-folder reports, from a dedicated period and project/all-projects scope. Reports always include all tools; redaction is off by default and can be toggled on before generation.
• Folder selection uses the Tauri dialog plugin and is runtime-only, matching TUI behavior.

Shared Local Data

The desktop app and TUI share the platform config directory under tokenuse:

File / directory	Shared purpose
config.json	User overrides, display currency, background alerts, and desktop preferences
archive.db	Durable local usage archive
exchange-rates.json	Optional local currency snapshot
rates.json	Legacy local currency snapshot
pricing-upstream.json	Optional local broad pricing book
pricing-overrides.json	Optional local official overrides and aliases
pricing-snapshot.json	Legacy local pricing snapshot
limits/claude-code.json	Optional Claude Code status-line limit sidecar
limits/copilot.json	Optional Copilot quota sidecar written by confirmed sync
reports/	Fallback report directory

Changing currency, refreshing or clearing the archive, downloading local rates/pricing books, or syncing limit sidecars from the desktop app affects the same data the TUI reads.

The Config page shows links for the published currency snapshot and both pricing books beside the download rows, so users can inspect the files before downloading them locally. The pricing row also shows the active book source and its latest checked/generated date. The Claude limits row imports an existing local sidecar and shows a setup hint until Claude Code’s statusLine writes the OS-specific sidecar path. The Copilot limits row asks for confirmation before reading local Copilot credentials and fetching current quota state from GitHub.

The Claude statusLine row sits directly above Claude limits and bootstraps the sidecar without touching your visible status line. Install writes a wrapper script under <config>/tokenuse/statusline/claude-code.sh (or .ps1 on Windows), backs up ~/.claude/settings.json to settings.json.bak.<unix-ts>, and rewrites statusLine.command to point at the wrapper. The wrapper tees Claude Code’s stdin into the sidecar JSON file and forwards it through whatever command was previously configured (for example cship), so the visible status line is unchanged. If you’d rather edit settings.json yourself, the second confirmation dialog offers Generate wrapper only, which writes the wrapper without modifying any user config. Re-installing is idempotent; clicking the row again on an installed system offers Uninstall, which restores the prior command and deletes the wrapper but leaves the sidecar JSON in place.