Tmux Integration

AgileFlow wraps Claude Code in tmux sessions, giving you multi-window terminal management, smart conversation resume, freeze recovery, and a themed status bar - all with a single af command.

Getting Started

After installing AgileFlow, use the af command instead of claude:

Copyaf              # Start Claude in tmux (or reattach to existing session)
af --new        # Force a new session
af --no-tmux    # Run Claude without tmux
af --kill       # Kill all sessions for this directory
af --help       # Show keybinding reference

To install af globally:

Copysudo ln -s $(pwd)/.agileflow/scripts/af /usr/local/bin/af

Session Management

Automatic Session Handling

When you run af, it automatically:

1. Reattaches to detached sessions - If you previously detached with Alt+Q, af brings you right back
2. Joins existing sessions - If a session is active in another terminal, it attaches as a second client
3. Creates new sessions - Only when no existing session is found

Sessions are named by directory: claude-myproject, claude-myproject-2, etc.

Smart Resume

Each tmux pane tracks its Claude conversation UUID. When you re-run Claude in the same pane, it automatically resumes the previous conversation. New windows start fresh conversations.

Session Lifecycle

af                  → Reattach to detached session (or create new)
af --new            → Force new session (skip reattach)
Alt+s (in tmux)     → New Claude window in current session
Alt+q               → Detach (session stays alive in background)
af                  → Reattach to the detached session
af --kill           → Kill all sessions for current directory

Multiple Sessions

Multiple terminals can run af from the same directory:

• First af creates claude-myproject
• Running af --new creates claude-myproject-2
• When multiple detached sessions exist, af shows a picker

Status Bar

The tmux session has a two-line status bar with a Tokyo Night-inspired dark theme:

Top line: Session name, live git branch, and keybinding hints

Bottom line: Window tabs with the active window highlighted in AgileFlow's brand orange

The status bar refreshes every 30 seconds to show the current git branch.

Keybindings

All keybindings use Alt as the modifier key (Option on Mac). Press Alt+h inside tmux to see the full reference as a popup.

Sessions

Windows

Panes

Utility

Freeze Recovery

If Claude freezes or hangs:

Auto-Cleanup

AgileFlow automatically cleans up:

• Dead sessions - Sessions where all panes have exited are removed
• Duplicate sessions - Numbered duplicates are consolidated
• Socket directory - Recreated automatically after macOS reboot clears /tmp

Window Naming

New Claude sessions get sequential names:

• First window: main
• Alt+s windows: claude-2, claude-3, etc.

Windows are automatically renumbered when you close one (no gaps).

Configuration

Disable Tmux

Add to docs/00-meta/agileflow-metadata.json:

Copy{
  "features": {
    "tmuxAutoSpawn": {
      "enabled": false
    }
  }
}

Default Claude Flags

Configure startup flags (e.g., --dangerously-skip-permissions) via /agileflow:configure or in metadata:

Copy{
  "sessions": {
    "defaultStartupMode": "dangerous"
  }
}

Refresh Config

If you update the tmux configuration, apply it to all running sessions:

Copyaf --refresh

Mac Users

On macOS, Alt is the Option key. If keybindings don't work, check your terminal settings:

• iTerm2: Preferences > Profiles > Keys > Left Option key > set to "Esc+"
• Terminal.app: Preferences > Profiles > Keyboard > check "Use Option as Meta key"
• Alacritty / Kitty / WezTerm: Usually works out of the box

Prerequisites

Tmux must be installed:

Copy# macOS
brew install tmux
 
# Ubuntu/Debian
sudo apt install tmux

If tmux isn't available, af falls back to running Claude directly.

Related

• Parallel Sessions - Working in multiple isolated git worktrees
• IDE Integrations - Setting up AgileFlow with your editor