Make agent-view session shortcuts remappable (`Alt+<n>` is unavailable in several terminals)
Summary
Follow-up to #85468. Alt+1–Alt+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-xchords) 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