From 7c07422202211f864209ffcd2dcbf38df209e9ed Mon Sep 17 00:00:00 2001
From: ethernet <arilotter@gmail.com>
Date: Thu, 30 Apr 2026 13:37:12 -0400
Subject: [PATCH] feat(tui): add a mini help menu when u write ? in the input
 field

it feels so nice :3 just a lil popup ! doesn't get in the way or take
any focus or anything, and directs users to /help for more info :3
---
 ui-tui/src/components/appLayout.tsx |  3 ++
 ui-tui/src/components/helpHint.tsx  | 73 +++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 ui-tui/src/components/helpHint.tsx

diff --git a/ui-tui/src/components/appLayout.tsx b/ui-tui/src/components/appLayout.tsx
index 6f2d33df97..97a0572246 100644
--- a/ui-tui/src/components/appLayout.tsx
+++ b/ui-tui/src/components/appLayout.tsx
@@ -22,6 +22,7 @@ import { GoodVibesHeart, StatusRule, StickyPromptTracker, TranscriptScrollbar }
 import { FloatingOverlays, PromptZone } from './appOverlays.js'
 import { Banner, Panel, SessionPanel } from './branding.js'
 import { FpsOverlay } from './fpsOverlay.js'
+import { HelpHint } from './helpHint.js'
 import { MessageLine } from './messageLine.js'
 import { QueuedMessages } from './queuedMessages.js'
 import { LiveTodoPanel, StreamingAssistant } from './streamingAssistant.js'
@@ -242,6 +243,8 @@ const ComposerPane = memo(function ComposerPane({
           pagerPageSize={composer.pagerPageSize}
         />
 
+        {composer.input === '?' && !composer.inputBuf.length && <HelpHint t={ui.theme} />}
+
         {!isBlocked && (
           <>
             {composer.inputBuf.map((line, i) => (
diff --git a/ui-tui/src/components/helpHint.tsx b/ui-tui/src/components/helpHint.tsx
new file mode 100644
index 0000000000..5634ef5661
--- /dev/null
+++ b/ui-tui/src/components/helpHint.tsx
@@ -0,0 +1,73 @@
+import { Box, Text } from '@hermes/ink'
+
+import { HOTKEYS } from '../content/hotkeys.js'
+import type { Theme } from '../theme.js'
+
+const COMMON_COMMANDS: [string, string][] = [
+  ['/help', 'full list of commands + hotkeys'],
+  ['/clear', 'start a new session'],
+  ['/resume', 'resume a prior session'],
+  ['/details', 'control transcript detail level'],
+  ['/copy', 'copy selection or last assistant message'],
+  ['/quit', 'exit hermes']
+]
+
+const HOTKEY_PREVIEW = HOTKEYS.slice(0, 8)
+
+export function HelpHint({ t }: { t: Theme }) {
+  const labelW = Math.max(
+    ...COMMON_COMMANDS.map(([k]) => k.length),
+    ...HOTKEY_PREVIEW.map(([k]) => k.length)
+  )
+
+  const pad = (s: string) => s + ' '.repeat(Math.max(0, labelW - s.length + 2))
+
+  return (
+    <Box alignItems="flex-start" bottom="100%" flexDirection="column" left={0} position="absolute" right={0}>
+      <Box
+        alignSelf="flex-start"
+        borderColor={t.color.primary}
+        borderStyle="round"
+        flexDirection="column"
+        marginBottom={1}
+        opaque
+        paddingX={1}
+      >
+        <Text>
+          <Text bold color={t.color.primary}>
+            ? quick help
+          </Text>
+          <Text color={t.color.muted}>
+            {'  ·  type /help for the full panel  ·  backspace to dismiss'}
+          </Text>
+        </Text>
+
+        <Box marginTop={1}>
+          <Text bold color={t.color.accent}>
+            Common commands
+          </Text>
+        </Box>
+
+        {COMMON_COMMANDS.map(([k, v]) => (
+          <Text key={k}>
+            <Text color={t.color.label}>{pad(k)}</Text>
+            <Text color={t.color.muted}>{v}</Text>
+          </Text>
+        ))}
+
+        <Box marginTop={1}>
+          <Text bold color={t.color.accent}>
+            Hotkeys
+          </Text>
+        </Box>
+
+        {HOTKEY_PREVIEW.map(([k, v]) => (
+          <Text key={k}>
+            <Text color={t.color.label}>{pad(k)}</Text>
+            <Text color={t.color.muted}>{v}</Text>
+          </Text>
+        ))}
+      </Box>
+    </Box>
+  )
+}