Investigate tmux focus-events and its implications for the in-browser terminal #187
Labels
No labels
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
lz/agent-nexus#187
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Context
The in-browser session terminal (AGENTS.md fact #14) bridges xterm.js in the
operator's browser to a
docker execPTY attached to a grouped tmux session(
-t nexus, group member with its own active-window pointer). Neitherworker/entrypoint.shnor the tmux invocation interminal/upgrade.tshasbeen reviewed for what
focus-events(set-option -g focus-events on|off,tmux default: off) is set to, or what changing it would mean for this
pipeline. This issue tracks investigating that, not a known bug report.
What focus-events does
When on, tmux both (a) tracks whether its own client has terminal focus, and
(b) forwards the outer terminal's focus in/out escape sequences (
\x1b[I/\x1b[O) through to whatever program is running in the active pane. Off(the default), those sequences are not forwarded, so any pane program that
wants focus changes — an editor with a focus-lost autosave, some REPLs, and
potentially claude-code's own TUI — never learns about them.
Why this might matter here
escape sequences into the PTY. Whether that ever reaches the pane
application depends on tmux's
focus-eventssetting somewhere on the pathin between.
the reverse — something downstream expects them and never gets them), the
likely failure shape is the same class of bug as the xterm/IME composition
issue already found in this codebase's terminal stack: stray escape bytes
rendered as literal text, or a session silently never learning it
gained/lost focus.
(
idle_prompt,agent_needs_input, etc. — AGENTS.md fact #26). If any ofclaude-code's own behavior is sensitive to terminal focus state, and that
state never correctly reaches it through this bridge, that's worth knowing
either way — whether or not it's currently causing a visible symptom.
What to investigate
worker/entrypoint.sh, orwhatever sets up the
nexussession) setsfocus-eventsto today — mostlikely unset, i.e. tmux's default off — and whether xterm.js's terminal
instance on the frontend has focus reporting enabled.
focus-events onserver-side changes anything observablein a real session (rendering artifacts, claude-code behavior change, or
nothing at all).
sequences visible in the terminal on a focus change) or this is a latent
gap with no current symptom.
No fix is proposed here — this is scoped as an investigation.