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
14 changes: 8 additions & 6 deletions docs/USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -316,6 +316,8 @@ Text editors use a blinking bar cursor so trailing spaces remain visible. Label

The keybind footer in the TUI only shows shortcuts that apply to the currently selected widget. Plain-letter shortcuts ignore Ctrl and Alt/Option modifiers, so combinations such as `Ctrl+S` do not also trigger the letter action.

All bar widgets offer a 16-cell **line bar** mode using `━` for filled cells and `─` for empty cells, with no brackets and the widget's numeric values alongside it. It is the last mode before the `p` cycle returns to its starting mode. Fill inversion and time cursors remain available on widgets that support them. Existing modes retain their appearance.

Widget-specific shortcuts:
- **Remote Control Status**: `e` edits the label in `label-check` and `label-mark` formats when raw value is off. The override is shared by these two formats; Tab in the label editor restores `remote `.
- **Glyph widgets** (Git Branch, Git Worktree, Git Worktree Mode, Git Staged, Git Unstaged, Git Untracked, Git Conflicts, Git Ahead/Behind, Git Status, Git Changes, Git Insertions, Git Deletions, Git Clean Status, Git Is Fork, JJ Revision, JJ Bookmarks, JJ Workspace, JJ Changes, JJ Insertions, JJ Deletions, Remote Control Status with Nerd Font icons): `g` set custom glyphs for the widget's symbols; Backspace in the editor renders without one, Shift+Tab toggles every symbol between none and default, and multi-symbol widgets (Ahead/Behind, Status, Conflicts, Changes, Clean Status, Remote Control Status on/off) edit each part in one list
Expand All @@ -326,16 +328,16 @@ Widget-specific shortcuts:
- **Git remote widgets** (`Git Origin*` / `Git Upstream*`): `l` toggle clickable repo links
- **Git Origin Owner/Repo**: `o` show only the owner when the repo is a fork
- **Git Conflicts**: `z` toggles how a visible conflict-free tree renders (`⚠0` or the clean glyph); `g` edits the conflict and clean glyphs
- **Context % widgets**: `u` toggle used vs remaining display, `p` cycle percentage/short bar/short bar only
- **Context % widgets**: `u` toggle used vs remaining display, `p` cycle percentage/short bar/short bar only/line bar
- **Session Cost Rate**: `t` switch between active time (how long Claude spent working, the default) and clock time (the whole session)
- **Block Usage / Weekly Usage / Weekly Sonnet Usage / Weekly Opus Usage / Weekly Fable Usage / Spend Limit Usage / Extra Usage Utilization**: `p` cycle percentage/full bar/medium bar/short bar/short bar only and `u` switch between used and remaining percentage in every display mode. The editor row labels the current direction as `used` or `remaining`, while the `u` helper names the direction it will switch to. Block and weekly usage widgets use `t` to toggle the time cursor in bar modes.
- **Block Usage / Weekly Usage / Weekly Sonnet Usage / Weekly Opus Usage / Weekly Fable Usage / Spend Limit Usage / Extra Usage Utilization**: `p` cycle percentage/full bar/medium bar/short bar/short bar only/line bar and `u` switch between used and remaining percentage in every display mode. The editor row labels the current direction as `used` or `remaining`, while the `u` helper names the direction it will switch to. Block and weekly usage widgets use `t` to toggle the time cursor in bar modes.
- **Extra Usage Daily Budget**: `w` toggle counting weekdays only (Saturday and Sunday, UTC, are skipped; today always counts)
- **Block Forecast**: `u` switch between projected used and remaining percentage
- **Block Limit Timer / Weekly Limit Timer / Weekly Fable Limit Timer**: `s` toggle compact time
- **Block Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time, `v` invert fill in progress mode
- **Block Reset Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode
- **Weekly Reset Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `o` toggle hours-only in time mode, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode
- **Context Bar**: `p` cycle medium/full/short/short-only progress bar
- **Block Timer**: `p` cycle time/full bar/medium bar/short bar/short bar only/line bar, `s` toggle compact time, `v` invert fill in progress mode
- **Block Reset Timer**: `p` cycle time/full bar/medium bar/short bar/short bar only/line bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode
- **Weekly Reset Timer**: `p` cycle time/full bar/medium bar/short bar/short bar only/line bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `o` toggle hours-only in time mode, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode
- **Context Bar**: `p` cycle medium/full/short/short-only/line 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), `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
Expand Down
13 changes: 5 additions & 8 deletions src/widgets/BlockResetTimer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ import {
LOCALE_EDITOR_ACTION,
renderUsageLocaleEditor
} from './shared/locale-editor';
import { makeTimerProgressBar } from './shared/progress-bar';
import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
import {
TIMEZONE_EDITOR_ACTION,
Expand All @@ -39,7 +38,6 @@ import {
getUsageDisplayMode,
getUsageDisplayModifierText,
getUsageLocale,
getUsageProgressBarWidth,
getUsageTimerCustomKeybinds,
getUsageTimezone,
isAtSessionLimit,
Expand All @@ -50,6 +48,7 @@ import {
isUsageProgressMode,
isUsageSliderMode,
makeSliderBar,
renderUsageProgressBar,
toggleUsageCompact,
toggleUsageDateMode,
toggleUsageHourFormat,
Expand Down Expand Up @@ -118,9 +117,8 @@ export class BlockResetTimerWidget implements Widget {
const previewPercent = inverted ? 90.0 : 10.0;

if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const progressBar = makeTimerProgressBar(previewPercent, barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${progressBar}] ${formatPercent(previewPercent, format)}`);
const progressBar = renderUsageProgressBar(previewPercent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${progressBar} ${formatPercent(previewPercent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down Expand Up @@ -164,10 +162,9 @@ export class BlockResetTimerWidget implements Widget {
}

if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const percent = inverted ? window.remainingPercent : window.elapsedPercent;
const progressBar = makeTimerProgressBar(percent, barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${progressBar}] ${formatPercent(percent, format)}`);
const progressBar = renderUsageProgressBar(percent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${progressBar} ${formatPercent(percent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down
18 changes: 7 additions & 11 deletions src/widgets/BlockTimer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,19 +17,18 @@ import {
} from '../utils/usage';

import { isHidden } from './shared/hideable';
import { makeTimerProgressBar } from './shared/progress-bar';
import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
import {
cycleUsageDisplayMode,
getUsageDisplayMode,
getUsageDisplayModifierText,
getUsageProgressBarWidth,
getUsageTimerCustomKeybinds,
isUsageCompact,
isUsageInverted,
isUsageProgressMode,
isUsageSliderMode,
makeSliderBar,
renderUsageProgressBar,
toggleUsageCompact,
toggleUsageInverted
} from './shared/usage-display';
Expand Down Expand Up @@ -82,9 +81,8 @@ export class BlockTimerWidget implements Widget {
const previewPercent = inverted ? 26.1 : 73.9;

if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const progressBar = makeTimerProgressBar(previewPercent, barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${progressBar}] ${formatPercent(previewPercent, format)}`);
const progressBar = renderUsageProgressBar(previewPercent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${progressBar} ${formatPercent(previewPercent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand All @@ -108,9 +106,8 @@ export class BlockTimerWidget implements Widget {

const emptyPercent = formatPercent(0, format);
if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const emptyBar = '░'.repeat(barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${emptyBar}] ${emptyPercent}`);
const emptyBar = renderUsageProgressBar(0, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${emptyBar} ${emptyPercent}`);
}

if (isUsageSliderMode(displayMode)) {
Expand All @@ -125,10 +122,9 @@ export class BlockTimerWidget implements Widget {
}

if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const percent = inverted ? window.remainingPercent : window.elapsedPercent;
const progressBar = makeTimerProgressBar(percent, barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${progressBar}] ${formatPercent(percent, format)}`);
const progressBar = renderUsageProgressBar(percent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${progressBar} ${formatPercent(percent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down
17 changes: 12 additions & 5 deletions src/widgets/ContextBar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,17 @@ import {
import { formatTokens } from '../utils/renderer';
import { makeUsageProgressBar } from '../utils/usage';

import { makeLineProgressBar } from './shared/progress-bar';
import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
import { makeSliderBar } from './shared/usage-display';

const LABEL = 'Context: ';

type DisplayMode = 'progress' | 'progress-short' | 'slider' | 'slider-only';
type DisplayMode = 'progress' | 'progress-short' | 'slider' | 'slider-only' | 'line';

function getDisplayMode(item: WidgetItem): DisplayMode {
const mode = item.metadata?.display;
if (mode === 'progress' || mode === 'slider' || mode === 'slider-only') {
if (mode === 'progress' || mode === 'slider' || mode === 'slider-only' || mode === 'line') {
return mode;
}
return 'progress-short';
Expand All @@ -54,6 +55,8 @@ export class ContextBarWidget implements Widget {
modifiers.push('short bar');
} else if (mode === 'slider-only') {
modifiers.push('short bar only');
} else if (mode === 'line') {
modifiers.push('line bar');
}

return {
Expand All @@ -74,7 +77,9 @@ export class ContextBarWidget implements Widget {
? 'slider'
: currentMode === 'slider'
? 'slider-only'
: 'progress-short';
: currentMode === 'slider-only'
? 'line'
: 'progress-short';

return {
...item,
Expand All @@ -100,7 +105,8 @@ export class ContextBarWidget implements Widget {
return formatRawOrLabeledValue(item, this.getLabelPrefix(), sliderDisplay);
}
const barWidth = displayMode === 'progress' ? 32 : 16;
const previewDisplay = `${makeUsageProgressBar(25, barWidth)} ${usedDisplay}/${totalDisplay} (${percentDisplay})`;
const previewBar = displayMode === 'line' ? makeLineProgressBar(25) : makeUsageProgressBar(25, barWidth);
const previewDisplay = `${previewBar} ${usedDisplay}/${totalDisplay} (${percentDisplay})`;
return formatRawOrLabeledValue(item, this.getLabelPrefix(), previewDisplay);
}

Expand Down Expand Up @@ -131,7 +137,8 @@ export class ContextBarWidget implements Widget {
}

const barWidth = displayMode === 'progress' ? 32 : 16;
const display = `${makeUsageProgressBar(clampedPercent, barWidth)} ${usedDisplay}/${totalDisplay} (${percentDisplay})`;
const bar = displayMode === 'line' ? makeLineProgressBar(clampedPercent) : makeUsageProgressBar(clampedPercent, barWidth);
const display = `${bar} ${usedDisplay}/${totalDisplay} (${percentDisplay})`;

return formatRawOrLabeledValue(item, this.getLabelPrefix(), display);
}
Expand Down
13 changes: 5 additions & 8 deletions src/widgets/ExtraUsageUtilization.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,19 +18,18 @@ import { getUsageErrorMessage } from '../utils/usage';

import { EXTRA_USAGE_DISABLED_HIDEABLE_STATE } from './shared/extra-usage-disabled';
import { isHidden } from './shared/hideable';
import { makeTimerProgressBar } from './shared/progress-bar';
import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
import {
USAGE_NO_DATA_HIDEABLE_STATE,
cycleUsageDisplayMode,
getUsageDisplayMode,
getUsageDisplayModifierText,
getUsagePercentCustomKeybinds,
getUsageProgressBarWidth,
isUsageInverted,
isUsageProgressMode,
isUsageSliderMode,
makeSliderBar,
renderUsageProgressBar,
toggleUsageInverted
} from './shared/usage-display';

Expand Down Expand Up @@ -87,9 +86,8 @@ export class ExtraUsageUtilizationWidget implements Widget {
const renderedPercent = inverted ? 100 - previewPercent : previewPercent;

if (isUsageProgressMode(displayMode)) {
const width = getUsageProgressBarWidth(displayMode);
const progressBar = makeTimerProgressBar(renderedPercent, width);
return formatRawOrLabeledValue(item, this.getLabelPrefix(), `[${progressBar}] ${formatPercent(renderedPercent, format)}`);
const progressBar = renderUsageProgressBar(renderedPercent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(), `${progressBar} ${formatPercent(renderedPercent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down Expand Up @@ -122,9 +120,8 @@ export class ExtraUsageUtilizationWidget implements Widget {
const renderedPercent = inverted ? 100 - percent : percent;

if (isUsageProgressMode(displayMode)) {
const width = getUsageProgressBarWidth(displayMode);
const progressBar = makeTimerProgressBar(renderedPercent, width);
return formatRawOrLabeledValue(item, this.getLabelPrefix(), `[${progressBar}] ${formatPercent(renderedPercent, format)}`);
const progressBar = renderUsageProgressBar(renderedPercent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(), `${progressBar} ${formatPercent(renderedPercent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down
15 changes: 7 additions & 8 deletions src/widgets/WeeklyResetTimer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ import {
isMetadataFlagEnabled,
toggleMetadataFlag
} from './shared/metadata';
import { makeTimerProgressBar } from './shared/progress-bar';
import { formatRawOrLabeledValue } from './shared/raw-or-labeled';
import {
TIMEZONE_EDITOR_ACTION,
Expand All @@ -43,7 +42,6 @@ import {
getUsageDisplayMode,
getUsageLocale,
getUsageLocaleModifier,
getUsageProgressBarWidth,
getUsageTimerCustomKeybinds,
getUsageTimezone,
getUsageTimezoneModifier,
Expand All @@ -55,6 +53,7 @@ import {
isUsageSliderMode,
isUsageWeekdayEnabled,
makeSliderBar,
renderUsageProgressBar,
toggleUsageCompact,
toggleUsageDateMode,
toggleUsageHourFormat,
Expand Down Expand Up @@ -91,6 +90,8 @@ function getWeeklyResetModifierText(item: WidgetItem): string | undefined {
modifiers.push('short bar');
} else if (displayMode === 'slider-only') {
modifiers.push('short bar only');
} else if (displayMode === 'line') {
modifiers.push('line bar');
}

if (isUsageInverted(item)) {
Expand Down Expand Up @@ -195,9 +196,8 @@ export class WeeklyResetTimerWidget implements Widget {
const previewPercent = inverted ? 90.0 : 10.0;

if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const progressBar = makeTimerProgressBar(previewPercent, barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${progressBar}] ${formatPercent(previewPercent, format)}`);
const progressBar = renderUsageProgressBar(previewPercent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${progressBar} ${formatPercent(previewPercent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down Expand Up @@ -243,10 +243,9 @@ export class WeeklyResetTimerWidget implements Widget {
}

if (isUsageProgressMode(displayMode)) {
const barWidth = getUsageProgressBarWidth(displayMode);
const percent = inverted ? window.remainingPercent : window.elapsedPercent;
const progressBar = makeTimerProgressBar(percent, barWidth);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `[${progressBar}] ${formatPercent(percent, format)}`);
const progressBar = renderUsageProgressBar(percent, displayMode);
return formatRawOrLabeledValue(item, this.getLabelPrefix(item), `${progressBar} ${formatPercent(percent, format)}`);
}

if (isUsageSliderMode(displayMode)) {
Expand Down
25 changes: 24 additions & 1 deletion src/widgets/__tests__/ContextBar.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -161,11 +161,34 @@ describe('ContextBarWidget', () => {
const second = widget.handleEditorAction('toggle-progress', first ?? base);
const third = widget.handleEditorAction('toggle-progress', second ?? base);
const fourth = widget.handleEditorAction('toggle-progress', third ?? base);
const fifth = widget.handleEditorAction('toggle-progress', fourth ?? base);

expect(first?.metadata?.display).toBe('progress');
expect(second?.metadata?.display).toBe('slider');
expect(third?.metadata?.display).toBe('slider-only');
expect(fourth?.metadata?.display).toBe('progress-short');
expect(fourth?.metadata?.display).toBe('line');
expect(fifth?.metadata?.display).toBe('progress-short');
});

it('renders a thin line bar in line mode', () => {
const context: RenderContext = {
data: {
context_window: {
context_window_size: 200000,
current_usage: {
input_tokens: 20000,
output_tokens: 10000,
cache_creation_input_tokens: 5000,
cache_read_input_tokens: 5000
}
}
}
};
const item: WidgetItem = { id: 'ctx', type: 'context-bar', metadata: { display: 'line' } };
const widget = new ContextBarWidget();

expect(widget.render(item, context, DEFAULT_SETTINGS)).toBe(`Context: ${'━'.repeat(2)}${'─'.repeat(14)} 30k/200k (15%)`);
expect(widget.getEditorDisplay(item).modifierText).toBe('(line bar)');
});

it('formats context preview samples with the selected styles', () => {
Expand Down
Loading
Loading