@thegitai/cli 1.0.0-preview.41 → 1.0.0-preview.42

package/README.md

@@ -53,8 +53,8 @@ is required. Tabs used by the agent join a TheGitAI tab group in an existing
 window. The conversation stays in your terminal.
 
 Default mode asks before using a website and can remember that site for the
-session. Auto-Accept allows browser actions; Plan mode reads pages without
-clicking, typing, or navigating. Use Stop/Resume in the extension popup to
+session. Bypass all permissions allows browser actions; Plan mode reads pages
+without clicking, typing, or navigating. Use Stop/Resume in the extension popup to
 pause browser control, or Disable to disconnect it. Chrome's protected pages,
 including browser settings and extension management, cannot be controlled.
 
@@ -76,8 +76,9 @@ Multi-select questions toggle choices. The last question has an explicit
 the form; **Ctrl+C** cancels the whole turn.
 
 Answers return to the same turn, and completed question/answer records remain
-readable when the session is resumed. Default, Auto-Accept, and Plan modes all
-support the form; Auto-Accept does not choose answers for you.
+readable when the session is resumed. Default, Bypass all permissions, and Plan
+modes all support the form; Bypass all permissions does not choose answers for
+you.
 
 ## Visible to-do list
 

package/dist/src/agent-mode.js

@@ -145,8 +145,31 @@ export function buildPlanModeToolBlockedResult(toolName, action = 'Plan mode is
 }
 export function agentModeLabel(mode) {
     if (mode === 'auto-accept')
-        return 'Auto-Accept';
+        return 'Bypass all permissions';
     if (mode === 'plan')
         return 'Plan · read-only';
+    return 'Default · asks to edit & run unless permitted';
+}
+export function agentModeLabelTiers(mode) {
+    if (mode === 'default') {
+        return [agentModeLabel(mode), 'Default · asks to edit & run'];
+    }
+    return [agentModeLabel(mode)];
+}
+export function agentModeShortLabel(mode) {
+    if (mode === 'auto-accept')
+        return 'Bypass';
+    if (mode === 'plan')
+        return 'Plan';
     return 'Default';
 }
+export function agentModeColor(mode) {
+    if (mode === 'auto-accept')
+        return 'red';
+    if (mode === 'plan')
+        return 'yellow';
+    return 'cyan';
+}
+export function agentModeCycleSequence() {
+    return AGENT_MODES.map(agentModeShortLabel).join(' → ');
+}

package/dist/src/api/http.js

@@ -7,12 +7,14 @@ export class ServerApiError extends Error {
     status;
     traceId;
     code;
-    constructor(message, status, traceId, code = '') {
+    details;
+    constructor(message, status, traceId, code = '', details = {}) {
         super(traceId ? `${message}\nTrace ID: ${traceId}` : message);
         this.name = 'ServerApiError';
         this.status = status;
         this.traceId = traceId;
         this.code = code;
+        this.details = details;
     }
 }
 export function createTraceId() {
@@ -187,6 +189,8 @@ export function gatewayFailureCategory(error) {
         return 'connection_error';
     if (!(error instanceof ServerApiError))
         return null;
+    if (isQuotaExceededError(error))
+        return 'quota_exceeded';
     return error.status in GATEWAY_STATUS_MESSAGES ? 'gateway_error' : null;
 }
 export async function readJsonResponse(response) {
@@ -208,6 +212,26 @@ export function failureMessage(data, status) {
 export function failureCode(data) {
     return typeof data?.error?.code === 'string' ? data.error.code : '';
 }
+export function failureDetails(data) {
+    const error = data?.error;
+    if (!error || typeof error !== 'object')
+        return {};
+    return {
+        ...(typeof error.window === 'string' ? { window: error.window } : {}),
+        ...(typeof error.resetsAt === 'string' ? { resetsAt: error.resetsAt } : {}),
+        ...(typeof error.percentLeft === 'number'
+            ? { percentLeft: error.percentLeft }
+            : {}),
+    };
+}
+export const QUOTA_EXCEEDED_CODE = 'QUOTA_EXCEEDED';
+export function isQuotaExceededError(error) {
+    if (!(error instanceof ServerApiError))
+        return false;
+    if (error.code === QUOTA_EXCEEDED_CODE)
+        return true;
+    return error.status === 429 && !error.code;
+}
 export function isAuthenticationError(error) {
     return error instanceof ServerApiError && error.status === 401;
 }
@@ -218,7 +242,7 @@ export function authenticationErrorMessage(error) {
 }
 export async function readErrorResponse(response, traceId = response.headers.get(TRACE_ID_HEADER) ?? '') {
     const data = await readJsonResponse(response);
-    return new ServerApiError(failureMessage(data, response.status), response.status, traceId, failureCode(data));
+    return new ServerApiError(failureMessage(data, response.status), response.status, traceId, failureCode(data), failureDetails(data));
 }
 export async function authorizedJson({ config, path, method = 'GET', body = null, headers = {}, fetchImpl = globalThis.fetch, timeoutMs = REQUEST_TIMEOUT_MS, }) {
     const trace = createTraceContext();
@@ -235,7 +259,7 @@ export async function authorizedJson({ config, path, method = 'GET', body = null
     });
     const data = await readJsonResponse(response);
     if (!response.ok) {
-        throw new ServerApiError(failureMessage(data, response.status), response.status, trace.traceId, failureCode(data));
+        throw new ServerApiError(failureMessage(data, response.status), response.status, trace.traceId, failureCode(data), failureDetails(data));
     }
     return data;
 }

package/dist/src/help-text.js

@@ -45,24 +45,29 @@ const HELP_MARKDOWN = [
     '',
     '## Options',
     '',
-    '- `-y, --yes` — start in Auto-Accept mode',
+    '- `-y, --yes` — start in Bypass all permissions mode',
     '- `-h, --help` — show this help',
     '- `-v, --version` — print the version and exit',
     '',
     '## Modes',
     '',
-    '- Default — asks before creating, editing or deleting files and before',
-    '  running commands. Each answer can be remembered for the rest of the',
-    '  session; see Safety & approvals.',
-    '- Auto-Accept — approves shell commands and file edits for the session.',
+    '- Default · asks to edit & run unless permitted — asks before creating,',
+    '  editing or deleting files, before running commands, and before touching a',
+    '  website. Each answer can be remembered for the rest of the session, and',
+    '  once it is, Default stops asking for that action; see Safety & approvals.',
+    '- Bypass all permissions — approves every command, file edit, deletion and',
+    '  browser action for the rest of the session, without asking. Shown in red',
+    '  in the footer. Blocked commands stay blocked.',
     '- Plan — read-only; the agent can inspect, ask typed questions, and plan,',
     '  with file-reading shell commands only. It will not edit files or run tests,',
     '  builds, diagnostics, package managers, project code, or network probes.',
-    '- In the TUI, Shift+Tab cycles modes, mouse drag copies transcript/footer text, left-click opens rendered links, right-click copies rendered links or pastes in the sticky composer/footer when no selection is active, double-click copies a word, and triple-click copies a row.',
+    '- In the TUI, press **?** on an empty composer for the keyboard-and-mouse panel. Shift+Tab cycles Default → Bypass → Plan (refused while the agent is working), mouse drag copies transcript/footer text, left-click opens rendered links, right-click copies rendered links or pastes in the sticky composer/footer when no selection is active, double-click copies a word, and triple-click copies a row.',
     '',
     '## Keys & clipboard',
     '',
-    '- **Enter** sends • **Shift+Tab** cycles modes • **Esc** cancels the turn •',
+    '- **?** on an empty composer opens the keyboard-and-mouse panel.',
+    '- **Enter** sends • **Shift+Tab** cycles Default → Bypass → Plan (only',
+    '  between turns) • **Esc** cancels the turn •',
     '  **Ctrl+C** clears the composer or the queued message, and quits once there',
     '  is nothing left to clear. These are the same on macOS, Linux, and Windows.',
     '- **While the agent is working**, Enter queues your message and locks the',

package/dist/src/quota-notice.js

@@ -0,0 +1,35 @@
+import { isQuotaExceededError, ServerApiError } from './api/http.js';
+import { USAGE_WINDOWS, formatUtcMinute, usageWindowLabel } from './usage.js';
+export function buildQuotaNotice(error) {
+    if (!(error instanceof ServerApiError) || !isQuotaExceededError(error)) {
+        return null;
+    }
+    const label = usageWindowLabel(String(error.details.window ?? ''));
+    const inSentence = label.toLowerCase();
+    const resetsAt = error.details.resetsAt ?? null;
+    const lines = [];
+    if (label) {
+        const reset = resetsAt ? formatUtcMinute(resetsAt) : '';
+        lines.push(reset && reset !== 'unknown'
+            ? `You've used your ${inSentence} limit. It resets at ${reset}.`
+            : `You've used your ${inSentence} limit.`);
+    }
+    else {
+        lines.push(firstMessageLine(error));
+    }
+    lines.push(label
+        ? `Run /usage to see your ${otherWindowNames(label)} windows.`
+        : 'Run /usage to see your remaining usage.');
+    return { title: 'Usage limit reached', body: lines.join('\n') };
+}
+function otherWindowNames(usedLabel) {
+    const names = USAGE_WINDOWS.map(([name]) => name)
+        .filter((name) => name !== usedLabel)
+        .map((name) => name.toLowerCase());
+    return names.length > 1
+        ? `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`
+        : (names[0] ?? '');
+}
+function firstMessageLine(error) {
+    return String(error.message ?? '').split('\n')[0]?.trim() || 'Usage limit reached.';
+}

package/dist/src/ui/repl.js

@@ -1,6 +1,6 @@
 import { createRatatuiBridge } from './tui/bridge.js';
 import { bucketActionLabel, } from '../permissions.js';
-import { approvalScrollLimit, buildTuiFrame, formatJobElapsed, formatTodoProgress, pickThinkingFallbackPhrase, renderTranscriptEntryLines, THINKING_FALLBACK_PHRASES, userInputViewportForFrame, } from './tui/build-frame.js';
+import { AGENT_MODE_LOCKED_STATUS, approvalScrollLimit, buildTuiFrame, formatJobElapsed, formatTodoProgress, pickThinkingFallbackPhrase, renderTranscriptEntryLines, THINKING_FALLBACK_PHRASES, userInputViewportForFrame, } from './tui/build-frame.js';
 import { createTerminalTitleController } from './tui/terminal-title.js';
 import { captureTerminalWrites, releaseTerminalWrites, } from './tui/terminal-writes.js';
 export { getSlashCommandSuggestions } from './tui/build-frame.js';
@@ -16,6 +16,7 @@ import { cancelActiveCommand } from '../executor.js';
 import { isTurnFailureMarker } from '../turn-failure-marker.js';
 import { clearCliAuthConfig, logoutFromServer, } from '../api/auth.js';
 import { authenticationErrorMessage, isAuthenticationError, } from '../api/http.js';
+import { buildQuotaNotice } from '../quota-notice.js';
 import { createUserInputPromptState, formatUserInputTranscript, } from './tui/user-input.js';
 import { setCommandOutputHook, withTuiMode } from '../runtime-mode.js';
 import { collectBackgroundJobUiKillMutations, collectBackgroundJobUiOutputMutations, } from '../tool-executor.js';
@@ -76,7 +77,6 @@ const TRANSCRIPT_DIFF_PREVIEW_LINES = 24;
 const WORKING_TOOL_PREVIEW_ITEMS = 4;
 const THINKING_NOTE_PREVIEW_ROWS = 3;
 const WORKING_TOOL_PREVIEW_ROWS = 3;
-const AGENT_MODE_LABEL_WIDTH = 16;
 export const REPORT_ISSUE_URL = 'https://thegit.ai/report';
 export function buildReportTranscriptEntries(openedUrl) {
     return openedUrl
@@ -1105,6 +1105,8 @@ function createInitialShellState(session, serverModels, debugUi) {
         jobsPickerOpen: false,
         modelPickerIndex: getDefaultModelPickerIndex(session.modelId, serverModels.models),
         modelPickerOpen: false,
+        shortcutsOpen: false,
+        transientStatus: null,
         projectRoot: session.rootDir,
         sessionId: session.sessionId,
         showSessionId: debugUi.showSessionId,
@@ -1532,15 +1534,17 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                 void remountTui();
             }, 0);
         };
-        const showTransientStatus = (status) => {
+        const showTransientStatus = (transientStatus) => {
             if (transientStatusTimer) {
                 clearTimeout(transientStatusTimer);
                 transientStatusTimer = null;
             }
-            store.update((current) => ({ ...current, status }));
+            store.update((current) => ({ ...current, transientStatus }));
             transientStatusTimer = setTimeout(() => {
                 transientStatusTimer = null;
-                store.update((current) => current.status === status ? { ...current, status: 'Ready' } : current);
+                store.update((current) => current.transientStatus === transientStatus
+                    ? { ...current, transientStatus: null }
+                    : current);
             }, 2500);
         };
         const terminalTitle = createTerminalTitleController({
@@ -1806,6 +1810,9 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
             setAgentMode(nextAgentMode(session.agentMode));
             scheduleLiveFrameRemount();
         };
+        const reportAgentModeLocked = () => {
+            showTransientStatus(AGENT_MODE_LOCKED_STATUS);
+        };
         const clearLiveFrameRemountTimer = () => {
             if (!liveFrameRemountTimer)
                 return;
@@ -2899,6 +2906,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                     return;
                 const failedTurnAttachments = activeTurnImageAttachments;
                 activeTurnImageAttachments = [];
+                const quotaNotice = cancelled ? null : buildQuotaNotice(error);
                 store.update((current) => ({
                     ...current,
                     activeTurnInput: '',
@@ -2908,7 +2916,11 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                     busySince: null,
                     commandLog: [],
                     imageAttachments: failedTurnAttachments,
-                    status: cancelled ? 'Ready' : 'Turn failed',
+                    status: cancelled
+                        ? 'Ready'
+                        : quotaNotice
+                            ? quotaNotice.title
+                            : 'Turn failed',
                     thinkingTitle: '',
                     thinkingNotes: [],
                     tokenUsage: formatClientTokenUsage(Date.now() - turnStartedAt, latestUsageSummary),
@@ -2927,6 +2939,16 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                     if (!(await saveActiveSession()))
                         return;
                 }
+                else if (quotaNotice) {
+                    appendStaticEntries([
+                        ...turnEntries,
+                        {
+                            body: quotaNotice.body,
+                            kind: 'system',
+                            title: quotaNotice.title,
+                        },
+                    ]);
+                }
                 else {
                     appendStaticEntries(turnEntries);
                     appendError(error.message);
@@ -3090,6 +3112,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
             },
             onCancelTurn: cancelActiveTurn,
             onCycleAgentMode: cycleAgentMode,
+            onAgentModeChangeBlocked: reportAgentModeLocked,
             onCtrlC: handleCtrlC,
             onLinkCopy: handleLinkCopy,
             onLinkOpen: handleLinkOpen,

package/dist/src/ui/tui/build-frame.js

@@ -1,9 +1,10 @@
-import { agentModeLabel } from '../../agent-mode.js';
+import { agentModeColor, agentModeLabelTiers, agentModeShortLabel, } from '../../agent-mode.js';
 import { singleLinePreview, truncate } from '../../utils.js';
 import { formatClientTokenUsage } from '../repl.js';
 import { renderFormattedBodyLines, renderPreformattedBodyLines, } from './markdown-render.js';
 import { displayWidth, line, padToWidth, plainLine, sliceToWidth, span, wrapText, } from './text.js';
 import { isDarkTerminalBackground, mutedColor, mutedStyle } from './terminal-theme.js';
+import { buildShortcutGroups, shortcutsPanelAvailable, } from './shortcuts.js';
 import { buildUserInputOverlayLines, } from './user-input.js';
 import { composerPromptLabel, frameContentWidth, splitComposerInput, } from './composer-layout.js';
 const WORKING_CLOCK_ICON = '◷';
@@ -28,7 +29,10 @@ const APPROVAL_SCROLLBAR_THUMB = '█';
 const APPROVAL_SCROLLBAR_TRACK = '░';
 const THINKING_NOTE_PREVIEW_ROWS = 3;
 const COMPOSER_INPUT_MAX_ROWS = 6;
-const AGENT_MODE_LABEL_WIDTH = 16;
+const FOOTER_HINT_MIN_GAP = 2;
+const FOOTER_HELP_HINT = '? for shortcuts';
+const FOOTER_CANCEL_HINT = 'esc cancels turn';
+const FOOTER_CYCLE_HINT = ' (shift+tab to cycle)';
 const OVERLAY_PANEL_MAX_WIDTH = 86;
 const OVERLAY_PANEL_MARGIN_LINES = 2;
 const OVERLAY_PANEL_MARGIN_MIN_ROWS = 30;
@@ -434,10 +438,14 @@ function tokenUsageLines(usage) {
     }
     return [line(...spans)];
 }
+export const AGENT_MODE_LOCKED_STATUS = 'Mode locked while the agent is working';
 function footerTransientStatus(status) {
     const text = String(status ?? '').trim();
     if (!text)
         return null;
+    if (text === AGENT_MODE_LOCKED_STATUS) {
+        return { color: 'yellow', text, icon: '!' };
+    }
     if (text === 'Copied selection' || text === 'Copied link') {
         return { color: 'green', text, icon: '✓' };
     }
@@ -478,9 +486,39 @@ function todoIndicatorSpans(state) {
         }),
     ];
 }
-function composerFooterLines(state) {
+function composerFooterRightHints(state) {
+    const cancelHint = state.busy && !state.queuedMessage && !state.userInputPrompt
+        ? FOOTER_CANCEL_HINT
+        : '';
+    const helpHint = shortcutsPanelAvailable(state) ? FOOTER_HELP_HINT : '';
+    const tiers = [];
+    if (cancelHint && helpHint)
+        tiers.push(`${cancelHint}  ·  ${helpHint}`);
+    if (cancelHint)
+        tiers.push(cancelHint);
+    if (helpHint)
+        tiers.push(helpHint);
+    tiers.push('');
+    return tiers;
+}
+export function fitComposerFooterRow({ modeLabels, modeLabelFallback, cycleHint, rightHints, leadWidth, tailWidth, contentWidth, }) {
+    const candidates = rightHints.flatMap((rightHint) => (cycleHint ? [cycleHint, ''] : ['']).flatMap((cycle) => modeLabels.map((modeLabel) => ({ modeLabel, cycleHint: cycle, rightHint }))));
+    const hasTail = (rightHint) => Boolean(rightHint) || tailWidth > 0;
+    const rowWidth = (choice, gap) => leadWidth +
+        displayWidth(choice.modeLabel) +
+        displayWidth(choice.cycleHint) +
+        (hasTail(choice.rightHint) ? gap : 0) +
+        displayWidth(choice.rightHint) +
+        tailWidth;
+    const chosen = candidates.find((choice) => rowWidth(choice, FOOTER_HINT_MIN_GAP) <= contentWidth) ?? { modeLabel: modeLabelFallback, cycleHint: '', rightHint: '' };
+    const gap = hasTail(chosen.rightHint)
+        ? Math.max(FOOTER_HINT_MIN_GAP, contentWidth - rowWidth(chosen, 0))
+        : 0;
+    return { ...chosen, gap };
+}
+function composerFooterLines(state, contentWidth) {
     const visibleSessionId = formatPromptSessionIdLabel(state.showSessionId, state.sessionId);
-    const transientStatus = footerTransientStatus(state.status);
+    const transientStatus = footerTransientStatus(state.transientStatus ?? null);
     const lines = [
         line(span('TheGitAI', { color: 'cyan', bold: true }), span(' • ', { color: 'gray', dim: true }), span(formatPromptDirectoryLabel(state.projectRoot), { color: 'cyan' }), ...(transientStatus
             ? [
@@ -498,11 +536,6 @@ function composerFooterLines(state) {
             ? [span(`   ${visibleSessionId}`, { color: 'gray', dim: true })]
             : []), ...backgroundJobIndicatorSpans(state), ...todoIndicatorSpans(state)),
         plainLine(''),
-        plainLine(formatModelLabel(state.currentModelId, state.serverModels), {
-            color: 'cyan',
-            dim: true,
-        }),
-        plainLine(''),
     ];
     if (state.exitConfirmUntil != null) {
         lines.push(plainLine(state.status || 'Press Ctrl+C again to quit.', {
@@ -511,34 +544,36 @@ function composerFooterLines(state) {
         }));
         return lines;
     }
-    const busyHelperText = state.queuedMessage
-        ? 'Enter sends it to the agent • ↑ edit • Esc / Ctrl+C discard'
-        : state.input
-            ? 'Enter queues • Esc cancels turn • Ctrl+C clears draft'
-            : 'Enter queues • Esc / Ctrl+C cancel turn';
-    const helperText = state.userInputPrompt
-        ? 'Answering agent questions • Ctrl+C cancels turn'
-        : state.busy
-            ? busyHelperText
-            : process.platform === 'win32'
-                ? 'Enter sends • Shift+Tab mode • Alt+V image • Esc cancel turn • Ctrl+C clears / quits'
-                : process.platform === 'darwin'
-                    ? 'Enter sends • Shift+Tab mode • Ctrl+V image • Esc cancel turn • Ctrl+C clears / quits'
-                    : 'Enter sends • Shift+Tab mode • Ctrl+V image • Esc cancel turn • Ctrl+C clears / quits';
-    const agentLabel = agentModeLabel(state.agentMode).padEnd(AGENT_MODE_LABEL_WIDTH);
     const tokenUsageText = state.tokenUsage || formatClientTokenUsage(null);
-    const footerMuted = mutedStyle();
-    const footerSpans = [
-        span(helperText, footerMuted),
-        span(' '.repeat(Math.max(1, 8)), footerMuted),
-        span(agentLabel, {
-            color: state.agentMode === 'plan' ? 'yellow' : 'cyan',
-        }),
-        span(tokenUsageText, { color: 'cyan' }),
-    ];
-    lines.push(line(...footerSpans));
+    lines.push(composerFooterModeLine(state, contentWidth, formatModelLabel(state.currentModelId, state.serverModels), tokenUsageText
+        ? displayWidth(tokenUsageText) + FOOTER_USAGE_SEPARATOR.length
+        : 0, tokenUsageText
+        ? [
+            span(FOOTER_USAGE_SEPARATOR, mutedStyle()),
+            span(tokenUsageText, { color: 'cyan' }),
+        ]
+        : []));
     return lines;
 }
+function composerFooterModeLine(state, contentWidth, modelLabel, usageWidth, usageSpans) {
+    const lead = modelLabel ? `${modelLabel}${FOOTER_MODEL_SEPARATOR}` : '';
+    const row = fitComposerFooterRow({
+        modeLabels: agentModeLabelTiers(state.agentMode),
+        modeLabelFallback: agentModeShortLabel(state.agentMode),
+        cycleHint: state.busy ? '' : FOOTER_CYCLE_HINT,
+        rightHints: composerFooterRightHints(state),
+        leadWidth: displayWidth(lead),
+        tailWidth: usageWidth,
+        contentWidth,
+    });
+    const footerMuted = mutedStyle();
+    return line(...(lead ? [span(lead, { color: 'cyan', dim: true })] : []), span(row.modeLabel, {
+        color: agentModeColor(state.agentMode),
+        bold: state.agentMode === 'auto-accept',
+    }), ...(row.cycleHint ? [span(row.cycleHint, footerMuted)] : []), ...(row.gap ? [span(' '.repeat(row.gap), footerMuted)] : []), ...(row.rightHint ? [span(row.rightHint, footerMuted)] : []), ...usageSpans);
+}
+const FOOTER_USAGE_SEPARATOR = '  ';
+const FOOTER_MODEL_SEPARATOR = '   ';
 export function formatJobElapsed(elapsedMs) {
     const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000));
     if (totalSeconds < 60)
@@ -895,6 +930,71 @@ function buildModelPickerPanel(options, selectedIndex, width, availableHeight) {
     body.push(modelPickerDivider(panelWidth), modelPickerPanelSideLine(plainLine(fitLine(hint, innerWidth), { color: 'gray' }), innerWidth), plainLine(`╰${'─'.repeat(panelWidth - 2)}╯`, { color: MODEL_PICKER_BORDER_COLOR }));
     return [...margin, ...body, ...margin];
 }
+const SHORTCUTS_PANEL_MAX_WIDTH = 96;
+const SHORTCUTS_KEY_COLUMN_MIN = 10;
+function shortcutsTopBorder(panelWidth) {
+    const fullTitle = ' TheGitAI - Keyboard & mouse ';
+    const compactTitle = ' Shortcuts ';
+    const title = panelWidth >= fullTitle.length + 4 ? fullTitle : compactTitle;
+    const available = Math.max(0, panelWidth - 2 - [...title].length);
+    const left = Math.floor(available / 2);
+    const right = available - left;
+    return line(span(`╭${'─'.repeat(left)}`, { color: MODEL_PICKER_BORDER_COLOR }), span(title, { color: MODEL_PICKER_ACCENT_COLOR, bold: true }), span(`${'─'.repeat(right)}╮`, { color: MODEL_PICKER_BORDER_COLOR }));
+}
+export function buildShortcutsPanel(groups, width, availableHeight) {
+    const panelWidth = Math.max(28, Math.min(width, SHORTCUTS_PANEL_MAX_WIDTH));
+    const innerWidth = Math.max(1, panelWidth - 4);
+    const keyWidth = Math.max(SHORTCUTS_KEY_COLUMN_MIN, ...groups.flatMap((group) => group.rows.map((row) => displayWidth(row.keys))));
+    const side = (row) => overlayPanelLine(row, innerWidth, MODEL_PICKER_BORDER_COLOR);
+    const groupLines = (group, spaced) => [
+        ...(spaced ? [side(plainLine(''))] : []),
+        side(plainLine(fitLine(group.title, innerWidth), {
+            color: MODEL_PICKER_ACCENT_COLOR,
+            bold: true,
+        })),
+        ...group.rows.map((row) => side(line(span(`  ${row.keys}${' '.repeat(Math.max(0, keyWidth - displayWidth(row.keys)))}  `, { bold: true }), span(fitLine(row.description, Math.max(1, innerWidth - keyWidth - 4)), { color: 'gray' })))),
+    ];
+    const chromeRows = 4;
+    const budget = Math.max(1, availableHeight - chromeRows);
+    const spacedBody = groups.flatMap((group, index) => groupLines(group, index > 0));
+    const plainBody = groups.flatMap((group) => groupLines(group, false));
+    let body = spacedBody;
+    let hidden = 0;
+    if (spacedBody.length > budget) {
+        body = plainBody;
+        if (plainBody.length > budget) {
+            body = [];
+            hidden = groups.reduce((total, group) => total + group.rows.length, 0);
+            for (const group of groups) {
+                const whole = groupLines(group, false);
+                if (body.length + whole.length <= budget) {
+                    body = [...body, ...whole];
+                    hidden -= group.rows.length;
+                    continue;
+                }
+                const room = budget - body.length - 1;
+                if (room >= 1) {
+                    const kept = group.rows.slice(0, room);
+                    body = [...body, ...groupLines({ ...group, rows: kept }, false)];
+                    hidden -= kept.length;
+                }
+                break;
+            }
+        }
+    }
+    const hint = hidden > 0 ? `esc close  •  ${hidden} more in /help` : 'esc close';
+    return [
+        shortcutsTopBorder(panelWidth),
+        ...body,
+        plainLine(`├${'─'.repeat(panelWidth - 2)}┤`, {
+            color: MODEL_PICKER_BORDER_COLOR,
+        }),
+        side(plainLine(fitLine(hint, innerWidth), { color: 'gray' })),
+        plainLine(`╰${'─'.repeat(panelWidth - 2)}╯`, {
+            color: MODEL_PICKER_BORDER_COLOR,
+        }),
+    ];
+}
 function commandPaletteTopBorder(panelWidth) {
     const prefix = '╭─ Commands ';
     const suffix = '╮';
@@ -1134,6 +1234,9 @@ function buildOverlayLines(state, width, height, nowMs) {
         }));
         return buildOverlayPanel(lines, width, OVERLAY_BORDER_COLOR, height);
     }
+    if (state.shortcutsOpen) {
+        lines.push(...buildShortcutsPanel(buildShortcutGroups(), width, height));
+    }
     if (state.modelPickerOpen) {
         const options = buildModelPickerOptions(state.currentModelId, state.serverModels);
         lines.push(...buildModelPickerPanel(options, state.modelPickerIndex, width, height));
@@ -1212,7 +1315,7 @@ function countSectionLines(sections) {
 export function userInputViewportForFrame(state, cols, rows, spinnerFrame, elapsedSeconds, nowMs = 0) {
     const contentWidth = frameContentWidth(cols);
     const liveRows = buildLiveLines(state, contentWidth, spinnerFrame, elapsedSeconds, nowMs).length;
-    const overlayHeight = Math.max(0, rows - liveRows - composerFooterLines(state).length);
+    const overlayHeight = Math.max(0, rows - liveRows - composerFooterLines(state, contentWidth).length);
     return {
         width: approvalPanelInnerWidth(contentWidth),
         maxRows: overlayPanelContentBudget(overlayHeight),
@@ -1248,7 +1351,11 @@ export function buildTuiFrame(state, cols, rows, spinnerFrame, elapsedSeconds, n
         sections.push({ kind: 'live', lines: liveLines });
     }
     const overlayActive = Boolean(state.approvalPrompt || state.sudoPrompt || state.userInputPrompt);
-    if (!state.resumePickerOpen && !state.modelPickerOpen && !state.jobsPickerOpen && !overlayActive) {
+    if (!state.resumePickerOpen &&
+        !state.modelPickerOpen &&
+        !state.jobsPickerOpen &&
+        !state.shortcutsOpen &&
+        !overlayActive) {
         const composerLines = [];
         if (state.busy && state.status === 'Starting a new conversation...') {
             composerLines.push(line(span('Starting a new conversation…', { color: 'gray', dim: true })));
@@ -1268,18 +1375,18 @@ export function buildTuiFrame(state, cols, rows, spinnerFrame, elapsedSeconds, n
         }
         sections.push({
             kind: 'composer',
-            lines: [...composerLines, plainLine(''), ...composerFooterLines(state)],
+            lines: [...composerLines, plainLine(''), ...composerFooterLines(state, contentWidth)],
         });
     }
     if (state.userInputPrompt) {
         sections.push({
             kind: 'busyFooter',
-            lines: composerFooterLines(state),
+            lines: composerFooterLines(state, contentWidth),
         });
     }
     const overlayHeight = state.userInputPrompt
         ? Math.max(0, rows - countSectionLines(sections))
-        : state.jobsPickerOpen
+        : state.jobsPickerOpen || state.shortcutsOpen
             ? Math.max(Math.min(rows, JOBS_PICKER_MIN_ROWS), rows - countSectionLines(sections))
             : rows;
     const overlayLines = buildOverlayLines(state, contentWidth, overlayHeight, nowMs);

package/dist/src/ui/tui/shell-input.js

@@ -1,3 +1,4 @@
+import { shortcutsPanelAvailable } from './shortcuts.js';
 import { moveComposerCursorVertically } from './composer-layout.js';
 import { readClipboardImage, readClipboardText } from '../../core/clipboard.js';
 import { MAX_IMAGES_PER_MESSAGE, MAX_TOTAL_IMAGE_BYTES_PER_MESSAGE, approximateBase64DecodedBytes, totalAttachmentBytes, } from '../../core/image-limits.js';
@@ -105,7 +106,7 @@ function pasteTextFromClipboard(store, handlers) {
     if (!text) {
         store.update((state) => ({
             ...state,
-            status: 'Clipboard has no text to paste',
+            transientStatus: 'Clipboard has no text to paste',
         }));
         return;
     }
@@ -415,12 +416,24 @@ export function handleShellKeyEvent(store, handlers, event) {
         }
         return;
     }
+    if (state.shortcutsOpen) {
+        if (key.escape || key.returnKey || key.input === '?' || key.input === 'q') {
+            handlers.onLiveFrameShapeChange();
+            store.update((current) => ({ ...current, shortcutsOpen: false }));
+        }
+        return;
+    }
     if (key.ctrl && key.input === 'b' && !key.meta && !key.shift) {
         if ((state.backgroundJobs ?? []).length > 0) {
             handlers.onOpenJobsPicker();
         }
         return;
     }
+    if (key.input === '?' && !key.ctrl && !key.meta && shortcutsPanelAvailable(state)) {
+        handlers.onLiveFrameShapeChange();
+        store.update((current) => ({ ...current, shortcutsOpen: true }));
+        return;
+    }
     if (key.escape) {
         if (state.busy) {
             if (state.queuedMessage) {
@@ -449,6 +462,10 @@ export function handleShellKeyEvent(store, handlers, event) {
         return;
     }
     if (key.tab && key.shift) {
+        if (state.busy) {
+            handlers.onAgentModeChangeBlocked?.();
+            return;
+        }
         handlers.onCycleAgentMode();
         return;
     }

package/dist/src/ui/tui/shortcuts.js

@@ -0,0 +1,60 @@
+import { agentModeCycleSequence } from '../../agent-mode.js';
+export function shortcutsPanelAvailable(state) {
+    return (!state.exiting &&
+        !state.approvalPrompt &&
+        !state.sudoPrompt &&
+        !state.userInputPrompt &&
+        !state.queuedMessage &&
+        !state.input &&
+        (state.cursor ?? 0) === 0 &&
+        (state.pastedChunks?.length ?? 0) === 0 &&
+        state.promptHistoryCursor == null);
+}
+export function buildShortcutGroups(platform = process.platform) {
+    const imagePaste = platform === 'win32' ? 'Alt+V' : 'Ctrl+V';
+    const textPaste = platform === 'darwin' ? 'Cmd+V' : 'Ctrl+Shift+V';
+    return [
+        {
+            title: 'Composer',
+            rows: [
+                { keys: 'Enter', description: 'Send your message' },
+                {
+                    keys: 'Shift+Tab',
+                    description: `Cycle ${agentModeCycleSequence()} (between turns)`,
+                },
+                { keys: '/', description: 'Slash commands — /help lists them all' },
+                { keys: '↑ / ↓', description: 'Earlier prompts' },
+                { keys: 'Esc', description: 'Clear the composer' },
+                { keys: 'Ctrl+C', description: 'Clear the composer, or quit when empty' },
+            ],
+        },
+        {
+            title: 'While the agent is working',
+            rows: [
+                { keys: 'Enter', description: 'Queue a message; Enter again sends it into the turn' },
+                { keys: '↑', description: 'Bring a queued message back to edit it' },
+                { keys: 'Esc', description: 'Discard the queued message, or cancel the turn' },
+                { keys: 'Ctrl+C', description: 'Cancel the turn' },
+                { keys: 'Ctrl+B', description: 'Background jobs' },
+            ],
+        },
+        {
+            title: 'Clipboard & images',
+            rows: [
+                { keys: imagePaste, description: 'Paste a screenshot into the message' },
+                { keys: textPaste, description: 'Paste text (your terminal’s own shortcut)' },
+                { keys: 'Right-click', description: 'Paste, or copy the link under the cursor' },
+            ],
+        },
+        {
+            title: 'Transcript',
+            rows: [
+                { keys: 'PageUp / PageDown', description: 'Scroll — the mouse wheel works too' },
+                { keys: 'Drag', description: 'Select and copy' },
+                { keys: 'Double-click', description: 'Copy a word' },
+                { keys: 'Triple-click', description: 'Copy a whole row' },
+                { keys: 'Left-click', description: 'Open a link' },
+            ],
+        },
+    ];
+}

package/dist/src/usage.js

@@ -1,9 +1,12 @@
-const USAGE_WINDOWS = [
+export const USAGE_WINDOWS = [
     ['5-hour', '5-hourly'],
     ['Weekly', 'weekly'],
     ['Monthly', 'monthly'],
 ];
-function formatUtcMinute(value) {
+export function usageWindowLabel(key) {
+    return USAGE_WINDOWS.find(([, id]) => id === key)?.[0] ?? '';
+}
+export function formatUtcMinute(value) {
     if (!value)
         return 'no active usage';
     const date = new Date(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thegitai/cli",
-  "version": "1.0.0-preview.41",
+  "version": "1.0.0-preview.42",
   "description": "TheGitAI is an agentic AI coding tool for your terminal. It reads and searches your repository, writes and edits files, runs your tests, and verifies the change before handing it back.",
   "keywords": [
     "agentic-ai",
@@ -44,11 +44,11 @@
     "@lydell/node-pty-linux-x64": "1.1.0",
     "@lydell/node-pty-win32-arm64": "1.1.0",
     "@lydell/node-pty-win32-x64": "1.1.0",
-    "@thegitai/tui-darwin-arm64": "1.0.0-preview.41",
-    "@thegitai/tui-darwin-x64": "1.0.0-preview.41",
-    "@thegitai/tui-linux-arm64": "1.0.0-preview.41",
-    "@thegitai/tui-linux-x64": "1.0.0-preview.41",
-    "@thegitai/tui-win32-x64": "1.0.0-preview.41",
+    "@thegitai/tui-darwin-arm64": "1.0.0-preview.42",
+    "@thegitai/tui-darwin-x64": "1.0.0-preview.42",
+    "@thegitai/tui-linux-arm64": "1.0.0-preview.42",
+    "@thegitai/tui-linux-x64": "1.0.0-preview.42",
+    "@thegitai/tui-win32-x64": "1.0.0-preview.42",
     "@vscode/ripgrep": "1.18.0"
   },
   "repository": {