Configuration

Configuration

All settings are optional — every key falls back to a built-in default. Config lives at ~/.config/claude-usage/config.json (created and updated automatically as you change things via the right-click menu). You can also hand-edit it; from a source checkout, copy the example first:

cp config.json.example config.json

{
    "refresh_seconds": 60,
    "osd_opacity": 0.75,
    "osd_scale": 1.0,
    "theme": "default"
}

---

All keys

Refresh & display

Key	Default	Description
refresh_seconds	60	Base poll interval — how often to fetch usage from the API (seconds).
refresh_max_seconds	300	Max poll interval the adaptive backoff climbs to when the API rate-limits/errors; snaps back to refresh_seconds on the next clean refresh.
osd_opacity	0.75	OSD background opacity (0.15–1.0). Bars/text stay fully opaque for legibility.
osd_scale	1.0	OSD zoom (0.6–2.0). Updated automatically when you scroll over the OSD.
theme	default	Palette name — see Themes for the full list of 11.
osd_view_mode	bars	bars (progress bars + ticker) or gauge (circular rings).

Position & window state

Key	Default	Description
osd_position	top-right	Anchor: top-left / top-right / bottom-left / bottom-right / custom.
osd_x / osd_y	null	Exact coordinates, used only when osd_position is custom. Written automatically on drag.
osd_minimized	false	Whether the OSD is collapsed to its thin strip. Restored on launch.
osd_visible	true	Whether the OSD is shown. Written on quit so it reopens the same way.
osd_always_on_top	true	Keep the OSD pinned above other windows. Off => a normal background desktop widget. Toggle via right-click -> "Always on top".

Tickers

Key	Default	Description
show_ticker	true	Scrolling per-turn cost strip along the OSD bottom.
show_news	false	Opt-in. Anthropic/Claude headline strip from Hacker News. Off by default because it makes outbound calls to a 3rd-party feed.

Local limits (popup display only)

These drive the popup's local-tracking bars; they do not affect the real API rate-limit data.

Key	Default	Description
daily_message_limit	200	Daily message limit for local tracking.
weekly_message_limit	1000	Weekly message limit for local tracking.
daily_token_limit	5000000	Daily token limit for local tracking.
weekly_token_limit	25000000	Weekly token limit for local tracking.

Paths & notifications

Key	Default	Description
claude_dir	~/.claude	Path to the Claude Code data directory.
notifications_enabled	true	Desktop notifications on threshold crossings.
notify_thresholds	[0.75, 0.90]	Utilization fractions that fire a notification when first crossed.

Integrations (opt-in)

Key	Default	Description
api_server_enabled	false	Start a localhost JSON API (see Shell Integrations).
api_server_host	127.0.0.1	Bind address for the API server.
api_server_port	8765	Port for the API server.
webhooks	{}	Map of event → URL. Events: threshold_crossed, daily_report, anomaly.

---

Examples

Bottom-left, larger, opaque, Dracula:

{
    "theme": "dracula",
    "osd_position": "bottom-left",
    "osd_scale": 1.3,
    "osd_opacity": 1.0
}

Poll less often to ease the API budget (reset times only change every 5h/7d, so a longer interval is fine):

{
    "refresh_seconds": 120
}

Webhook to Slack on threshold + anomaly:

{
    "webhooks": {
        "threshold_crossed": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
        "anomaly": "https://hooks.slack.com/services/XXX/YYY/ZZZ"
    }
}