Skip to content

Commit 355af2e

Browse files
committed
Merge origin/main into feat/session-forecast
2 parents ca78e3b + b9136d9 commit 355af2e

34 files changed

Lines changed: 2140 additions & 133 deletions

‎docs/USAGE.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ ccstatusline --version
3131
- **Claude Session ID** / **Session Name** / **Claude Account Email** - Show session identifiers plus the currently signed-in Claude account email.
3232
- **Claude Status** - Show the current Claude/Anthropic service status from `status.claude.com` (`ok` when the indicator is `none`, otherwise the indicator word such as `minor`, `major`, `critical`, or `maintenance`). Press `h` in the editor to add a 48-hour incident-history strip of eight six-hour blocks (oldest to newest), each colored by the worst incident overlapping that block: green (none), yellow (minor), orange (major), red (critical). Responses are cached for about five minutes; on network failure the widget shows stale data when available or degrades to `?`. With the history strip enabled the widget colors itself by severity, so per-widget foreground colors and theme foregrounds are skipped, like Custom Command's preserve-colors mode. Press `l` to make the widget a link to the status page (`https://status.claude.com`), in terminals that support OSC 8 hyperlinks.
3333
- **Voice Status** - Show whether Claude Code voice input is enabled. It can render as an icon, icon plus text, plain text, or `voice on/off`, with optional Nerd Font microphone icons.
34+
- **Fast Mode** - Show whether Claude Code's fast mode is on, from the status line's `fast_mode` field. It can render as icon plus text (`⚡ on` / `⚡ off`, the default), an icon with a state dot, plain text, or `fast on/off`, with optional Nerd Font lightning icons. It can hide while fast mode is off, and shows nothing on Claude Code versions that don't report fast mode.
3435
- **Sandbox Status** - Show the effective `sandbox.enabled` value from Claude Code's layered project and user settings. It can render as a glyph, `SB: ON/OFF`, or `Sandbox: ON/OFF`, with optional Nerd Font lock icons. The value is refreshed after `/sandbox` changes, but is best effort when managed or CLI settings override files or sandbox initialization fails.
3536
- **Thinking Effort** / **Vim Mode** / **Skills** - Show Claude thinking effort, the current vim editing mode, and skill activity from hook data. Thinking Effort reads live status JSON first, then `/model` or `/effort` transcript output, then settings fallback; it supports `low`, `medium`, `high`, `xhigh`, and `max`, shows `default` when no effort is set, and marks unknown future values with `?`. Claude Code reports Ultracode as `xhigh` in status line data; it does not expose Ultracode as a separate effort level.
3637
- **Session Clock** / **Session Cost** / **Session Cost Rate** - Show elapsed session time, the current session cost in USD, and that cost per hour (`Rate: $5.00/hr`). Session Cost Rate divides by the time Claude spent working (API time) by default, or by the whole session with clock time on, and shows nothing until a full minute of that time has passed.
@@ -61,7 +62,7 @@ ccstatusline --version
6162
- **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. 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.
6263
- **Compaction Counter** - Show how many context compactions have been detected in the current session by scanning transcript compaction markers. It can render as icon plus number, text plus number, or number-only, and can hide while the count is zero. Two optional, independent per-item add-ons toggle extra detail: a trigger split (`↻ 3 (2 auto, 1 manual)`; a compaction whose trigger is missing or unrecognized is bucketed as `unknown`) and tokens reclaimed (`↻ 3 ↓887.0k`, each compaction's `preTokens - postTokens` floored at 0 and summed, shown only when greater than 0 — so very old transcripts predating the `postTokens` field display nothing). Its value selector can instead render the total count, one trigger count (`auto`, `manual`, or `unknown`), or reclaimed tokens as a standalone value; hide-when-zero applies to the selected value.
6364
- **Spend Limit Usage** / **Spend Limit Amount** - For developers behind a Claude apps gateway with spend limits (Claude Code 2.1.251 or later). Spend Limit Usage shows the share of the limit used, as a percentage or bar, and can show the remaining share instead. Spend Limit Amount shows `$314.12 / $500.00` and renders nothing until the gateway reports the dollar figures (Claude Code and gateway 2.1.284 or later). Both read `rate_limits.spend_limit` from the status line payload only and never call the usage API; without a spend limit they render nothing.
64-
- **Block Usage** / **Weekly Usage** / **Weekly Sonnet Usage** / **Weekly Opus Usage** / **Weekly Fable Usage** / **Extra Usage Utilization** / **Extra Usage Remaining** / **Extra Usage Used** / **Extra Usage Daily Budget** / **Block Timer** / **Block Reset Timer** / **Weekly Reset Timer** - Show usage percentages, monthly pay-as-you-go overage usage, and current block/reset timing. Block Usage and the all-model Weekly Usage read the legacy flat API buckets when available and fall back per field to `session` and `weekly_all` entries in the newer `limits[]` response. The per-model widgets prefer `weekly_scoped` entries for Sonnet, Opus, and Fable, with legacy Sonnet/Opus buckets as fallbacks; Weekly Fable Usage renders nothing when the API reports no Fable quota. Block Usage, the weekly percentage widgets, and Extra Usage Utilization can show either used or remaining percentage in every display mode. Block and weekly usage bars can also show a time cursor. Extra usage widgets accept known extra-usage state as complete when an account has no monthly limit configured, avoid repeated refetches and stale `[Timeout]` output, and format amounts with the API-reported billing currency when available. On accounts with no plan limits (usage-based Enterprise plans), extra usage is all of the account's spend rather than overage beyond a plan; the label editor can change the Extra Usage widgets' `Overage` labels to read `Spend`. Before the first charge of the month the API reports no utilization, so Extra Usage Utilization works it out from the amount spent and the monthly limit. Extra Usage Daily Budget divides what's left of the monthly limit by the days left in the month, today included, optionally skipping future weekend days (today always counts). It requires a monthly limit and amount spent, and displays zero once the limit is exhausted. Days are UTC days, since monthly limits reset at 00:00 UTC on the 1st. Reset timers can show remaining time, progress, or exact reset date/time with timezone and locale controls; while reset data is still arriving at startup, they show a labeled loading placeholder instead of a transient API error.
65+
- **Block Usage** / **Weekly Usage** / **Weekly Sonnet Usage** / **Weekly Opus Usage** / **Weekly Fable Usage** / **Extra Usage Utilization** / **Extra Usage Remaining** / **Extra Usage Used** / **Extra Usage Limit** / **Extra Usage Daily Budget** / **Block Timer** / **Block Reset Timer** / **Weekly Reset Timer** - Show usage percentages, monthly pay-as-you-go overage usage, and current block/reset timing. Block Usage and the all-model Weekly Usage read the legacy flat API buckets when available and fall back per field to `session` and `weekly_all` entries in the newer `limits[]` response. The per-model widgets prefer `weekly_scoped` entries for Sonnet, Opus, and Fable, with legacy Sonnet/Opus buckets as fallbacks; Weekly Fable Usage renders nothing when the API reports no Fable quota. Block Usage, the weekly percentage widgets, and Extra Usage Utilization can show either used or remaining percentage in every display mode. Block and weekly usage bars can also show a time cursor. Extra usage widgets accept known extra-usage state as complete when an account has no monthly limit configured, avoid repeated refetches and stale `[Timeout]` output, and format amounts with the API-reported billing currency when available. On accounts with no plan limits (usage-based Enterprise plans), extra usage is all of the account's spend rather than overage beyond a plan; the label editor can change the Extra Usage widgets' `Overage` labels to read `Spend`. Extra Usage Limit shows the monthly limit itself, or `none` when extra usage is on without a monthly limit. Before the first charge of the month the API reports no utilization, so Extra Usage Utilization works it out from the amount spent and the monthly limit. Extra Usage Daily Budget divides what's left of the monthly limit by the days left in the month, today included, optionally skipping future weekend days (today always counts). It requires a monthly limit and amount spent, and displays zero once the limit is exhausted. Days are UTC days, since monthly limits reset at 00:00 UTC on the 1st. Reset timers can show remaining time, progress, or exact reset date/time with timezone and locale controls; while reset data is still arriving at startup, they show a labeled loading placeholder instead of a transient API error.
6566
- **Block Forecast** / **Block Limit Timer** - Forecast the 5-hour block from the recent pace. Block Forecast shows the projected usage at reset (`→83.2%`), and Block Limit Timer shows how long until 100% (`Limit in: 1hr 13m`) when that comes before the reset. Each renders nothing until it has something to show, so they sit naturally right after the 5-hour usage widget. The pace is measured over the last 30 minutes from readings saved in `~/.cache/ccstatusline/session-usage-history.json`, kept separately for each Claude config directory and each login within it. A stretch with no status-line updates (the machine asleep, or usage on another device) is spread evenly across the gap, and a new block can be forecast once it is 10 minutes old.
6667

6768
An explicit per-model quota at 0% is shown even when its reset timestamp is still missing; the time cursor appears only once a usable window is available. Weekly Fable Usage uses the label `Weekly Fable:` and stays empty when the API reports no Fable quota.
@@ -316,6 +317,7 @@ Widget-specific shortcuts:
316317
- **Sandbox Status**: `f` cycle glyph/text/word format, `n` toggle Nerd Font lock icons in glyph mode
317318
- **Claude Status**: `h` toggle the 48-hour incident-history strip, `l` toggle the link to the status page
318319
- **Voice Status**: `f` cycle format, `n` toggle Nerd Font microphone icons
320+
- **Fast Mode**: `f` cycle format, `n` toggle Nerd Font lightning icons
319321
- **Current Working Dir**: `h` home abbreviation, `s` segment editor, `f` fish-style path, `g` optional leading glyph (off by default; pair with raw value to replace the `cwd:` label with the glyph)
320322
- **Skills**: `v` cycle view mode, `l` edit list limit in list mode
321323
- **Input Speed / Output Speed / Total Speed**: `w` edit the rolling window in seconds
@@ -347,6 +349,7 @@ Supported states by widget family:
347349
- **Block Timer**: `no-data` hides the `0hr 0m` / empty-bar display when no block is active
348350
- **Block Reset Timer / Weekly Reset Timer**: `no-data` hides both the `[Loading]` placeholder and the usage-error placeholders while no reset window is available
349351
- **Block Reset Timer**: `under-limit` hides the timer until the 5-hour block's usage reaches 100%, so the reset countdown appears only once the block's limit is hit. It reads the block's raw percent from the usage API, so a usage percent shown as `100%` after rounding 99.7% still counts as under the limit. The status payload's percent comes from that session's last response and stops moving while the session sits idle, so it's used only when the API can't be reached. The API's answer is cached for 3 minutes and shared by every session. A cached answer from a block that has already reset (the cache outliving the reset, or the API failing since) is ignored, and the payload's percent stands in until a fresh one arrives.
352+
- **Block Usage**: `at-limit` hides the percent once the 5-hour block's usage reaches 100%, by the same check as Block Reset Timer's `under-limit`, so with both on the reset countdown takes the percent's place at the limit, in the same render. With `under-limit` on, the timer appears only there, so a label like `5h reset ` (set with `e`) keeps the 5h label in front of the countdown
350353
- **Input/Output/Total Speed**: `no-data` hides the `—` placeholder when no speed data exists
351354
- **Output Style**: `default-value` hides the widget when the style is `default`
352355
- **Compaction Counter**: `zero` hides the counter before any compaction occurs

‎src/tui/App.tsx‎

Lines changed: 46 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import Gradient from 'ink-gradient';
1010
import React, {
1111
useCallback,
1212
useEffect,
13+
useMemo,
1314
useRef,
1415
useState
1516
} from 'react';
@@ -346,14 +347,15 @@ function clearInstallationMetadata(settings: Settings | null): Settings | null {
346347
return next;
347348
}
348349

349-
export function getCurrentInstallation(
350-
isClaudeInstalled: boolean,
350+
// Claude Code runs ccstatusline, so until its status line command is read, the saved
351+
// metadata describes the install
352+
export function classifyInstalledStatusLine(
351353
existingStatusLine: string | null,
352-
settings: Settings
354+
savedInstallation: InstallationMetadata | undefined
353355
): InstallationMetadata {
354-
return isClaudeInstalled && !existingStatusLine && settings.installation
355-
? settings.installation
356-
: classifyInstallation(existingStatusLine, settings.installation);
356+
return !existingStatusLine && savedInstallation
357+
? savedInstallation
358+
: classifyInstallation(existingStatusLine, savedInstallation);
357359
}
358360

359361
function trimTrailingSeparators(filePath: string): string {
@@ -646,7 +648,9 @@ export const App: React.FC = () => {
646648
}
647649
// Global save shortcut
648650
if (key.ctrl && input === 's' && settings && screen !== 'confirm') {
649-
const installation = getCurrentInstallation(isClaudeInstalled, existingStatusLine, settings);
651+
const installation = isClaudeInstalled
652+
? classifyInstalledStatusLine(existingStatusLine, settings.installation)
653+
: classifyInstallation(existingStatusLine, settings.installation);
650654
const activeCommand = installation.method === 'pinned' || installation.method === 'self-managed'
651655
? inspectActiveGlobalCommand({ commandAvailability })
652656
: null;
@@ -811,9 +815,9 @@ export const App: React.FC = () => {
811815

812816
const handleUpdateCheck = useCallback(() => {
813817
setUpdateCheckerState({ status: 'checking' });
814-
const installation = settings
815-
? getCurrentInstallation(isClaudeInstalled, existingStatusLine, settings)
816-
: classifyInstallation(existingStatusLine, undefined);
818+
const installation = isClaudeInstalled
819+
? classifyInstalledStatusLine(existingStatusLine, settings?.installation)
820+
: classifyInstallation(existingStatusLine, settings?.installation);
817821
const activeCommand = installation.method === 'pinned' || installation.method === 'self-managed'
818822
? inspectActiveGlobalCommand({ commandAvailability })
819823
: null;
@@ -936,22 +940,44 @@ export const App: React.FC = () => {
936940
setScreen('main');
937941
}, [importValidation, settings]);
938942

939-
if (!settings || !hasLoadedClaudeStatus || !hasLoadedInstalledState) {
943+
const savedInstallation = settings?.installation;
944+
const hasLoaded = settings !== null && hasLoadedClaudeStatus && hasLoadedInstalledState;
945+
// Looking up the global ccstatusline command runs `which -a`, `npm prefix -g` and
946+
// `bun pm bin -g`, which block for a few hundred ms. Editor keys redraw App (the live
947+
// preview, each widget edit), so the lookups run only when the installation changes:
948+
// once loading finishes, and after an install, update or uninstall here, since each
949+
// changes the installation metadata or Claude's status line. Null while loading.
950+
const installationState = useMemo(() => {
951+
if (!hasLoaded) {
952+
return null;
953+
}
954+
955+
const currentInstallation = isClaudeInstalled
956+
? classifyInstalledStatusLine(existingStatusLine, savedInstallation)
957+
: classifyInstallation(existingStatusLine, savedInstallation);
958+
const activeGlobalCommand = currentInstallation.method === 'pinned' || currentInstallation.method === 'self-managed'
959+
? inspectActiveGlobalCommand({ commandAvailability })
960+
: null;
961+
const effectiveInstallation = getPathInferredInstallation(currentInstallation, activeGlobalCommand);
962+
const pinnedRelaunchCommand = effectiveInstallation.method === 'pinned'
963+
&& effectiveInstallation.packageManager !== 'unknown'
964+
? getPinnedGlobalRelaunchCommand(effectiveInstallation.packageManager)
965+
: null;
966+
967+
return { activeGlobalCommand, effectiveInstallation, pinnedRelaunchCommand };
968+
}, [commandAvailability, existingStatusLine, hasLoaded, isClaudeInstalled, savedInstallation]);
969+
970+
if (!settings || !installationState) {
940971
return <Text>Loading settings...</Text>;
941972
}
942973

943974
const runningVersion = getPackageVersion();
944-
const currentInstallation = getCurrentInstallation(isClaudeInstalled, existingStatusLine, settings);
945-
const activeGlobalCommand = currentInstallation.method === 'pinned' || currentInstallation.method === 'self-managed'
946-
? inspectActiveGlobalCommand({ commandAvailability })
947-
: null;
948-
const effectiveInstallation = getPathInferredInstallation(currentInstallation, activeGlobalCommand);
949-
const pinnedVersionMismatch = effectiveInstallation.method === 'pinned'
950-
&& effectiveInstallation.packageManager !== 'unknown'
975+
const { activeGlobalCommand, effectiveInstallation, pinnedRelaunchCommand } = installationState;
976+
const pinnedVersionMismatch = pinnedRelaunchCommand
951977
? getPinnedVersionMismatch(
952978
effectiveInstallation,
953979
runningVersion,
954-
getPinnedGlobalRelaunchCommand(effectiveInstallation.packageManager),
980+
pinnedRelaunchCommand,
955981
versionInstalledThisSession
956982
)
957983
: null;
@@ -1246,7 +1272,7 @@ export const App: React.FC = () => {
12461272
};
12471273

12481274
const configWarning = buildConfigLoadWarning(configLoadError);
1249-
// Label drafts affect only the preview until Enter accepts the edit.
1275+
// Label drafts and the picker's highlighted widget affect only the preview until Enter accepts them.
12501276
const previewLines = screen === 'items' && previewWidgets
12511277
? settings.lines.map((line, index) => index === selectedLine ? previewWidgets : line)
12521278
: settings.lines;

0 commit comments

Comments
 (0)