# tmux terminal setup — Claude Code prompt

From: https://intlo.com/news/tmux-for-agent-sessions

## Goal
Make every new window of **the terminal app this session is running in** open straight into a persistent tmux session called `main`, set sane tmux defaults, and verify. The run must be idempotent (safe to run twice) and must not kill or disturb any tmux session that is already running.

## Rules
- Back up before editing: `~/.zshrc` → `~/.zshrc.bak-<YYYYMMDD-HHMMSS>`, and the same for `~/.tmux.conf` if it exists.
- Never run `tmux kill-server` or `tmux kill-session`. Existing sessions (Claude Code, Codex, other agents) must survive.
- Only change the startup behaviour of the one terminal app identified in step 2. Editor terminals (VS Code, Cursor, JetBrains), SSH logins and scripted shells must keep opening a plain shell.
- Wrap every block you add in the marker comments `# >>> tmux-terminal >>>` and `# <<< tmux-terminal <<<`. On a re-run, replace what is between the markers instead of appending again.
- This prompt assumes macOS and zsh. If either is not true, stop and report what you found.

## Steps

1. **Is tmux installed?** Run `command -v tmux || brew install tmux`, then report the version (`tmux -V`).

2. **Identify the terminal app.** Read `$__CFBundleIdentifier` and `$TERM_PROGRAM` from the current shell.
   - If `$TMUX` is set, this shell is already inside tmux and `TERM_PROGRAM` will say `tmux`. Get the real values another way: `tmux show-environment -g __CFBundleIdentifier`, or ask the user which app they use and read its bundle ID with `osascript -e 'id of app "<App Name>"'`.
   - Match on `__CFBundleIdentifier` if you can, because it is the most reliable. Fall back to `TERM_PROGRAM` only if the bundle ID is unavailable.
   - If the result is an editor (for example `com.microsoft.VSCode`) or nothing identifies a terminal app, stop and tell the user exactly what you found. Don't guess.

3. **Add this block to `~/.zshrc`** (inside the markers), with the identifier you found:
   ```zsh
   # >>> tmux-terminal >>>
   if [[ -z "$TMUX" && -o interactive && "$__CFBundleIdentifier" == "<BUNDLE_ID>" ]]; then
     exec tmux new -A -s main
   fi
   # <<< tmux-terminal <<<
   ```
   If you matched on `TERM_PROGRAM` instead, compare `"$TERM_PROGRAM" == "<VALUE>"`. Put the block near the **end** of `.zshrc`, so PATH and Homebrew are set first. `exec` means leaving tmux closes the tab cleanly.

4. **Write `~/.tmux.conf`.** Merge this block inside the markers and keep any lines the user already has:
   ```
   # >>> tmux-terminal >>>
   set -g mouse on
   set -g history-limit 100000
   set -g default-terminal "tmux-256color"
   set -ag terminal-overrides ",xterm-256color:RGB"
   set -g base-index 1
   setw -g pane-base-index 1
   set -g renumber-windows on
   set -g escape-time 10
   set -g focus-events on
   set -g set-clipboard on
   set -g status-right "#S  %-I:%M %p"
   # <<< tmux-terminal <<<
   ```

5. **Verify.**
   - `zsh -n ~/.zshrc` must pass (syntax check).
   - `tmux -f ~/.tmux.conf start-server \; show -g mouse` must report `mouse on`.
   - If a tmux server is already running, apply the config live with `tmux source-file ~/.tmux.conf`.
   - Run `tmux ls` before and after. The same sessions must still be listed.

6. **Report back** in under 10 lines: the tmux version, the identifier you matched on, the backup file paths, the verification results, and the session list. Then give the one thing the user does next: **quit and reopen the terminal app, then run `echo $TMUX`**. Any output means it worked.

## Rollback
Delete the lines between the `tmux-terminal` markers in both files, or restore the `.bak-*` copies.
