Make agent-view session shortcuts remappable (`Alt+<n>` is unavailable in several terminals)

Status Open
Maintainer reply None cached
Activity 0 comments · opened Aug 20, 2026

Summary

Follow-up to #85468. Alt+1Alt+9 attach to sessions 1–9 in claude agents, but Alt+<number> is not reliably deliverable to a TUI: several common terminal emulators consume it before the application sees it, and on macOS the default Option handling turns it into a text character. A remappable binding (e.g. via ~/.claude/keybindings.json) would let users pick a chord their terminal actually passes through.

Current behavior

The agent-view session shortcuts appear to be fixed. On the environments below, they cannot be triggered at all:

| Environment | What happens to Alt+1 |
| --- | --- |
| GNOME Terminal / Konsole / Tilix / Terminator | Consumed by the emulator as "switch to tab 1"; never reaches the TUI |
| macOS Terminal.app (default settings) | "Use Option as Meta key" is off, so ⌥1 emits ¡ |
| iTerm2 (default profile) | Option is set to Normal unless the user changes it to Esc+ |
| Windows Terminal | Alt-prefixed chords are partly reserved; Ctrl+Alt+<n> is the convention there |

Notably, the binding itself works fine once the key sequence actually reaches the TUI. Sending it from tmux — tmux send-keys M-1, which writes the escape sequence straight into the pane and bypasses the emulator's own key handling — switches sessions exactly as documented. So this is not a bug in the agent view; the sequence is simply intercepted before it gets there in normal interactive use.

There is also an inherent ambiguity: Alt+1 reaches the application as the byte sequence ESC 0x31, so distinguishing it from a bare Esc followed by a 1 keystroke depends on a timing heuristic.

Desired behavior

  • Allow the agent-view session shortcuts to be rebound in ~/.claude/keybindings.json, consistent with other remappable bindings
  • Support a prefix/chord form as an alternative to a single modified key, since prefix styles (Ctrl-b <n> in tmux, Ctrl-x chords) are immune to emulator interception
  • Have ? in agent view display the effective binding rather than a hardcoded one, so the help text stays correct after remapping

Why

The shortcut is most valuable to people running many parallel sessions, and that group skews toward Linux terminal emulators — exactly the environments where Alt+<n> is already taken by tab switching. Without a remap path, the feature is silently unusable there, and the failure mode looks like a bug rather than a key conflict.

Raised because a collaborator invited follow-ups in #85468.

🤖 Generated with Claude Code

View original on GitHub ↗