# Running inside tmux (https://jackin.tailrocks.com/guides/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.

<Aside type="note">
  These settings apply to the **host tmux** — the session you start `jackin console` inside. jackin❯ does not run tmux inside the container — agent sessions live inside an in-container multiplexer that jackin❯ manages directly — so there is no container-side tmux configuration to touch.
</Aside>

## Required configuration [#required-configuration]

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

```sh
# 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:

```sh
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 [#what-each-setting-does]

### `extended-keys` — fixes Shift+Enter [#extended-keys--fixes-shiftenter]

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 [#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 [#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 [#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 [#version-requirements]

| Setting                | Minimum tmux version |
| ---------------------- | -------------------- |
| `extended-keys always` | 3.2a                 |
| `terminal-features`    | 3.2                  |
| `allow-passthrough on` | 3.3                  |
| `focus-events on`      | 1.8                  |
| `mouse on` (unified)   | 2.1                  |

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`.