Make agent key hints clickable in terminal panes

[azooz2003-bit]

Summary

Agent TUIs print key hints all over their output: ctrl+o to expand under a collapsed tool result, esc to interrupt in the status line, shift+tab to cycle beside the mode. With the new agentActions.keyHints setting on (off by default, Settings > Terminal > Clickable Agent Key Hints), clicking one of those hints in a terminal pane presses its keys. Hovering a hint underlines it, shows a pointing hand, and a tooltip such as "Click to press ⌃O (expand)".

How it works:

• Detection. AgentKeyHintDetector (CmuxTerminalCore) reads the clicked viewport row on its own (no joining of soft-wrapped lines): one or more chords (ctrl+x, alt+x, shift+tab, esc, tab, enter, space, arrows, ⌃O-style glyphs, ctrl+x ctrl+k sequences), optionally again, then to/for and an action that ends at ·, |, parentheses, a two-space column gap or the end of the line. OpenCode's bare esc interrupt form matches only for its known actions. Bare key words (up to date, end to end) count only before a hint verb, and return is not a key word. Keys that act on whatever UI is live (Enter, Esc, Tab, arrows, bare letters, Home, End, page keys) count only in the agent's live region: the viewport is at the bottom and the row is no more than 8 rows above the cursor row, or below it, where the status line, input box, footer and permission prompts are drawn. Ctrl and Alt chords (ctrl+o to expand) count on any row, so prose such as "Scroll down to view the full log" stays inert.
• Where. Only in panes whose journaled agent lifecycle includes Claude Code, Codex or OpenCode, and only while the setting is on. When several are journaled, a running or waiting agent wins over an idle one. Nothing runs on the typing path; the click is resolved on mouse release, and hover reads one row only when the pointer moves to a new cell. Scrolling, a resize, or a viewport change under a shown hint clears or re-resolves the underline.
• Safety. Chords that quit, suspend or signal (ctrl+c, ctrl+d, ctrl+z, ctrl+\) are never clickable, and are never sent even if a keybindings file maps a hinted action to one. Any chord with Ctrl and c, d, z or \ counts, whatever Shift or Alt is added. A drag, a selection or a Shift/Option/Control click presses nothing. A click presses its hint once the system double-click interval passes without a second press, so a double or triple click selects text and presses nothing.
• Click vs Command-click. If the agent has not captured the mouse, a plain click presses the hint. If it has, the click belongs to the agent and only a Command-click presses the hint. A Command-click on a hint takes over from the link and path fallback only when a hint covers the clicked cell; links, paths and SHAs elsewhere open as before.
• Binding layers. For Claude Code, a hint printed with its default chord (expand, cycle mode, run in background, interrupt, amend) is remapped to the user's chord when ~/.claude/keybindings.json binds that action to a different one. The file is checked on click and cached by modification date; hover reuses a check for up to 5 seconds. Codex and OpenCode render their hints from their own keymaps, so their printed chord is sent. Then, if the pane's Ghostty keybindings would consume the chord (ghostty_surface_key_is_binding), the key's legacy encoding is sent instead (ctrl+o as 0x0f, shift+tab as ESC [ Z, arrows as ESC [ A...), so the terminal binding doesn't run; a key with no legacy encoding is skipped.

OS-level remaps (Karabiner, modifier keys in System Settings, hidutil) and a tooltip that names the physical key to press come in a follow-up.

Part of #15223. Stacked on #15234.

Testing

Ran locally:

• swift test --package-path Packages/macOS/CmuxTerminalCore --filter 'AgentKeyHint|TerminalLegacyKeyEncoding': 29 tests in 6 suites passed (detector incl. live region and prose, signal chords with extra modifiers, chord resolver against keybindings files, mtime cache and hover max age, live region rule, deferred press timing, click policy, legacy encodings).
• swift test --package-path Packages/macOS/CmuxTerminal --filter TerminalTextRegion: passed (a viewport row selects exactly that row; a blank row below short content reads blank; a soft-wrapped line reads one row at a time).
• swift test --package-path Packages/macOS/CmuxSettings --filter SettingCatalogTests: passed, including the new default-off test.
• python3 tests/test_cmux_schema_parity.py and python3 tests/test_cmux_settings_supported_paths.py: passed.
• python3 scripts/verify-local.py: 15/15 checks passed. python3 scripts/localization_catalog.py check: 0 parity errors.

Not run locally: the app compile and cmuxTests. CI builds the app and runs the new cmuxTests/TerminalAgentKeyHintTests.swift, which checks that a hint click in an agent pane enqueues one key (two for ctrl+b ctrl+b), that nothing is clickable with the setting off, that bare keys are clickable only in the live region, that a running agent wins over a stale lifecycle, without an agent lifecycle, on prose or ctrl+c lines, and that a mouse-capturing agent needs a Command-click. The mouse release, hover underline, tooltip and Ghostty binding fallback are not yet exercised in a live build.

Localization: new Settings title and subtitle in the CmuxSettingsUI catalog, and the Settings search title and alias plus both tooltips in the app catalog, all in en, de, fr, ar, es, zh-Hant, zh-Hans, ko and ja.

Changelog

Added: Key hints that Claude Code, Codex and OpenCode print in a terminal, like "ctrl+o to expand", can be clicked to press those keys (Settings > Terminal > Clickable Agent Key Hints)

Demo Video

Pending dogfood.

Checklist

• Behavior changes have added or updated tests, or Testing says why not
• UI, settings, menu, schema, help-text or user-facing docs change: localization audited, and the result is stated above
• User-facing docs updated if needed
• Reviewed with a subagent before merge (cmux-review), and all bot and human review comments resolved

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Makes the key hints Claude Code, Codex, and OpenCode print in terminal panes (like ctrl+o to expand or esc to interrupt) clickable, behind a new off-by-default setting at Settings > Terminal > Clickable Agent Key Hints. Clicking a hint presses its keys; hovering underlines it and shows a pointing hand and a tooltip. The exact /goal resume prompt Codex prints is also clickable, sending the command and Enter through the same deferred hint path.

How clicks behave

• Keys that quit, suspend, or signal (ctrl+c, ctrl+d, ctrl+z, ctrl+\) are never clickable or sent, even when a keybindings file maps an action to one, including with Shift or Alt added.
• A plain click presses a hint once the double-click interval passes, so a double or triple click selects instead of pressing; a pending press is re-validated against the current runtime surface, generation, row, and authorization just before sending, and survives pointer exit. When the agent captures the mouse, only a Command-click presses the hint, and it wins over the link and path fallback for that cell.
• Codex's /goal resume prompt clicks only in the live row region with an allowlisted command; no other shell text is clickable.
• Bare-key hints (Enter, Esc, Tab, arrows, Home, End, page keys) count only in the agent's live region—viewport at the bottom of the scrollback, within 8 rows of the cursor. Ctrl and Alt chords count anywhere; "return" is never a key word.
• Claude Code hints printed with their default chord are remapped to the user's chord from ~/.claude/keybindings.json, read on click and cached by modification date.
• When the pane's Ghostty keybindings would consume the chord, the key's legacy terminal encoding is sent instead so the binding doesn't run; keys with no legacy encoding are skipped.
• Hints resolve from the exact viewport row under the pointer, so a blank row can't map to content above it; hover re-reads per new cell and re-resolves on scroll or layout.
• This branch carries a long stale merge of main; only the agent key hint changes belong to this PR.

^{Written for commit b231717. Summary will update on new commits.}

---

Migrated from #15305 after correcting the PR author identity. The head branch and commit history are preserved.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 62d53544-9dfd-4a1a-9dfa-13a81b00c25b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}