Mouse Mode and Selection
Kitty provides rich mouse support — click to focus windows, select text on drag, middle-click to paste, and open URLs or file paths with a click. Mouse actions are fully configurable.
Mouse selections and URL hints save time during ad-hoc log inspection and documentation reading. Learn them, but rely on keyboard shortcuts for daily navigation.
Mouse Support Overview
Kitty mouse mode is always on — there is no toggle like tmux's set -g mouse. Kitty natively handles mouse events for window focus, text selection, and click actions.
Copy-on-Select Behavior
By default, kitty copies text to the clipboard as soon as you release the mouse after a selection:
1. Click and drag to select text
└── Text is highlighted (inverted colors)
2. Release mouse button
└── Text is copied to system clipboard automatically
└── No manual Ctrl+Shift+C needed for simple selections
Copy-on-select puts text directly into the system clipboard (not a kitty-internal buffer). You can paste it anywhere with Ctrl+Shift+V or middle-click.
Middle-Click Paste
Middle-clicking (scroll wheel button) pastes the primary selection (X11) or the clipboard content, depending on your platform and configuration:
# Control middle-click paste behavior
mouse_map middle press ungrabbed paste_selection
mouse_map middle press grabbed paste_selection
# Or disable middle-click paste
# mouse_map middle press ungrabbed none
Configuring Mouse Actions
Mouse actions are mapped using mouse_map directives:
# Syntax: mouse_map button event modifiers action
# Click on a window to focus it (default)
mouse_map left press ungrabbed focus_window
# Ctrl+Shift+click to open URL under cursor
mouse_map ctrl+shift left release grabbed open_url
# Double-click selects word, triple-click selects line (built-in)
# Right-click context menu
mouse_map right press ungrabbed show_scrollback
Mouse Action Table
| Directive | Action |
|---|---|
mouse_map left press ungrabbed | Focus window under cursor |
mouse_map left press grabbed | Focus grabbed window |
mouse_map left release ungrabbed | Copy selection to clipboard |
mouse_map middle press ungrabbed | Paste primary selection |
mouse_map right press ungrabbed | Show scrollback context menu |
mouse_map ctrl+shift left release grabbed | Open URL at cursor |
The ungrabbed vs grabbed modifier refers to whether a kitty window is currently "grabbing" the mouse (e.g., a full-screen TUI app like htop or vim).
URL Hints (Ctrl+Shift+e)
Kitty has a dedicated URL hinting mechanism:
Ctrl+Shift+e → Activate URL hints
When pressed, kitty highlights all URLs and file paths visible on screen. Each gets a numeric hint or fuzzy-match label:
┌─────────────────────────────────────────────┐
│ Visit https://example.com/docs [1] │
│ Check file:///var/log/syslog [2] │
│ Clone git@github.com:user/repo.git [3] │
│ │
│ Press 1, 2, or 3 to open — or type part │
│ of the URL to fuzzy-match. │
└─────────────────────────────────────────────┘
Press the number or start typing to filter. Enter opens the URL. Esc cancels.
Use URL hints to open GitHub links, documentation URLs, or file paths during log inspection without touching your mouse.
The open_actions Feature
Kitty can be configured with open actions — rules that determine how different types of content are opened when clicked or activated:
# Map file extensions to actions
open http* with firefox
open https* with firefox
open *.log with vim
open *.py with code
open /tmp/* with vim
# Default: open with xdg-open
open * with xdg-open
Create this file at ~/.config/kitty/open-actions.conf and kitty will use it for URL hints and click actions.
# Enable open actions config
open_actions ~/.config/kitty/open-actions.conf
Be careful with open actions for unknown file types. Configure only the patterns you frequently use to avoid accidental execution.
Mouse Scrolling and Scrollback
Kitty treats scrollback as a first-class feature. Use Ctrl+Shift+↑/↓ or the mouse wheel:
| Mouse Action | Effect |
|---|---|
| Scroll wheel up | Scroll back in history |
| Scroll wheel down | Scroll forward |
| Shift+scroll wheel | Scroll horizontally |
| Ctrl+Shift+click on scrollback | Open URL under cursor |
Copy Mode Alternative
For precise selection without the mouse, use kitty's selection operations from the command palette (Ctrl+Shift+p) or keyboard shortcuts:
| Shortcut | Action |
|---|---|
Ctrl+Shift+c | Copy selection to clipboard |
Ctrl+Shift+v | Paste from clipboard |
Ctrl+Shift+s | Paste from primary selection |
Ctrl+Shift+o | Pass selection to external program |
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| Copy-on-select copies unintended text | Wrong content in clipboard | Use Ctrl+Shift+c for manual copy instead of drag-select |
| Middle-click pastes differently on Wayland | Pastes wrong content | Install wl-clipboard and configure primary_selection in kitty.conf |
| URL hints don't show | Modifier not recognized | Press Ctrl+Shift+e precisely — hold both modifiers before pressing e |
| Open actions not working | Click does nothing | Verify open_actions path in kitty.conf and check the file syntax |
| Mouse grabbed by TUI app | Can't select terminal text | Shift+click bypasses grab and uses terminal-native selection |
Hands-On Practice
# 1) Open kitty and run a command that produces URLs
echo "Visit https://kitty.app/docs for documentation"
echo "Or check file:///home/user/projects/readme.md"
# 2) Press Ctrl+Shift+e to activate URL hints
# Type part of the URL to filter, press Enter to open
# 3) Test copy-on-select:
# Drag-select a portion of text → release → text is copied
# Middle-click somewhere to paste it
# 4) Configure a custom open action:
mkdir -p ~/.config/kitty
cat > ~/.config/kitty/open-actions.conf << 'EOF'
open *.txt with vim
open *.md with vim
open https* with firefox
open * with xdg-open
EOF
# 5) Add the open_actions directive to kitty.conf if not present
grep -q "open_actions" ~/.config/kitty/kitty.conf 2>/dev/null || \
echo "open_actions ~/.config/kitty/open-actions.conf" >> ~/.config/kitty/kitty.conf
# 6) Reload config
kitty @ load-config