Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ ccstatusline --version

- **Tokens Input** / **Tokens Output** / **Tokens Cached** / **Tokens Total** - Show current-session token counts. Input/output prefer cumulative transcript metrics and fall back to `context_window.total_input_tokens` / `context_window.total_output_tokens` when transcript metrics are unavailable; cached/total use transcript metrics.
- **Cache Hit Rate** / **Cache Read** / **Cache Write** - Show prompt-cache efficiency. Cache Hit Rate uses cache reads divided by cache reads plus cache writes; Cache Read and Cache Write include each value's share of prompt context. They default to the latest turn from `context_window.current_usage`, can switch to cumulative session totals, and can hide when empty.
- **Cache Timer** - Show time remaining before the current prompt-cache entry expires. When Claude Code provides usable `prompt_cache` data, the widget counts down to `expires_at` or shows `COLD` when `warm` is false. The reported `ttl` (`5m` or `1h`) controls the fresh/draining/urgent glyph thresholds. This reported state takes precedence even during a turn, so the Working glyph (`🔥 HOT`) is used only in the transcript fallback. Without usable reported state (including `caching_observed: false`), the widget shows `HOT` while a main-chain turn is active, then estimates expiry from the latest assistant request with cache activity. Interrupts and local slash commands such as `/cost` end that working state without refreshing the cache anchor. The `t` setting selects a 5-minute or 1-hour TTL for this fallback countdown; it also supplies glyph thresholds when a reported expiry has no recognized TTL. Each state's glyph can be customized, and the widget can hide when neither reported state nor a transcript cache anchor is available.
- **Cache Timer** - Show time remaining before the current prompt-cache entry expires. When Claude Code provides usable `prompt_cache` data, the widget counts down to `expires_at` or shows `COLD` when `warm` is false. The reported `ttl` (`5m` or `1h`) controls the fresh/draining/urgent glyph thresholds. This reported state takes precedence even during a turn, so the Working glyph (`🔥 HOT`) is used only in the transcript fallback. Without usable reported state (including `caching_observed: false`), the widget shows `HOT` while a main-chain turn is active, then estimates expiry from the latest assistant request with cache activity. Interrupts and local slash commands such as `/cost` end that working state without refreshing the cache anchor. The `t` setting selects a 5-minute or 1-hour TTL for this fallback countdown; it also supplies glyph thresholds when a reported expiry has no recognized TTL. The countdown renders as `4m 52s`, or `4m52s` in short time mode. Each state's glyph can be customized (Backspace in the glyph editor renders a state without one), and the widget can hide when neither reported state nor a transcript cache anchor is available.
- **Cache Misses** / **Last Cache Miss** / **Cache Miss Tokens** / **Cache If Cold** - Show the prompt cache statistics Claude Code reports for the main conversation (Claude Code 2.1.251 or later), the same figures as the `Prompt cache (main)` line of `/usage`. Cache Misses shows the misses out of the session's requests (`2/14`); a miss is a request that re-processed content the cache already held, so rebuilds after a compaction don't count. Last Cache Miss shows when the last miss happened and its likely cause (`3m ago, tools changed (+2)`, `5m TTL expired`, `system prompt changed (+120 chars)`); causes need Claude Code 2.1.260 or later and read `cause unknown` when Claude Code identified none. Cache Miss Tokens shows the tokens the misses wrote back to the cache (`310.2k`), and Cache If Cold what the next request re-caches if the cache has gone cold by then (`45.0k`). They read only the status line payload, so they render nothing until the session's first API response; Last Cache Miss also stays empty until the first miss, and Cache If Cold right after a compaction until the next request.
- **Input Speed** / **Output Speed** / **Total Speed** - Show session-average token throughput with an optional per-widget rolling window (`0-3600` seconds, up to an hour; `0` = full-session average). Token totals and speed metrics count repeated content-block records with the same response ID once, including interleaved records.
- **Context Length** / **Context Window** / **Context %** / **Context % (usable)** / **Context Bar** - Show current context length, total context window size, used/remaining percentage, usable-window percentage, or a progress bar. When Claude Code omits a percentage, the percentage calculated from its current usage counts input, cache-read, and cache-write tokens, excluding output tokens until a later turn reads them as input. Reported percentages retain precedence. The window size is taken from Claude Code's reported `context_window.context_window_size` when present, then from a model-name hint (e.g. a `[1m]` suffix), and finally from a fixed fallback. Set `CCSTATUSLINE_CONTEXT_SIZE_FALLBACK` to a positive integer to override that last-resort fallback (defaults to `200000`) — useful when an older Claude Code does not report the window size for a 1M-context model, so the bar would otherwise read against 200k. Immediately after `/compact`, transcript fallback uses the latest `compact_boundary.postTokens` value until a new main-chain turn reports the current size, so the widgets do not retain the pre-compaction context.
Expand Down Expand Up @@ -327,7 +327,7 @@ Widget-specific shortcuts:
- **Context Bar**: `p` cycle medium/full/short/short-only progress bar
- **Compaction Counter**: `v` cycle value (count/auto/manual/unknown/reclaimed), `f` cycle format, `n` toggle Nerd Font icon in icon mode, `s` toggle trigger split (auto/manual/unknown), `t` toggle tokens reclaimed
- **Cache widgets** (Cache Hit Rate, Cache Read, Cache Write): `t` toggle turn/session scope
- **Cache Timer**: `t` cycle the fallback 5-minute/1-hour TTL (reported `5m`/`1h` takes precedence), `g` customize the working/fresh/draining/urgent/cold glyphs; Working is used only in the transcript fallback
- **Cache Timer**: `t` cycle the fallback 5-minute/1-hour TTL (reported `5m`/`1h` takes precedence), `s` toggle compact time, `g` customize the working/fresh/draining/urgent/cold glyphs; Working is used only in the transcript fallback; Backspace in the glyph editor renders that state without one
- **Sandbox Status**: `f` cycle glyph/text/word format, `n` toggle Nerd Font lock icons in glyph mode
- **Claude Status**: `h` toggle the 48-hour incident-history strip, `l` toggle the link to the status page
- **Voice Status**: `f` cycle format, `n` toggle Nerd Font microphone icons
Expand Down
43 changes: 35 additions & 8 deletions src/widgets/CacheTimer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,11 @@ import type {
import { CACHE_EMPTY_HIDEABLE_STATE } from './shared/cache-scope';
import { makeModifierText } from './shared/editor-display';
import { isHidden } from './shared/hideable';
import { removeMetadataKeys } from './shared/metadata';
import {
isMetadataFlagEnabled,
removeMetadataKeys,
toggleMetadataFlag
} from './shared/metadata';
import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
import {
getSlotSymbol,
Expand All @@ -36,6 +40,11 @@ const DEFAULT_TTL_SECONDS = 300;
const TTL_OPTIONS = [300, 3600] as const; // 5 minutes, 1 hour
const TOGGLE_TTL_ACTION = 'toggle-ttl';

// Same key, action and metadata flag as the reset timers, so short time works
// the same way on every timer widget.
const COMPACT_METADATA_KEY = 'compact';
const TOGGLE_COMPACT_ACTION = 'toggle-compact';

const SAFETY_MARGIN = 5; // display as COLD 5s before actual expiry

// One editable glyph per display state, so nerd-font / ASCII users can replace
Expand Down Expand Up @@ -271,13 +280,20 @@ function getReportedTtlSeconds(context: RenderContext): number | null {
}
}

function formatCountdown(remaining: number): string {
// Labeled like the reset timers ('4m 52s' / '4m52s') rather than clock
// notation, so every timer widget reads the same way. Seconds always render:
// they are the point of a cache countdown, and dropping a zero part the way
// formatUsageDuration does would make the widget jump width every minute.
function formatCountdown(remaining: number, compact: boolean): string {
if (remaining <= 0) {
return 'COLD';
}
const m = Math.floor(remaining / 60);
const s = Math.floor(remaining % 60);
return `${m}:${s.toString().padStart(2, '0')}`;
const total = Math.floor(remaining);
const h = Math.floor(total / 3600);
const m = Math.floor((total % 3600) / 60);
const s = total % 60;
const parts = [h > 0 && `${h}${compact ? 'h' : 'hr'}`, (h > 0 || m > 0) && `${m}m`, `${s}s`];
return parts.filter(Boolean).join(compact ? '' : ' ');
}

// The glyph for the current drain state (excluding HOT, handled in render).
Expand Down Expand Up @@ -314,6 +330,10 @@ export class CacheTimerWidget implements Widget {
if (ttlSeconds !== DEFAULT_TTL_SECONDS) {
modifiers.push(`ttl ${formatTtlLabel(ttlSeconds)}`);
}

if (isMetadataFlagEnabled(item, COMPACT_METADATA_KEY)) {
modifiers.push('compact');
}
return {
displayText: this.getDisplayName(),
modifierText: makeModifierText(modifiers)
Expand All @@ -329,21 +349,27 @@ export class CacheTimerWidget implements Widget {
return cycleTtl(item);
}

if (action === TOGGLE_COMPACT_ACTION) {
return toggleMetadataFlag(item, COMPACT_METADATA_KEY);
}

return null;
}

render(item: WidgetItem, context: RenderContext, _settings: Settings): string | null {
const hideWhenEmpty = isHidden(item, CACHE_EMPTY_HIDEABLE_STATE.key);
const compact = isMetadataFlagEnabled(item, COMPACT_METADATA_KEY);

if (context.isPreview) {
return formatRawOrLabeledValue(item, this.getLabelPrefix(), withGlyph(getSlotSymbol(item, FRESH_SLOT), '4:52'));
const sample = formatCountdown(292, compact);
return formatRawOrLabeledValue(item, this.getLabelPrefix(), withGlyph(getSlotSymbol(item, FRESH_SLOT), sample));
}

const reportedRemaining = getReportedRemainingSeconds(context);
if (reportedRemaining !== null) {
const ttlSeconds = getReportedTtlSeconds(context) ?? getTtlSeconds(item);
const glyph = getStateSymbol(item, reportedRemaining, ttlSeconds);
return formatRawOrLabeledValue(item, this.getLabelPrefix(), withGlyph(glyph, formatCountdown(reportedRemaining)));
return formatRawOrLabeledValue(item, this.getLabelPrefix(), withGlyph(glyph, formatCountdown(reportedRemaining, compact)));
}

const transcriptPath = context.data?.transcript_path;
Expand All @@ -366,12 +392,13 @@ export class CacheTimerWidget implements Widget {
const remaining = getRemainingSeconds(lastAssistant, ttlSeconds);
const glyph = getStateSymbol(item, remaining, ttlSeconds);

return formatRawOrLabeledValue(item, this.getLabelPrefix(), withGlyph(glyph, formatCountdown(remaining)));
return formatRawOrLabeledValue(item, this.getLabelPrefix(), withGlyph(glyph, formatCountdown(remaining, compact)));
}

getCustomKeybinds(): CustomKeybind[] {
return [
{ key: 't', label: '(t)tl', action: TOGGLE_TTL_ACTION },
{ key: 's', label: '(s)hort time', action: TOGGLE_COMPACT_ACTION },
getSymbolKeybind()
];
}
Expand Down
Loading
Loading