1jehuang / 1jehuang/jcode

bug: Keyboard protocol stack (CSI u) not cleared on exit, breaking Shift+Space inside tmux

Open
#898 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug needs-info triage: unclear
Dominant language
Rust
Stars
19.9k
Forks
2.3k
Avg merge
2d 7h
Merged PRs (30d)
30

Description

Description:

When exiting jcode via /exit, the terminal state is not properly restored for sessions nested inside tmux. Specifically, jcode fails to clear the Kitty Keyboard Protocol (CSI u) from the terminal's keyboard stack upon graceful shutdown.Because tmux intercepts standard terminal escape sequences, the underlying terminal emulator (iTerm2) remains permanently locked in an enhanced keyboard state. This causes downstream applications like Vim to misinterpret Shift+Space as an escape byte sequence, throwing the editor out of Insert mode and dropping it back into Normal mode.

Environment:
  • OS: macOS
  • Terminal Emulator: iTerm2
  • Shell: zsh
  • Multiplexer: tmux
Steps to Reproduce:
  • Start an iTerm2 session and attach to tmux.
  • Launch jcode.
  • Exit gracefully using the /exit command.
  • shift+space previously was interpreted as space in my setup. Now, it is overridden to change the modality of my terminal to NORMAL mode.
Expected Behavior:

jcode should completely pop its modified keyboard protocol configurations from the screen stack on shutdown so that Shift+Space continues to be evaluated normally as a standard space character.

Suggested Fix:

The application needs to explicitly pop/clear the enhanced keyboard protocol stack during its cleanup sequence. To account for multiplexers like tmux, the cleanup routing needs to bypass tmux by wrapping the sequences in a pass-through format (\ePtmux;...\e\) if a $TMUX environment variable is active. The specific fallback escape sequences required to force-wipe all levels of the Kitty Keyboard and XTerm modifier stacks are:

# Inside tmux (requires doubled escapes for pass-through):
printf '\ePtmux;\e\e[<u\e\e[>4;0m\e\\'

# Standard fallback (outside tmux):
printf '\e[<u\e[>4;0m'
Temporary Fix:

Add this bash function to .zshrc :

jcode() {
    command jcode "$@"
    
    # Check if we are currently running inside a tmux session
    if [ -n "$TMUX" ]; then
        # Pass the sequences directly through tmux to iTerm2
        printf '\ePtmux;\e\e[<u\e\e[>4;0m\e\\'
    else
        # Standard fallback if run outside of tmux
        printf '\e[<u\e[>4;0m'
    fi
    
    # Restore general line modes and clear the alternate screen buffer
    printf '\e[?1049l\e[0m'
    stty sane
    clear
}

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Begin at the /exit graceful-shutdown cleanup path and trace how terminal keyboard modes are restored, especially when TMUX is set. Reproduce in iTerm2 inside tmux, then verify that exiting jcode leaves Shift+Space working in Vim and that the proposed Kitty/XTerm reset sequences are sent through tmux.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.