tmux Configuration
==================

tmux configuration for persistent terminal sessions with popup windows and session management

Date: February 7, 2026


tmux is a terminal multiplexer that lets you switch easily between several
programs in one terminal, detach them (they keep running in the background) and
reattach them to a different terminal.

## Features

- **Popup windows** - Quick access to sessions and tools without leaving current
  context
- **Session management** - Easy switching between projects
- **Vi mode** - Familiar keybindings for copy mode
- **Minimal status bar** - Hidden by default, toggle when needed

## Setup

### Installation

Install via mise:

```bash
mise install tmux
```

Or your package manager:

```bash
# Ubuntu/Debian
sudo apt install tmux

# Arch Linux
sudo pacman -S tmux
```

### Configuration

The config file is `~/.tmux.conf`. Main settings:

```bash
# Vi mode for copy/paste
setw -g mode-keys vi

# Don't detach on destroy
set-option -g detach-on-destroy off

# Focus events for nvim integration
set-option -g focus-events on

# Hidden status bar by default
set-option -g status off
```

## Key Bindings

### Prefix

The prefix key is `Ctrl+Space` (custom):

```bash
bind Space send-prefix
```

### Session Management

| Key | Action |
|-----|--------|
| `Alt+Space` | Popup: attach to workspace session |
| `Alt+T` | Popup: attach to workspace in current directory |
| `Alt+Escape` | Popup: create new workspace |
| `Alt+Backspace` | Popup: add repo to workspace |
| `Ctrl+J` | Popup: switch to any session with fzf |
| `Alt+G` | Popup: open scratch session |
| `Alt+Shift+G` | Popup: open scratch session (large) |
| `Ctrl+K` | Popup: kill sessions |
| `J` | tmux session tree browser |

### Copy Mode

| Key | Action |
|-----|--------|
| `Alt+[` | Enter copy mode |
| `Alt+V` | Enter copy mode |
| `Alt+Enter` | Enter copy mode |
| `Enter` | Enter copy mode |

Copy uses `wl-copy` on Wayland or `xclip` on X11.

### Status Bar

| Key | Action |
|-----|--------|
| `Prefix+s` | Toggle status bar |
| `Prefix+Ctrl+S` | Toggle status bar |

### Git Integration

| Key | Action |
|-----|--------|
| `Alt+F` | Popup: git commit --verbose |
| `Alt+Shift+F` | Popup: gitui |

### Workspaces

| Key | Action |
|-----|--------|
| `Ctrl+W` | Popup: attach to ~/work |
| `Alt+W` | Popup: attach to ~/work |
| `Ctrl+G` | Popup: attach to ~/git |
| `Ctrl+P` | Popup: attach to ~/project |
| `Ctrl+T` | New session: todo list in nvim |

## Popup Windows

Popups are a key feature - they let you access tools without leaving your
current context:

```bash
# Example: switch sessions without leaving current window
bind C-j display-popup -E "\
    tmux list-sessions -F '#{?session_attached,,#{session_name}}' |\
    sed '/^$/d' |\
    fzf --reverse --header jump-to-session --preview 'tmux capture-pane -pt {}' \\
        --bind 'enter:execute(tmux switch-client -t {})+accept'"
```

## Workflows

### Project Hopping

1. `Alt+Space` to see all workspace sessions
2. `Ctrl+J` to fuzzy-find any session
3. `Alt+G` for a quick scratch pad

### Git Workflow

1. `Alt+F` to write a commit message in a popup
2. `Alt+Shift+F` for full gitui when needed

### Todo Management

1. `Ctrl+T` opens a dedicated todo session with three files:
   - `backlog.md` - Things to do eventually
   - `doing.md` - Currently working on
   - `done.md` - Completed tasks

## Clipboard Integration

Copy mode automatically integrates with system clipboard:

```bash
bind -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel \\
    "bash -c 'command -v wl-copy >/dev/null && wl-copy || \\
    xclip -i -f -selection primary | xclip -i -selection clipboard'"
```

## See Also

<div class="embed-card">
  <a href="/zellij/" class="embed-card-link">
    <div class="embed-card-content">
      <div class="embed-card-title">Zellij</div>
      <div class="embed-card-description">Zellij - a terminal workspace with batteries included</div>
      <div class="embed-card-meta">Feb 7, 2026</div>
    </div>
  </a>
</div>


<div class="embed-card">
  <a href="/zsh/" class="embed-card-link">
    <div class="embed-card-content">
      <div class="embed-card-title">zsh Configuration</div>
      <div class="embed-card-description">zsh shell configuration - my primary shell with autosuggestions, syntax highlighting, and custom functions</div>
      <div class="embed-card-meta">Feb 7, 2026</div>
    </div>
  </a>
</div>


<div class="embed-card">
  <a href="/workspace/" class="embed-card-link">
    <div class="embed-card-content">
      <div class="embed-card-title">Workspace Script</div>
      <div class="embed-card-description">Workspace script - session management automation for tmux</div>
      <div class="embed-card-meta">Feb 7, 2026</div>
    </div>
  </a>
</div>


<div class="embed-card embed-card-external">
  <a href="https://github.com/tmux/tmux/wiki" class="embed-card-link" target="_blank" rel="noopener noreferrer">
    <div class="embed-card-image">
      <img src="https://opengraph.githubassets.com/4af025f64a340cae98c16826e770e0bf1f432116ea30a380012ada618cfa678b/tmux/tmux" alt="" loading="lazy">
    </div>
    <div class="embed-card-content">
      <div class="embed-card-title">Home</div>
      <div class="embed-card-description">tmux source code. Contribute to tmux/tmux development by creating an account on GitHub.</div>
      <div class="embed-card-meta">GitHub · github.com</div>
    </div>
  </a>
</div>