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

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',
@@ -72,6 +77,11 @@ const HELP_MARKDOWN = [
     '  back for editing and **Esc**/**Ctrl+C** discards it; both unlock the',
     '  composer for the next message. **Ctrl+V** pastes a screenshot onto the',
     '  queued message, and it is delivered into the running turn with the text.',
+    '- **Ctrl+G** turns desktop notifications on or off. One is raised when a turn',
+    '  ends and when a permission prompt or a question is waiting for you, but',
+    '  only while the terminal is in the background — if you are looking at the',
+    '  session you are told nothing. Coming back clears it. The choice is',
+    '  remembered between sessions.',
     `- **Paste** into the composer with your terminal's paste shortcut (\`${PASTE_SHORTCUT}\``,
     '  on this system) or by right-clicking the composer.',
     '- **Copy** from the transcript by dragging to select; double-click copies a',
@@ -96,6 +106,7 @@ const HELP_MARKDOWN = [
     '  is working; press it again or Esc to close without touching the turn',
     '- `/jobs output <id>` — print one job\'s full captured output',
     '- `/jobs kill <id>` — stop one background job',
+    '- `/notify` — turn desktop notifications on or off (same as Ctrl+G)',
     '- `/new` — start a new conversation; this session remains saved',
     '- `/logout` — sign out and quit',
     '- `/exit` — quit the session',

package/dist/src/preferences.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { getClientStateDir } from './client-state.js';
+export const DEFAULT_PREFERENCES = {
+    notifications: true,
+};
+export function getPreferencesPath(env = process.env) {
+    return path.join(getClientStateDir(env), 'prefs.json');
+}
+export function readPreferences(env = process.env) {
+    const filePath = getPreferencesPath(env);
+    if (!existsSync(filePath))
+        return { ...DEFAULT_PREFERENCES };
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+        return {
+            notifications: parsed.notifications === false ? false : DEFAULT_PREFERENCES.notifications,
+        };
+    }
+    catch {
+        return { ...DEFAULT_PREFERENCES };
+    }
+}
+export function writePreferences(preferences, env = process.env) {
+    const filePath = getPreferencesPath(env);
+    mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(preferences, null, 2)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}

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,10 @@
+import { basename } from 'node:path';
 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 { createAttentionController, INITIAL_TERMINAL_FOCUS, } from './tui/attention.js';
+import { backendFor, createNotificationQueue, } from './tui/desktop-notification.js';
+import { readPreferences, writePreferences } from '../preferences.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 +20,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 +81,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
@@ -135,6 +139,10 @@ export const SLASH_COMMANDS = [
         command: '/jobs',
         description: 'Background jobs: pick to view output or kill',
     },
+    {
+        command: '/notify',
+        description: 'Toggle desktop notifications when a turn ends (Ctrl+G)',
+    },
     {
         command: '/new',
         description: 'start a new conversation; this session remains saved',
@@ -1100,11 +1108,15 @@ function createInitialShellState(session, serverModels, debugUi) {
         exiting: false,
         input: '',
         maxToolSteps: session.maxToolSteps,
+        notificationsEnabled: readPreferences(session.env).notifications,
+        terminalFocused: INITIAL_TERMINAL_FOCUS,
         jobsPickerExpandedId: null,
         jobsPickerIndex: 0,
         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 +1544,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({
@@ -1553,11 +1567,42 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                 busy: state.busy,
             });
         };
+        const notifier = backendFor();
+        let notificationHandle = null;
+        const projectLabel = basename(session.rootDir) || 'TheGitAI';
+        const notifications = createNotificationQueue();
+        const attention = createAttentionController({
+            notify: (kind) => {
+                notifications.run(async () => {
+                    notificationHandle = await notifier.post({
+                        title: projectLabel,
+                        body: kind === 'blocked'
+                            ? 'Waiting for your answer'
+                            : 'Finished \u2014 your turn',
+                    }, notificationHandle);
+                });
+            },
+            withdraw: () => {
+                notifications.run(async () => {
+                    notifier.withdraw(notificationHandle);
+                    notificationHandle = null;
+                });
+            },
+        });
+        const syncAttention = () => {
+            const state = store.getState();
+            attention.sync({
+                awaitingAnswer: Boolean(state.approvalPrompt || state.sudoPrompt || state.userInputPrompt),
+                busy: state.busy,
+                focused: state.terminalFocused,
+            }, state.notificationsEnabled);
+        };
         const renderCurrentFrame = () => {
             if (!tuiReady)
                 return;
             const state = store.getState();
             syncTerminalTitle();
+            syncAttention();
             const elapsedSeconds = busyElapsedSeconds(state, Date.now());
             bridge.render(buildTuiFrame(state, terminalCols, terminalRows, spinnerFrame, elapsedSeconds, Date.now()));
         };
@@ -1806,6 +1851,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;
@@ -2100,6 +2148,16 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                 title: 'Model',
             });
         };
+        const toggleNotifications = () => {
+            const enabled = !store.getState().notificationsEnabled;
+            store.update((current) => ({ ...current, notificationsEnabled: enabled }));
+            try {
+                writePreferences({ ...readPreferences(session.env), notifications: enabled }, session.env);
+            }
+            catch {
+            }
+            showTransientStatus(enabled ? 'Notifications on' : 'Notifications off');
+        };
         const openJobsPicker = () => {
             if (store.getState().jobsPickerOpen)
                 return;
@@ -2506,8 +2564,19 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                         openJobsPicker();
                         return;
                     }
+                    if (input === '/notify') {
+                        store.update((current) => ({
+                            ...current,
+                            cursor: 0,
+                            input: '',
+                            pastedChunks: [],
+                        }));
+                        toggleNotifications();
+                        return;
+                    }
                     appendTurnAwareEntry({
-                        body: "Slash commands can't be queued while a turn is running. Ctrl+B opens background jobs.",
+                        body: "Slash commands can't be queued while a turn is running. " +
+                            'Ctrl+B opens background jobs, Ctrl+G toggles notifications.',
                         kind: 'system',
                         title: 'Queued',
                     });
@@ -2592,6 +2661,10 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                 appendStaticEntries(buildReportTranscriptEntries(opened));
                 return;
             }
+            if (input === '/notify') {
+                toggleNotifications();
+                return;
+            }
             if (input === '/jobs' || input.startsWith('/jobs ')) {
                 const jobsArgs = input.slice('/jobs'.length).trim();
                 if (!jobsArgs) {
@@ -2899,6 +2972,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 +2982,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 +3005,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 +3178,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
             },
             onCancelTurn: cancelActiveTurn,
             onCycleAgentMode: cycleAgentMode,
+            onAgentModeChangeBlocked: reportAgentModeLocked,
             onCtrlC: handleCtrlC,
             onLinkCopy: handleLinkCopy,
             onLinkOpen: handleLinkOpen,
@@ -3101,6 +3190,7 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
             onSelectionCopy: handleAppSelectionCopy,
             onSelectModel: handleInlineModelSelection,
             onOpenJobsPicker: openJobsPicker,
+            onToggleNotifications: toggleNotifications,
             onJobsPickerOutput: handleJobsPickerOutput,
             onJobsPickerKill: handleJobsPickerKill,
             onSudoPasswordInput: handleSudoPasswordInput,
@@ -3144,6 +3234,13 @@ export async function runClientInteractive({ appendPromptHistory, authConfig, de
                 return;
             }
             if (message.op === 'event') {
+                if (message.kind === 'focus') {
+                    store.update((current) => current.terminalFocused === message.focused
+                        ? current
+                        : { ...current, terminalFocused: message.focused });
+                    renderCurrentFrame();
+                    return;
+                }
                 if (message.kind === 'resize') {
                     terminalCols = message.cols;
                     terminalRows = message.rows;

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

@@ -0,0 +1,25 @@
+export const INITIAL_TERMINAL_FOCUS = true;
+export function createAttentionController(options) {
+    let previous = null;
+    let outstanding = false;
+    return {
+        sync(state, enabled) {
+            const last = previous;
+            previous = { ...state };
+            if (last && !last.focused && state.focused && outstanding) {
+                outstanding = false;
+                options.withdraw();
+            }
+            if (!last || !enabled)
+                return;
+            if (state.focused)
+                return;
+            const turnFinished = last.busy && !state.busy;
+            const nowBlocked = !last.awaitingAnswer && state.awaitingAnswer;
+            if (nowBlocked || turnFinished) {
+                outstanding = true;
+                options.notify(nowBlocked ? 'blocked' : 'finished');
+            }
+        },
+    };
+}

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

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -51,6 +51,9 @@ function normalizeChildMessage(raw) {
             url: String(raw.url ?? ''),
         };
     }
+    if (raw.kind === 'focus') {
+        return { op: 'event', kind: 'focus', focused: raw.focused === true };
+    }
     if (raw.kind === 'contextMenu') {
         return { op: 'event', kind: 'contextMenu' };
     }
@@ -95,13 +98,18 @@ function normalizeChildMessage(raw) {
         pageDown: bool(raw.pageDown ?? raw.page_down),
     };
 }
+function isRepoCheckout(moduleDir) {
+    return [
+        path.join(moduleDir, '../../../../thegitai-tui/Cargo.toml'),
+        path.join(moduleDir, '../../../../../thegitai-tui/Cargo.toml'),
+    ].some((candidate) => existsSync(candidate));
+}
 export function resolveTuiBinaryPath() {
     const binaryName = process.platform === 'win32' ? 'thegitai-tui.exe' : 'thegitai-tui';
     const platformPackage = `@thegitai/tui-${process.platform}-${process.arch}`;
-    try {
-        return requireFromHere.resolve(`${platformPackage}/${binaryName}`);
-    }
-    catch {
+    const override = String(process.env.THEGITAI_TUI_BINARY ?? '').trim();
+    if (override && existsSync(override)) {
+        return override;
     }
     const moduleDir = path.dirname(fileURLToPath(import.meta.url));
     const devCandidates = [
@@ -109,6 +117,24 @@ export function resolveTuiBinaryPath() {
         path.join(moduleDir, '../../../../bin', binaryName),
     ];
     const devBinary = devCandidates.find((candidate) => existsSync(candidate));
+    let publishedBinary = null;
+    try {
+        publishedBinary = requireFromHere.resolve(`${platformPackage}/${binaryName}`);
+    }
+    catch {
+    }
+    if (publishedBinary && devBinary && isRepoCheckout(moduleDir)) {
+        try {
+            if (statSync(devBinary).mtimeMs > statSync(publishedBinary).mtimeMs) {
+                return devBinary;
+            }
+        }
+        catch {
+        }
+    }
+    if (publishedBinary) {
+        return publishedBinary;
+    }
     if (devBinary) {
         return devBinary;
     }

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,20 @@ 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_NOTIFICATIONS_ON = 'Notifications ON';
+const FOOTER_NOTIFICATIONS_OFF = 'Notifications OFF';
+export function footerNotificationHint(status) {
+    const text = String(status ?? '').trim();
+    if (text === 'Notifications on')
+        return FOOTER_NOTIFICATIONS_ON;
+    if (text === 'Notifications off')
+        return FOOTER_NOTIFICATIONS_OFF;
+    return '';
+}
+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;
@@ -176,10 +190,12 @@ export function formatPromptSessionIdLabel(showSessionId, sessionId) {
 }
 const CLIENT_SLASH_COMMANDS = [
     { command: '/help', description: 'Show available chat commands' },
+    { command: '/about', description: 'Show version and platform info' },
     { command: '/usage', description: 'Show account usage percentage and reset times' },
     { command: '/model', description: 'Switch the active model' },
     { command: '/resume', description: 'Open the session picker to resume a previous session' },
     { command: '/jobs', description: 'Background jobs: pick to view output or kill' },
+    { command: '/notify', description: 'Toggle desktop notifications when a turn ends (Ctrl+G)' },
     { command: '/report', description: 'Report a bug privately on the TheGitAI website' },
     { command: '/new', description: 'start a new conversation; this session remains saved' },
     { command: '/logout', description: 'Sign out and quit' },
@@ -434,10 +450,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 +498,47 @@ 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 notifyHint = footerNotificationHint(state.transientStatus);
+    const join = (...parts) => parts.filter(Boolean).join('  ·  ');
+    const tiers = [];
+    if (notifyHint) {
+        tiers.push(join(cancelHint, notifyHint, helpHint));
+        tiers.push(join(notifyHint, helpHint));
+        tiers.push(join(cancelHint, notifyHint));
+        tiers.push(notifyHint);
+    }
+    if (cancelHint && helpHint)
+        tiers.push(`${cancelHint}  ·  ${helpHint}`);
+    if (cancelHint)
+        tiers.push(cancelHint);
+    if (helpHint)
+        tiers.push(helpHint);
+    tiers.push('');
+    return tiers.filter((tier, index) => tiers.indexOf(tier) === index);
+}
+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 +556,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 +564,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 +950,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 +1254,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 +1335,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 +1371,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 +1395,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/desktop-notification.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process';
+function run(command, args, { capture = false } = {}) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                stdio: ['ignore', capture ? 'pipe' : 'ignore', 'ignore'],
+            });
+        }
+        catch {
+            resolve('');
+            return;
+        }
+        let out = '';
+        child.stdout?.on('data', (chunk) => {
+            out += chunk.toString('utf8');
+        });
+        child.on('error', () => resolve(''));
+        child.on('close', () => resolve(out.trim()));
+    });
+}
+const linuxBackend = {
+    canWithdraw: true,
+    async post(request, previous) {
+        const args = [
+            '--print-id',
+            '--app-name=TheGitAI',
+            '--icon=utilities-terminal',
+            '--urgency=normal',
+        ];
+        if (previous)
+            args.push(`--replace-id=${previous}`);
+        args.push(request.title, request.body);
+        const id = await run('notify-send', args, { capture: true });
+        return /^\d+$/.test(id) ? id : null;
+    },
+    withdraw(handle) {
+        if (!handle)
+            return;
+        void run('gdbus', [
+            'call',
+            '--session',
+            '--dest',
+            'org.freedesktop.Notifications',
+            '--object-path',
+            '/org/freedesktop/Notifications',
+            '--method',
+            'org.freedesktop.Notifications.CloseNotification',
+            handle,
+        ]);
+    },
+};
+function appleScriptString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+const macBackend = {
+    canWithdraw: false,
+    async post(request) {
+        await run('osascript', [
+            '-e',
+            `display notification "${appleScriptString(request.body)}" with title "${appleScriptString(request.title)}"`,
+        ]);
+        return null;
+    },
+    withdraw() {
+    },
+};
+function powerShellString(value) {
+    return value.replace(/'/g, "''");
+}
+const WINDOWS_AUMID = 'TheGitAI';
+const WINDOWS_TAG = 'thegitai-attention';
+const WINDOWS_GROUP = 'thegitai';
+const windowsBackend = {
+    canWithdraw: true,
+    async post(request) {
+        const script = [
+            '[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null',
+            '[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom, ContentType=WindowsRuntime] > $null',
+            '$t = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)',
+            '$n = $t.GetElementsByTagName("text")',
+            `$n.Item(0).AppendChild($t.CreateTextNode('${powerShellString(request.title)}')) > $null`,
+            `$n.Item(1).AppendChild($t.CreateTextNode('${powerShellString(request.body)}')) > $null`,
+            '$toast = [Windows.UI.Notifications.ToastNotification]::new($t)',
+            `$toast.Tag = '${WINDOWS_TAG}'`,
+            `$toast.Group = '${WINDOWS_GROUP}'`,
+            `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${WINDOWS_AUMID}').Show($toast)`,
+        ].join('; ');
+        await run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script]);
+        return WINDOWS_TAG;
+    },
+    withdraw(handle) {
+        if (!handle)
+            return;
+        const script = [
+            '[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] > $null',
+            `[Windows.UI.Notifications.ToastNotificationManager]::History.Remove('${powerShellString(handle)}', '${WINDOWS_GROUP}', '${WINDOWS_AUMID}')`,
+        ].join('; ');
+        void run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script]);
+    },
+};
+export function createNotificationQueue() {
+    let tail = Promise.resolve();
+    return {
+        idle: () => tail,
+        run(step) {
+            tail = tail.then(step).catch(() => {
+            });
+        },
+    };
+}
+export function backendFor(platform = process.platform) {
+    if (platform === 'darwin')
+        return macBackend;
+    if (platform === 'win32')
+        return windowsBackend;
+    return linuxBackend;
+}

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,28 @@ 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.ctrl && key.input === 'g' && !key.meta && !key.shift) {
+        handlers.onToggleNotifications?.();
+        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 +466,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,61 @@
+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' },
+                { keys: 'Ctrl+G', description: 'Desktop notifications — toggle on or off' },
+            ],
+        },
+        {
+            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.43",
   "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.43",
+    "@thegitai/tui-darwin-x64": "1.0.0-preview.43",
+    "@thegitai/tui-linux-arm64": "1.0.0-preview.43",
+    "@thegitai/tui-linux-x64": "1.0.0-preview.43",
+    "@thegitai/tui-win32-x64": "1.0.0-preview.43",
     "@vscode/ripgrep": "1.18.0"
   },
   "repository": {