​
VibeTunnel Keyboard Shortcuts

VibeTunnel provides a comprehensive set of keyboard shortcuts for efficient terminal session management. The app intelligently handles keyboard input to balance browser functionality with terminal control.

​
Keyboard Capture Modes

VibeTunnel operates in two keyboard capture modes:

​
1. Capture Active (Default)

  • Most keyboard shortcuts are sent to the terminal
  • Critical browser shortcuts remain functional
  • Indicated by the keyboard icon in the session header

​
2. Capture Disabled

  • Browser shortcuts take precedence
  • Terminal receives only typed text
  • Toggle with double-press Escape

​
Toggling Keyboard Capture

ActionDescription
Double EscapeToggle keyboard capture on/off
Press Escape twice within 500ms to toggle between capture modes.

​
Critical Browser Shortcuts (Always Available)

These shortcuts always work, regardless of keyboard capture state:

​
Tab Management

macOSWindows/LinuxAction
⌘TCtrl+TNew tab
⌘WCtrl+WClose tab
⌘⇧TCtrl+Shift+TReopen closed tab
⌘1-9Ctrl+1-9Switch to tab 1-9*
⌘0Ctrl+0Switch to last tab*
*When keyboard capture is active in session view, these shortcuts switch between VibeTunnel sessions instead of browser tabs

​
Window Management

macOSWindows/LinuxAction
⌘NCtrl+NNew window
⌘⇧NCtrl+Shift+NNew incognito window
⌘QCtrl+QQuit browser
⌘H-Hide window (macOS)
-Alt+F4Close window (Windows)

​
Essential Operations

macOSWindows/LinuxAction
⌘CCtrl+CCopy
⌘VCtrl+VPaste
⌘ACtrl+ASelect all*
⌘,-Preferences (macOS)
*When capture is active, ⌘A/Ctrl+A goes to terminal (moves cursor to line start)

​
Developer Tools

macOSWindows/LinuxAction
F12F12Open DevTools
⌘⌥ICtrl+Shift+IOpen DevTools

​
VibeTunnel-Specific Shortcuts

macOSWindows/LinuxActionContext
⌘KCtrl+KCreate new sessionAny view
⌘OCtrl+OBrowse filesList view
⌘BCtrl+BToggle sidebarAny view
EscapeEscapeReturn to listSession/File browser

​
Session Switching (When Keyboard Capture Active)

macOSWindows/LinuxActionContext
⌘1…9Ctrl+1…9Switch to session 1 to 9Session view with capture ON
⌘0Ctrl+0Switch to session 10Session view with capture ON
Note: When keyboard capture is active in session view, number shortcuts switch between VibeTunnel sessions instead of browser tabs. The session numbers correspond to the numbers shown in the session list. This allows quick navigation between active sessions without leaving the keyboard.

​
Terminal Shortcuts (When Capture Active)

When keyboard capture is active, these shortcuts are sent to the terminal:

​
Cursor Movement

macOSWindows/LinuxTerminal Action
⌘ACtrl+AMove to line start
⌘ECtrl+EMove to line end
⌥←Alt+LeftMove word backward
⌥→Alt+RightMove word forward

​
Text Editing

macOSWindows/LinuxTerminal Action
⌘WCtrl+WDelete word backward
⌘UCtrl+UDelete to line start
⌘KCtrl+KDelete to line end
⌥⌫Alt+BackspaceDelete word backward
⌥DAlt+DDelete word forward
macOSWindows/LinuxTerminal Action
⌘RCtrl+RReverse history search
⌘PCtrl+PPrevious command
⌘NCtrl+NNext command

​
Terminal Control

macOSWindows/LinuxTerminal Action
⌘LCtrl+LClear screen
⌘DCtrl+DEOF/Exit
⌘CCtrl+CInterrupt process
⌘ZCtrl+ZSuspend process

​
Shortcuts Behavior by Capture State

​
When Capture is Active ✅

These shortcuts go to the terminal:
  • Text editing (⌘A, ⌘E, ⌘W, ⌘K, ⌘U)
  • Navigation (⌘F, ⌘B for forward/backward char)
  • Terminal control (⌘L, ⌘D, ⌘R)

​
When Capture is Disabled ❌

These shortcuts perform browser actions:
  • ⌘F/Ctrl+F - Find in page
  • ⌘L/Ctrl+L - Focus address bar
  • ⌘D/Ctrl+D - Bookmark page
  • ⌘P/Ctrl+P - Print
  • ⌘S/Ctrl+S - Save page

​
Special Key Handling

​
Modified Enter Key

CombinationTerminal Receives
EnterStandard return
Ctrl+EnterSpecial control sequence
Shift+EnterSpecial shift sequence

​
Function Keys

  • F1-F12 are sent to the terminal when capture is active
  • F5 (Refresh) works in browser when capture is disabled
  • F11 (Fullscreen) always works

​
Platform Differences

​
macOS

  • Uses ⌘ (Command) as primary modifier
  • ⌥ (Option) for word navigation
  • Additional shortcuts like ⌘H (Hide), ⌘M (Minimize)

​
Windows/Linux

  • Uses Ctrl as primary modifier
  • Alt for word navigation
  • Alt+F4 closes windows

​
Tips

  1. Double-tap Escape to quickly toggle between terminal and browser shortcuts
  2. Critical shortcuts (new tab, close tab, copy/paste) always work
  3. Session switching (⌘1-9, ⌘0) - When keyboard capture is ON in session view, quickly switch between active sessions
  4. Tab switching (⌘1-9, ⌘0) - When keyboard capture is OFF, switch browser tabs as usual
  5. When unsure, check the keyboard icon in the session header to see capture state

​
Troubleshooting

​
Shortcuts not working as expected?

  1. Check keyboard capture state - Look for the keyboard icon in the session header
  2. Try double-escape - Toggle capture mode on/off
  3. Browser shortcuts in terminal? - Ensure keyboard capture is active
  4. Terminal shortcuts in browser? - Disable keyboard capture with double-escape

​
Copy/Paste issues?

  • Standard copy/paste (⌘C/⌘V or Ctrl+C/Ctrl+V) always works
  • For terminal copy mode, use the terminal’s built-in shortcuts
  • Right-click context menu is always available

​
Implementation Details

The keyboard shortcut system is implemented in:
  • web/src/client/utils/browser-shortcuts.ts - Centralized shortcut detection
  • web/src/client/components/session-view/input-manager.ts - Terminal input handling
  • web/src/client/app.ts - Application-level shortcut handling
The system uses a priority-based approach:
  1. Critical browser shortcuts (highest priority)
  2. VibeTunnel app shortcuts
  3. Terminal shortcuts (when capture active)
  4. Browser defaults (when capture disabled)