Clauder - Claude Code Rate Limit Monitor

Real-time rate limit monitoring for Claude Code with a beautiful customizable statusline

clauder.fyi | Configure your experience from the web dashboard

Features

Smart Statusline

Real-time monitoring directly in your terminal:

5-hour rate limit tracking with progress bar and countdown
Weekly usage monitoring with reset time
Context window usage percentage
Git branch with dirty indicator
Carousel rotates through metrics automatically
Prompt quality scoring (time-limited after each prompt)
ML-powered ETA predictions (Pro)

Single-Writer Usage Cache

Run multiple Claude Code instances without hitting 429 rate limits:

Cross-process locking ensures only one instance fetches usage data
fetched_at timestamps prevent stale writes from corrupting the cache
retry_after coordination prevents 429 cascades across all terminals
Jittered refresh intervals stagger polling across instances

Full Customization

Configure everything from clauder.fyi/dashboard/extension:

Drag & Drop Reordering - Arrange elements in any order
Custom Icons - Choose from 6+ icon styles per element
Unicode/ASCII Mode - Works in any terminal
Progress Bars - Visual usage indicators
Carousel Controls - Set visible count and rotation

Sound Notifications

Prompt completion alerts
Rate limit warnings
Customizable thresholds (50-99%)
Quiet hours support

Budget Tracking (Pro)

Daily, weekly, monthly limits
Real-time cost monitoring
Auto-block when exceeded

Quick Install

curl -fsSL https://clauder.fyi/api/scripts/install | bash

Or generate a personalized install script at clauder.fyi.

Statusline Elements

Element	Description	Icons
Model	Active Claude model	`◆` `★` `⚡` `🤖` `🧠` `✦`
Git Branch	Current branch + dirty	(none) `$` `⎇`
Context	Window usage %	`ctx:` `◫` `mem:`
5-Hour	Rate limit + bar + ETA	(none) `⏱` `▣`
Weekly	7-day usage + reset	`W:` `📅` `7d:`
Prediction	ETA to limit	`~` `ETA:` `≈` `⚡`
Prompt Quality	Score after prompts	`✎` `✓` `◈`

Stale Indicator

When usage data cannot be refreshed (e.g., API rate limit), the statusline shows a ☁✕ indicator and dims the metrics. This clears automatically when the next fetch succeeds.

VS Code Extension

A VS Code extension that displays your Claude Code usage in the status bar. Monitor your 5-hour session and weekly limits at a glance.

Status Bar Features

Shows your current 5-hour session usage with time until reset
Color-coded indicator that shifts from tan to red as usage increases
Automatically shows weekly usage when approaching your weekly limit
Alerts when you hit the 5-hour or weekly limit
Rate-limited state display when API is temporarily unavailable

Installation

Install from the VS Code Marketplace or search for "Clauder" in VS Code Extensions.

Requirements

macOS (uses Keychain for OAuth credentials)
Claude Code CLI installed and authenticated (claude command)

Configuration

General

Setting	Default	Description
`clauder.refreshInterval`	`30`	Auto-refresh interval in seconds (5-300)
`clauder.weeklyHighlightThreshold`	`90`	Show weekly usage when above this % (50-100)
`clauder.statusDisplay`	`both`	Where to display status: `both`, `vscode`, or `shell`
`clauder.showProgress`	`true`	Show usage progress in the status bar

Carousel

Setting	Default	Description
`clauder.carousel.enabled`	`true`	Enable metric carousel rotation
`clauder.carousel.interval`	`5`	Rotation interval in seconds
`clauder.carousel.slides`	`1`	Number of visible metrics at once

Sound Notifications

Setting	Default	Description
`clauder.sounds.enabled`	`true`	Enable all sound notifications
`clauder.sounds.promptCompletion`	`true`	Play sound when Claude finishes responding
`clauder.sounds.rateLimitWarning`	`true`	Play sound when approaching rate limits
`clauder.sounds.rateLimitHit`	`true`	Play sound when rate limit is reached
`clauder.sounds.warningThreshold`	`80`	Usage % to trigger warning sound (50-99)
`clauder.sounds.customSoundPath`	`""`	Optional path to custom sound file

Sync (Pro)

Setting	Default	Description
`clauder.sync.enabled`	`false`	Enable syncing to Clauder backend for predictions
`clauder.sync.licenseKey`	`""`	License key for Clauder Pro
`clauder.sync.backendUrl`	`https://clauder.fyi`	Backend URL for sync
`clauder.sync.interval`	`30`	Sync interval in seconds (15-120)

Commands

Clauder: Refresh - Manually refresh usage data
Clauder: Toggle Sound Notifications - Enable/disable sounds
Clauder: Toggle Progress Display - Show/hide shell statusline progress
Clauder: Install Shell Integration - Install statusline scripts
Clauder: Sync Sound Settings - Sync sound preferences from dashboard
Clauder: Open Dashboard - Open the web dashboard
Clauder: Next Slide - Advance carousel to next metric

Environment Variables

Variable	Description
`CLAUDER_ASCII`	Set to `1` to force ASCII mode

Pro Features

Start with a 14-day free trial at clauder.fyi:

Statusline configurator with live preview
Sound notifications with quiet hours
ML-powered usage predictions
Budget tracking & alerts
Webhook integrations (Slack, Discord, custom)

Troubleshooting

"Not authenticated" message

Run claude in your terminal and complete the authentication flow. The extension reads credentials from the same Keychain entry used by Claude Code CLI.

Usage data not updating

Click the status bar item or run "Clauder: Refresh" from the Command Palette. If running multiple Claude Code instances, the single-writer cache ensures only one fetches at a time — wait ~30s for the next refresh cycle.

Persistent ☁✕ stale indicator

This means the usage API is returning 429 (rate limited). The indicator clears automatically once the API recovers. If it persists, restart your Claude Code terminals to pick up the latest scripts with single-writer coordination.

429 rate limit errors

If you see frequent 429s, ensure you're running script version 1.3.0+ (grep SCRIPT_VERSION ~/.claude/statusline-command.sh). Older versions lack the single-writer cache and can exhaust the API rate limit with multiple terminals. Reinstall with:

curl -fsSL https://clauder.fyi/api/scripts/install?key=YOUR_KEY | bash

Debug with diagnostics

Run Clauder: Show Diagnostics from the Command Palette. Opens a read-only editor tab with cache contents, lock state, event counts, and platform info. Paste the block into your bug report at github.com/nksrentas/clauder/issues.

Escape hatch: disable single-writer coordination

If single-writer mode is causing issues (stuck in loading state, unexpected errors), set clauder.rateLimit.coordinationMode to per-instance in settings. Each VS Code window will hit the API independently — more likely to rate limit, but removes coordination as a variable while you debug.

Known limitations

Single-writer coordination uses filesystem primitives (mkdir, rename, mtime) to serialize API calls across processes. These assumptions hold for the typical setup — local SSD, same user, ≤ ~10 terminals — but break in known ways:

Clock skew between processes

The stale-takeover threshold (60s) and TTL checks use Date.now() from each process independently. If system clocks drift significantly between terminals — unusual on a single machine, possible inside containers sharing a host clock that isn't NTP-synced, or across VMs — a process with a fast clock may take over a lock a real owner still holds. Mitigation: keep NTP running. We don't detect or repair drift; if diagnostics show repeated stale-takeovers without contention, check clock alignment.

Network filesystems (NFS, SMB, sshfs)

mkdir atomicity on NFS depends on server config and is not guaranteed across all implementations. If ~/.claude/ is on a network mount, lock races are possible. Keep the cache directory on local disk.

Very high concurrency (20+ instances)

The design targets ≤10 simultaneous Claude Code terminals. Beyond that, lock contention increases and the 30s fetch TTL may not produce a fresh result before all waiters time out. Not a hard failure — you'll see more ☁✕ stale indicators — but the coordination isn't tuned for this scale.

Same-user tampering trust model

Cache files are readable and writable by the user who owns them. A malicious process running as the same user could write garbage to usage-cache.json. We validate shape on read and route malformed entries through a 60s recovery backoff, but the trust boundary is the user account — not the process. Don't run untrusted code as your interactive user.

Windows shell integration

The statusline script is POSIX shell (bash/zsh). Windows users running Claude Code via WSL work fine; native Windows terminals (PowerShell, cmd) do not get the shared cache — the extension still coordinates among VS Code windows, but the shell statusline will fetch independently.

License

MIT

Clauder

nrentas