d0ugal / d0ugal/graith

Make terminal input gestures configurable per agent

Open
#1,906 0 comments 0 reactions 0 assignees View on GitHub
size: M
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.