atxtechbro / atxtechbro/dotfiles
iTerm2 mouse input not working with tmux (and other applications)
- 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