Misleading keyboard shortcut labels on macOS: 'Alt' should be 'Option' (⌥)

Resolved 💬 1 comment Opened May 12, 2026 by adisagar2003 Closed Jun 12, 2026

Summary

In Claude Code's agent view (and elsewhere in the UI), keyboard shortcuts are labeled using Alt — but macOS keyboards do not have an Alt key. The corresponding key on Mac is labeled Option (⌥). This is confusing for macOS users who look at their keyboard for a key that doesn't exist.

Steps to reproduce

  1. Run Claude Code on macOS
  2. Open the agent view / any UI surface that displays a keyboard shortcut hint involving the Alt key
  3. Observe the hint reads Alt+<key> instead of Option+<key> (or ⌥<key>)

Expected behavior

On macOS, shortcuts should be displayed using the platform-native key name:

  • Option or instead of Alt
  • (Likewise: Command / instead of Ctrl where the shortcut actually maps to Cmd, Return instead of Enter where appropriate, etc.)

On Windows/Linux, Alt remains correct.

Actual behavior

Alt+<key> is shown on all platforms, including macOS, even though no Alt key exists on a Mac keyboard.

Suggested fix

Detect the platform at render time (e.g. process.platform === 'darwin') and swap the modifier label:

| Generic | macOS | Win/Linux |
|--------|--------|-----------|
| Alt | ⌥ / Option | Alt |
| Ctrl | ⌘ / Command (if mapping to Cmd) or ⌃ / Control | Ctrl |
| Meta | ⌘ / Command | Win / Super |

A small helper that maps shortcut tokens to their platform-appropriate glyphs would centralize this and prevent future drift.

Environment

  • Claude Code on macOS (Darwin)
  • Affects: shortcut hints in the agent/terminal view

Why this matters

Beyond aesthetics, this is an accessibility and onboarding issue — new macOS users (especially those new to terminal tooling) will hunt for a non-existent key. Native key labels are a baseline expectation for any cross-platform CLI/desktop tool.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗