Subscription usage tracking

Keep tabs on your Claude Code subscription from anywhere — Untether surfaces usage directly in Telegram. This guide covers checking usage on demand and enabling automatic usage footers after every run.

In Codex, OpenCode and other non-Claude chats, /usage shows the token totals of the chat’s last session instead — see Cost budgets → Other engines.

Check usage with /usage#

Send /usage in any chat to see a full breakdown of your Claude Code subscription usage:

Untether

📊 Claude Code Usage

5h window: ████░░░░░░ 45% (resets in 2h 15m)
Weekly: ███░░░░░░░ 30% (resets in 4d 3h)
Sonnet: ██░░░░░░░░ 25%
Opus: █░░░░░░░░░ 5%
Extra: $0.00 used

The breakdown includes:

Enable footer usage line#

To show a compact usage summary after every completed Claude Code run, enable the subscription usage footer:

untether config

untether config set footer.show_subscription_usage true

toml

[footer]
show_subscription_usage = true

When enabled, completed messages include a line like:

⚡ 5h: 45% | 7d: 30%

This tells you how much of your 5-hour and 7-day rate limits you’ve used — all without leaving the chat. Once a window passes 50%, its reset time is added (⚡ 5h: 72% (1h 14m) | 7d: 30%).

With the footer off, Untether still adds a warning line once the 5-hour window passes 70% (⚡5h: 75% (1h 14m) | 7d: 30%), turning to ⚠️ at 90% and 🛑 5h limit hit — resets in … at 100%.

Limit notes during a run

Separately from the footer, a running Claude session shows a one-off ⚠️ 5h limit 85% used — resets 17:30 note when Claude Code reports the window is nearly used, and ⏳ Rate limited until … if a request is actually refused. Since v0.36.0 routine usage snapshots no longer show a false Rate limited wait (#790). See Troubleshooting → Rate-limit and API-retry notes.

Combine with API cost#

By default, Untether shows API token and cost information in the footer (show_api_cost = true). You can show both API cost and subscription usage together:

toml

[footer]
show_api_cost = true
show_subscription_usage = true

Or disable API cost to show only subscription usage:

toml

[footer]
show_api_cost = false
show_subscription_usage = true

Debug page (/usage debug)#

When the subscription usage footer goes silent, run /usage debug to see a one-message diagnostic block (#410) without grepping journalctl:

Untether

📊 Claude Code Usage
…
🔧 debug
• cache: last success 2026-05-04T11:07:32+00:00 (42s ago, fresh)
• last error: none
• OAuth token: expires 2026-05-15T08:00:00+00:00 (in 261h 3m)
• schema mismatches this process: 0

The block shows:

Use this when subscription usage stops appearing in the footer or returns stale numbers — the four fields point at the most likely root causes (auth lapsed, API shape changed, transient HTTP failure, or simply nothing fresh has been fetched yet).

Claude Code credentials#

The /usage command reads your Claude Code OAuth credentials to fetch live data from the Anthropic API. If you see “No Claude Code credentials found”, sign in to Claude Code on that machine (run claude and follow the login prompt).

Credential storage varies by platform:

Untether checks both locations automatically. If /usage still fails after logging in, verify that the Claude Code CLI is working by running claude directly.

Related#

• Cost budgets — set per-run and daily cost limits
• Configuration — full config reference for footer settings
• Troubleshooting — credential issues with /usage