Running inside tmux

If you run jackin console inside a tmux session, a few host-side tmux settings are required for agents to receive the full keyboard and terminal experience they expect. Without them, Shift+Enter collapses to plain Enter, focus events are lost, and desktop notifications never reach your terminal.

Required configuration

Add the following lines to your ~/.tmux.conf:

# Pass Shift+Enter and other modified keys through to the agent (tmux 3.2a+)
set -s extended-keys always
set -as terminal-features 'xterm*:extkeys'

# Let editors know when their pane gains or loses focus
set -g focus-events on

# Pass OSC sequences through to the outer terminal (desktop notifications, progress bars)
set -g allow-passthrough on

# Eliminate the Escape-key ambiguity delay — important for TUI agents
set -sg escape-time 0

Reload without restarting tmux:

tmux source-file ~/.tmux.conf

If you also want mouse scrollback and pane interaction, add set -g mouse on. This is a personal preference — some operators prefer scroll events to reach the terminal emulator directly.

What each setting does

extended-keys — fixes Shift+Enter

tmux by default collapses modifier+key combinations before forwarding them to the inner pane. Shift+Enter arrives at the agent as plain Enter, which submits the prompt instead of inserting a newline.

set -s extended-keys always forwards extended key sequences (modifyOtherKeys format) unconditionally, without waiting for the inner app to opt in via an activation escape. set -as terminal-features 'xterm*:extkeys' advertises that capability to inner panes so their terminfo queries confirm support.

Requires tmux 3.2a or later.

focus-events — editor file reloads

When enabled, tmux emits FocusIn and FocusOut escape sequences to the active pane when the tmux window gains or loses OS focus. Editors running alongside an agent (Neovim, Helix, etc.) use these events to re-read files that the agent modified while the editor was in the background, keeping the display current without a manual reload.

allow-passthrough on — desktop notifications and progress bars

tmux-aware tools (Claude Code, iTerm2 inline images, etc.) wrap their OSC sequences in a DCS passthrough escape when they detect $TMUX. With allow-passthrough on, tmux forwards those DCS-wrapped sequences to the outer terminal so desktop notifications, progress bars, and clipboard writes reach iTerm2, Ghostty, Kitty, etc. Tools that emit raw OSC without DCS wrapping require allow-passthrough all (tmux 3.4+) instead.

Requires tmux 3.3 or later.

escape-time 0 — Escape key latency

tmux waits after a bare Escape to decide whether it is a key prefix or a standalone key. Agents use Escape constantly for TUI navigation (vi-mode, modal editors, menu dismissal), and the delay causes misfired key sequences. Setting this to 0 removes the ambiguity window.

Version requirements

Check your version with tmux -V. On macOS, the system tmux (from Xcode Command Line Tools) is typically too old — install a current version via Homebrew: brew install tmux.