Make terminal input gestures configurable per agent
- Dominant language
- Go
- Stars
- 2
- Forks
- 0
- Avg merge
- 5h 49m
- Merged PRs (30d)
- 189
Description
## Problem
`gr attach` now has a working terminal scrollback pager, and mapping mouse wheel-up to that pager is useful for coding-agent sessions. Making wheel capture unconditional is risky, though: some attached programs deliberately own mouse-wheel input via mouse tracking or alternate-screen alternate-scroll behavior.
Related: #1899 fixed the scroll pager content refresh path so entering scroll mode can show current terminal-owned history instead of a stale attach seed.
We should make terminal input gestures configurable per agent so built-in coding agents can get ergonomic defaults while custom/interactive agents can opt out or choose a different policy.
## Proposed direction
Prefer typed gestures mapped to graith actions/results, not arbitrary raw escape-code bindings. Raw terminal bytes are too mode-dependent: mouse reporting, SGR encoding, coordinates, modifiers, and alternate-screen behavior all affect what bytes arrive.
A possible config shape:
```toml
[input]
# off | auto | always
mouse_wheel_policy = "off"
[input.bindings]
mouse_wheel_up = "scroll_mode"
shift_mouse_wheel_up = "scroll_mode"
[agents.codex.input]
mouse_wheel_policy = "auto"
[agents.claude.input]
mouse_wheel_policy = "auto"
[agents.some-tui.input]
mouse_wheel_policy = "off"
```
Suggested wheel policies:
- `off`: current behavior; do not capture wheel input for graith history.
- `auto`: trigger the configured graith action only when the child is not actively using mouse tracking and is not relying on alternate-screen alternate-scroll.
- `always`: prefer the configured graith action even when the child might otherwise receive wheel events. This should be opt-in because it can break apps that own the wheel.
Suggested initial gestures:
- `mouse_wheel_up`
- `mouse_wheel_down`
- `shift_mouse_wheel_up`, if modifiers are reliable enough across supported terminals
- `shift_mouse_wheel_down`, if modifiers are reliable enough across supported terminals
Suggested initial actions/results:
- `scroll_mode`: enter graith's terminal history pager.
- `none`: explicitly disable a binding at a more specific config layer.
The first implementation can stay deliberately small: wheel gestures plus `scroll_mode`/`none`. The important design point is that the config should map semantic gestures to graith actions, leaving room to add actions later without exposing terminal escape-code internals.
Open design questions:
- Should built-in coding agents default to `auto` while the global fallback remains `off` for unknown/custom agents?
- Should per-agent config use `[agents..input]` for future input settings, or flat keys on `[agents.]` for consistency with existing agent options?
- Can modifier-wheel gestures be detected consistently enough to document them as portable?
## Acceptance criteria
- Config supports global input gesture defaults and per-agent overrides.
- Invalid wheel policies, gesture names, and action names fail config validation with clear errors.
- The effective input config is resolved from the attached session's `AgentName`, including when switching/adopting sessions inside attach.
- `auto` does not steal wheel events from child apps that have enabled mouse tracking or alternate-screen alternate-scroll.
- `always` is documented as potentially stealing wheel events from child apps.
- The initial implementation maps at least `mouse_wheel_up = "scroll_mode"` for agents that opt into `auto` or `always`.
- User docs and generated/default config comments are updated.
- Tests cover config validation, global/per-agent resolution, and terminal-owned input routing for the supported policies.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by tracing `gr attach`, the attached session's `AgentName` resolution, and the existing terminal scrollback pager and input-routing paths. Review config validation, user documentation, generated/default config comments, and related tests before deciding how global and per-agent settings fit together. Done means the accepted policies and mappings resolve correctly and tests cover validation, overrides, and terminal-owned input behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100