Codex Usage for Quickshell

A compact Codex usage and limits dashboard for the ii Hyprland bar.

🇬🇧 English · 🇷🇺 Русский

Codex Usage is a Quickshell module for the ii / illogical-impulse style Hyprland bar. It adds a compact top-bar indicator and a smooth, click-open dashboard for Codex usage and limits.

The module is Codex-only: it does not read Claude projects or cloud billing pages.

Features

• Theme-aware Codex indicator in the top bar.
• Click-open popup that follows the visual language of the system panel.
• Local token totals for today, the week, the last turn, input, cached input, output, and reasoning.
• Live 5-hour and weekly limit cards from the local Codex app server, with cache and local session-log fallback.
• A small freshness indicator for limits: live, cache, stale, or local.
• Activity bars for the last 18 hours.
• Loading skeletons and animated value updates instead of full visual resets.
• A settings drawer with immediate controls, palette presets, and a generated custom palette.
• Live light/dark-theme detection through gsettings org.gnome.desktop.interface color-scheme.
• The collector pauses when the module is disabled in configuration.

Screenshots

The full panel with limits, token statistics, activity history, and its settings drawer in light and dark system themes:

Light theme	Dark theme

The top-bar indicator adapts its icon to the selected theme:

Light theme	Dark theme

Requirements

• Quickshell with a configuration using the qs.modules.common, qs.services, and qs.modules.ii.bar import layout.
• Python 3.10 or newer.
• Codex Desktop or Codex CLI writing session files under ~/.codex/sessions.
• codex available on PATH or in a common user install location to fetch live account limits. When unavailable, the collector uses cached or local session metadata.
• Optional: gsettings for live system light/dark detection.

Install

git clone https://github.com/knyazin47/codex-usage-quickshell.git
cd codex-usage-quickshell
./install.sh

The installer copies the module files to:

~/.config/quickshell/ii/modules/ii/bar/codexUsage
~/.config/quickshell/ii/services
~/.config/quickshell/ii/scripts/codex-usage
~/.config/quickshell/ii/assets/icons

Add this import to ~/.config/quickshell/ii/modules/ii/bar/BarContent.qml:

import qs.modules.ii.bar.codexUsage

Place the indicator where you want it in the bar. A convenient position is near system resources and media:

CodexUsageIndicator {
    visible: Config.options.bar.codexUsage.enable && root.useShortenedForm < 2
    Layout.leftMargin: 6
}

Add the configuration object under Config.options.bar in ~/.config/quickshell/ii/modules/common/Config.qml:

property JsonObject codexUsage: JsonObject {
    property bool enable: true
    property string language: "auto" // auto, ru, en
    property bool showActivity: true
    property bool showTokenBreakdown: true
    property bool showDetailedLimits: true
    property int refreshInterval: 15 // seconds
    property string accentStyle: "codex" // codex, violet, mint, rose, clean, custom
    property int customAccentHue: 220 // 0-360
    property string customAccentBase: "#86a8ff"
    property int customAccentTemperature: 0 // -100 cool, 0 balanced, 100 warm
}

Reload Quickshell:

qs -c ii -d

Privacy

The collector reads local Codex session JSONL files in ~/.codex/sessions to calculate token totals. By default, it also requests the current account rate-limit snapshot from the local Codex app server, so limits remain current after mobile usage or a reset window.

Live limit snapshots are cached at:

${XDG_CACHE_HOME:-~/.cache}/codex-usage-quickshell/rate_limits.json

Disable live-limit refresh to use local data only:

CODEX_USAGE_LIVE_LIMITS=0 ~/.config/quickshell/ii/scripts/codex-usage/codex_usage.py

Workspace names are not collected by default. Enable them explicitly only if you want that data:

CODEX_USAGE_INCLUDE_WORKSPACE=1 ~/.config/quickshell/ii/scripts/codex-usage/codex_usage.py

If you publish screenshots, remember that aggregate token counts may be visible.

Tuning

The collector scans the last 8 days of session files by default. Override this for debugging:

CODEX_USAGE_DAYS=14 ~/.config/quickshell/ii/scripts/codex-usage/codex_usage.py

Archived sessions are skipped by default to keep refreshes light. Include them explicitly:

CODEX_USAGE_INCLUDE_ARCHIVED=1 ~/.config/quickshell/ii/scripts/codex-usage/codex_usage.py

Large session histories can be expensive to scan frequently. The UI defaults to 15 seconds and clamps the refresh value to at least 5 seconds. Live-limit requests have a short timeout and fall back to cached or local session metadata if the Codex app server does not respond. While the panel shows local or stale, the configured automatic interval continues probing live limits; starting Codex Desktop later can therefore switch the source back to live data without pressing refresh. The refresh button and refresh-interval buttons bypass the short live-limit cache for an immediate account-limit check.

Tune live-limit cache timing with:

CODEX_USAGE_LIVE_CACHE_SECONDS=5 ~/.config/quickshell/ii/scripts/codex-usage/codex_usage.py
CODEX_USAGE_LIVE_STALE_SECONDS=900 ~/.config/quickshell/ii/scripts/codex-usage/codex_usage.py

License

MIT