Custom Gestures

Fast One-Handed Control for Mobile Terminals

Mobile touchscreens lack physical Function keys, Ctrl keys, and arrow buttons. Hunting through screen toolbars or popping open the software keyboard just to send a single keystroke slows down your workflow. Custom Gestures unlocks touch gesture sequences, allowing you to trigger complex terminal commands, navigation actions, and direct terminal keycodes using fluid tap and swipe movements.

Sending Terminal Keys and Action Bindings via Gestures

In addition to navigating UI elements, Casshper gestures can directly dispatch low-level terminal keycodes straight to the active shell, as well as trigger application Action Bindings. This enables completely keyboard-free terminal control:

• Ctrl+C (Process Interrupt / SIGINT): Dispatch Ctrl+C keycode sequences directly to the active shell session. Terminate runaway scripts, stop tail -f logs, or cancel command prompts in a fraction of a second with a single gesture, without needing to open the on-screen keyboard or hunt for an on-screen button.
• Escape (Modal Exit): Send the Escape keycode directly to running terminal applications. Perfect for instantly exiting Vim/Neovim INSERT mode, cancelling fzf fuzzy searches, or clearing interactive CLI prompts without sacrificing vertical viewport space to a permanent Escape key.
• Paste Clipboard: Inject the current Android clipboard contents directly into the terminal input buffer with zero keystrokes.
• Text Selection and Actions: Initiate word and character selection, toggle the keyboard, or switch sessions. See Action Bindings and Terminal Commands for complete details on supported actions.

Immediate Execution Mode (⚡ Zero-Latency Triggers)

By default, Casshper uses a 300ms evaluation timer to detect multi-step gesture combinations (such as distinguishing between a single tap and the beginning of a double-tap sequence). For critical key-sending shortcuts where you want instant response, you can enable Immediate Execution (⚡):

• Standard Mode: The gesture engine waits up to 300ms after the final touch release to verify whether additional taps or swipes follow before resolving the action.
• Immediate Mode (⚡): The engine executes the bound keycode or action immediately upon completing the final touch stroke without waiting for the trailing timeout. This provides instant, zero-latency feedback for time-sensitive shortcuts like interrupts and modal exits.

Operational Key Modes in Touch Gestures (Press, Latch, Toggle)

Touch gestures configured with Keycode (KEYCODE) bindings support all three tactile operational key modes, bridging touch motions directly into sticky and modal keyboard states:

• Press (Momentary): Dispatches the keycode and its modifiers immediately upon gesture recognition. This is standard for quick triggers like Escape, Return, or Ctrl+C.
• Latch (One-Shot / Sticky Modifier): Arms a modifier or key sequence for the very next keystroke typed on your keyboard or soft-key bar. For example, assign a gesture to latch Ctrl or Ctrl+B (tmux prefix). Swiping arms the modifier; typing your next key consumes the armed state and automatically dispatches the combination.
• Toggle (Persistent Switch): Toggles the modifier key (such as Ctrl, Alt, or Shift) continuously locked on until you execute the gesture a second time or tap to clear it. Ideal for prolonged selection or navigation modes without physical modifier keys.

In the gesture list, non-momentary gestures are clearly labeled with a badge suffix such as (Latch) or (Toggle) (e.g. Ctrl+B (Latch) or Shift (Toggle)) so you always know their operational mode at a glance.

Hardware Modifiers, Chording and Bypass XKB Mode

When mapping a gesture to a keycode, the gesture editor provides fine-grained modifier chording and byte-level control:

• Simultaneous Modifier Bitmasks: Combine any keycode with simultaneous Ctrl, Alt, and Shift modifier checkboxes (for example, creating a single gesture that fires Ctrl+Shift+F or Alt+Enter).
• Raw Bytes and Bypass XKB Mode: Toggle Raw Bytes (Bypass XKB) to stream raw byte values directly to the PTY session, bypassing XKB layout translation. This is crucial for special control sequences and non-standard terminal emulations.

Built-in Gesture Shortcuts

• Tap (Tap): Direct terminal click and cursor positioning at touch coordinates.
• Long Press (Long Press ⚡): Precision word text selection (Select Word) at the touch point with zero-latency immediate execution.
• Tap + Long Press (Tap + Long Press ⚡): Precision character text selection (Select Character) for fine-grained token extraction with immediate execution.
• Double Tap (Tap + Tap): Toggle the virtual software keyboard on or off instantly.
• Double Tap + Swipe Left (Tap + Tap + Swipe Left): Switch to the previous active session tab.
• Double Tap + Swipe Right (Tap + Tap + Swipe Right): Switch to the next active session tab.
• Double Tap + Swipe Up (Tap + Tap + Swipe Up): Quick-paste clipboard buffer directly into the active shell session.
• Triple Tap (Tap + Tap + Tap): Open the Sneaky Input overlay dialog.

Supported Gesture Bindings Reference

Gestures can trigger low-level hardware keycodes (KEYCODE), freeform text macros (TEXT), or high-level application action bindings (ACTION). While terminal keystrokes like Escape and Ctrl+C are handled via keycode dispatch (or command macros via text), high-level commands like session management, keyboard toggles, and toolbar swapping are handled via action bindings. For a comprehensive catalog of all action triggers and command specifications, see Action Bindings and Terminal Commands.

Configuring Custom Key and Navigation Gestures

1. Open Casshper and open the sidebar menu to select Settings.
2. Select the Touch Gestures tab.
3. Under Custom Touch Gestures, tap + New Gesture (or tap an existing gesture row or edit button to modify it).
4. Perform your touch sequence on the interactive Record Touch Gesture pad (combining taps and directional swipes).
5. Select your target binding:
   • Keycode (KEYCODE): Configure your keycode using the streamlined editor flow:
     1. Keycode: Select a preset key (e.g. Esc, Tab, Return, Ctrl, F1–F12) or enter a custom ASCII hex keycode (e.g. 0x43 for 'C').
     2. Modifiers: Check any desired modifier bitmasks (Ctrl, Alt, Shift).
     3. Key Mode: Tap the Key Mode button to cycle between PRESS, LATCH, and TOGGLE.
     4. Raw Bytes: Optionally toggle Raw Bytes (Bypass XKB) for direct stream injection.
   • Text (TEXT): Enter literal text command snippets (e.g. git status\n).
   • Action (ACTION): Pick an application command like Paste Clipboard, Toggle Keyboard, Next Session, Sneaky Input, or Swap Soft-Key Bar.
6. (Optional) Enable Immediate Execution (⚡) if you want zero-delay dispatch on the sequence completion.
7. Tap Save Gesture, then tap Save Settings to activate your new shortcut!

Workflow Recipes

Vim / Neovim Modal Switching

Map Tap + Swipe Up to Escape with Immediate Execution enabled. While editing code in Neovim on your phone, a quick upward flick instantly drops you out of INSERT mode into NORMAL mode without having to reach for a toolbar button or open the full keyboard.

Emergency Process Interrupt

Map Tap + Swipe Down to Ctrl+C with Immediate Execution enabled. If a script starts dumping runaway log output or an SSH command hangs, a single swipe downwards immediately kills the process via SIGINT.

One-Shot Latched Multiplexer Prefix

Map Tap + Swipe Right to Ctrl+B (or Ctrl+A for screen) in Latch mode. While working in tmux, a flick to the right arms your multiplexer prefix for the very next keypress. Tap % on your keyboard to split panes horizontally or c to spawn a new window without clumsy chord gymnastics.

Multiplexer and Tool Switching

Pair gestures with Multi-Soft Key Bars by mapping a gesture to Swap Soft-Key Bar or Cycle Soft-Key Bar. You can switch between a general coding key bar and a dedicated tmux and Screen Bar with a single gesture motion.