---
title: Running inside tmux
description: Host tmux settings required for Shift+Enter, focus events, and mouse support when running jackin inside a tmux session
---
import { Aside } from '@astrojs/starlight/components'

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. The container's internal tmux is configured automatically by jackin; you do not need to touch it.
</Aside>

## 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

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

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