atxtechbro / atxtechbro/dotfiles

iTerm2 mouse input not working with tmux (and other applications)

Open
#415 1 comment 0 reactions 0 assignees View on GitHub
high-priority
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Problem

Mouse input is not working properly in iTerm2, affecting multiple applications:

1. **tmux**: Clicking on panes does not select/focus them (only Option+h/l navigation works)
2. **Scrolling**: Cannot scroll when zoomed in too much
3. **General mouse events**: Applications don't seem to receive mouse events properly

**SEVERITY: HIGH** - This severely hampers development workflows on macOS

## Expected Behavior

- Clicking on a tmux pane should immediately make it active/focused
- Mouse scrolling should work regardless of zoom level
- Applications should receive mouse events as expected

## Current Workarounds

- Using Option+h/l for tmux pane navigation
- Avoiding high zoom levels to maintain scroll functionality

## Investigation Done

### tmux Configuration
- ✅ `set -g mouse on` is enabled
- ✅ Mouse bindings are present: `bind-key -T root MouseDown1Pane select-pane -t=`
- ✅ tmux shows mouse support enabled: `#{mouse}` returns `1`

### iTerm2 Configuration Attempts
- ✅ `MouseReporting = 1` in defaults
- ✅ `ScrollWheelSendsArrowKeysInAlternateScreenMode = false`
- ✅ `AlternateMouseScroll = false`
- ✅ `FocusReporting = true`
- ✅ Restarted iTerm2 multiple times

### Diagnostic Results
- tmux receives and processes mouse bindings correctly (visible in `tmux list-keys`)
- Mouse events may not be reaching tmux from iTerm2 at all
- Issue persists across tmux server restarts

## Speculation

The issue appears to be in the **iTerm2 → application communication layer** rather than tmux configuration. Possible causes:

1. **Profile-specific settings** overriding global mouse settings
2. **System accessibility/security settings** blocking mouse events
3. **iTerm2 version compatibility** issues with mouse reporting
4. **Terminal escape sequence handling** problems
5. **macOS system-level input interception**

## Environment

- **OS**: macOS
- **Terminal**: iTerm2
- **tmux**: 3.5a
- **Terminal type**: `screen-256color`

## Next Steps

- [ ] Monitor for other mouse-related issues in different applications
- [ ] Test with alternative terminal emulators (Terminal.app, Alacritty)
- [ ] Check system accessibility/security settings
- [ ] Investigate iTerm2 profile-specific mouse configurations
- [ ] Test raw mouse event reporting outside of tmux

## Impact

**HIGH PRIORITY** - This severely hampers development workflows on macOS. Basic UI interactions should work reliably in a properly configured development environment.

---

*Following the Spilled Coffee Principle: if we can't control basic terminal interactions, it suggests gaps in our environment setup that could affect other tools.*

Contributor guide

No contributing guide indexed for this repository

Research direction

No repository files or tests are identified; begin by reproducing the mouse behavior in iTerm2 with tmux 3.5a and the stated screen-256color environment. Compare raw mouse reporting with another terminal and inspect the listed iTerm2, tmux, and macOS settings. Done means identifying a reproducible configuration or code-level cause and documenting a verified fix.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos
Domain
cli, operating-systems
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.