Claude Drain Guard

A zero-dependency VS Code extension that watches Claude Code locally, aggregates five-minute slices, and tells you to stop after the first anomalous prompt—before the next few prompts drain the session.

Install or update

Install Claude Drain Guard 0.9.1 from the Visual Studio Marketplace, or open Extensions: Install from VSIX... in VS Code and select the 0.9.1 VSIX package.

Marketplace releases are immutable: an uploaded package cannot be replaced. Version 0.9.1 adds immediate, monotonic 5h/7d synchronization on top of the official cache telemetry introduced in 0.9.0.

Status bar

Five-hour usage and cache hit stay visible in a small item on the right. A separate state indicator sits beside it:

• Normal: 5h 31% · cache 97% followed by a blue dot
• Elevated: the same metrics followed by a yellow dot
• Critical: the same metrics followed by a red dot and Alert

Click the item and select Refresh every Ns to set a 1–60 second background refresh interval. The default is 15 seconds; file changes still trigger an immediate incremental read.

Quota display adapts to the available data: Claude.ai 5h/7d, 5h-only, stale quota, or local API/Bedrock usage. Cache hit remains visible in every active mode. The colored indicator is independent of the quota percentage: only cache, fresh-token, change-point, and sudden-drain anomaly signals change it.

Signals

• Official main-conversation cache miss and expected-rebuild classification on Claude Code 2.1.251+
• Per-turn cache hit, cache rewrite, and fresh-token spike
• Consecutive large cache-rewrite detection; one low cache percentage is not critical by itself
• Median/MAD robust anomaly score, resistant to outliers
• Short EWMA acceleration against the user's own rolling baseline
• Page-Hinkley change points and one-sided CUSUM for sustained drain
• Multivariate risk scoring across fresh input, cache write, output, cache deficit and cache cliffs
• Baselines segmented by model, project, context bucket, and main/subagent/workflow traffic
• Deterministic bootstrap 30-minute burn forecast with p50/p90 bounds
• Hysteresis and notification cooldown to suppress alert flapping
• Compact status bar: 5m fresh tokens · cache hit · risk score
• Compact right-side usage item plus a tiny blue/yellow/red state indicator
• Compact native hover for the current slice; detailed evidence stays in VS Code Quick Pick
• Acknowledgement-required critical alert after the first anomalous turn
• Automatic local Markdown incident report with recent turns and five-minute slices
• Cost auto mode: prefer Claude Code's per-entry costUSD, then estimate from official model pricing when it is absent
• Separate 5-minute and 1-hour cache-write pricing when Claude Code provides the TTL breakdown

Dashboard

Click the status item or run Claude Drain Guard: Open Dashboard. The first card is the current Claude Code session, detected from the most recently active JSONL session file. It shows session totals and one bar per completed API response. Hover a bar for its exact fresh input, cache hit, output, time, and cost. Records created by older releases are associated with the latest contiguous project run without rescanning or duplicating historical data.

The 24-hour chart switches between 5-minute, 30-minute, and 1-hour buckets and uses a log scale so ordinary activity remains visible beside a large spike. It includes numeric scale labels, total/peak values, and detailed hover data. The initial 5-minute bars are rendered before Webview JavaScript runs, and current-session turns backfill a bucket if its aggregate slice is not available yet. Consecutive anomalous turns are grouped into one incident with aggregate fresh tokens and cost instead of filling the table with repeated rows. Prompt and response content is never shown.

The cached 5-hour usage snapshot has its own reset timer. When its published reset time arrives, the status bar moves the expired window from 100% to a new local 0% window immediately and performs a read-only background refresh; it no longer waits for the next prompt. Five-hour quota rollover does not imply prompt-cache expiry and does not affect anomaly classification. The first response in a new session or after at least five idle minutes is treated as a possible cache rebuild. When official telemetry is connected, Claude Code's own unexpected-miss classification takes priority and expected rebuilds never alert.

Cost follows the mature ccusage auto strategy: use Claude Code's reported per-entry estimate when available, otherwise multiply input, output, cache-read, 5-minute cache-write, and 1-hour cache-write tokens by the matching official model rates. It is an API-equivalent impact estimate, not a Claude Max invoice and not a conversion to the 5-hour quota. If old records omit the TTL breakdown, the default fallback is the standard 5-minute cache-write rate and can be changed with claudeDrainGuard.cost.fallbackCacheTtl. Cloud-provider and fast-mode fallbacks are deliberately left unavailable unless Claude Code reports their cost, avoiding a misleading first-party estimate.

If 5h:— remains visible, click Connect live usage in the dashboard. On setups where the official VS Code extension keeps its login isolated, this opens the bundled official Claude Code CLI for a one-time OAuth login; Claude Drain Guard never receives or stores the token itself.

Official cache telemetry

Claude Code 2.1.251+ exposes authoritative main-conversation cache statistics through its status-line JSON. Run Claude Drain Guard: Connect Official Cache Telemetry once to receive:

• warm, cold, or unknown state
• observed 5-minute or 1-hour TTL and expiry
• session hit ratio, requests, unexpected misses, and expected rebuilds
• current cache read/write tokens and the next cold-recache estimate

The connection is explicit and fail-safe. It adds a small local status-line helper to Claude settings, stores only the listed counters, and never stores prompt or response text. If Claude already has a custom status line, Drain Guard refuses to overwrite or wrap it. Use Disconnect Official Cache Telemetry to remove only a status-line entry owned by Drain Guard.

The dashboard uses three layers: official status-line data for the active main conversation and immediate 5h/7d updates, incremental JSONL reads for response history and subagents, and the OAuth usage endpoint as a five-minute quota reconciliation fallback. If the optional official layer is absent or stale, monitoring falls back without blocking Claude.

Performance

• Event-driven reads target only the JSONL file that changed
• Configurable 1–60 second checks touch only known active files
• Full session discovery is asynchronous and runs once per minute
• Appended data is streamed in 256 KB chunks; incomplete JSONL tails are preserved
• State writes are asynchronous, atomic, and coalesced only after new data
• Incident reports are written asynchronously
• Claude transcript files are opened read-only; no file lock is acquired
• No proxy, certificate, environment-variable rewrite, child process, or prompt interception is installed

No prompts, source code, credentials, or tool arguments are collected. Local anomaly monitoring remains independent of the network. Live 5h/7d usage is enabled by default: when a readable Claude OAuth token is available, the adapter makes its own read-only GET /api/oauth/usage request at most once per five minutes with a hard timeout. It does not observe or modify another extension's HTTP response. No model prompt is sent, and the token is never logged or persisted. The feature can be disabled with claudeDrainGuard.authoritativeQuota.enabled.

Development

Open this folder in VS Code and press F5. Run node --test test/*.test.js for the detector tests.

To create a Marketplace package, increment version in package.json for every release, then run npx @vscode/vsce package --no-dependencies. Never reuse a version that has already been uploaded.

Commands

• Claude Drain Guard: Open Dashboard
• Claude Drain Guard: Connect Live Usage
• Claude Drain Guard: Connect Official Cache Telemetry
• Claude Drain Guard: Disconnect Official Cache Telemetry
• Claude Drain Guard: Show Details
• Claude Drain Guard: Generate Incident Report
• Claude Drain Guard: Mute Alerts for 15 Minutes
• Claude Drain Guard: Reset Baseline

Privacy and security

See PRIVACY.md and SECURITY.md. This is a community project and is not affiliated with or endorsed by Anthropic.