Feature Reference

Keyboard Shortcuts

Zone Navigation

Pane Interaction

Monitor Controls

Note: In the preview zone, every keystroke that is not handled by a global binding is forwarded to the tmux pane via tmux send-keys. Special keys (Enter, Escape, Backspace, arrows, Space, Delete, Home, End, PageUp/Down) and Ctrl-combinations are translated; regular characters are sent literally.

Zone Model

Monitor uses a two-zone model. Focus lives in one of:

Tab and Shift+Tab cycle between these zones. The active zone is reflected in the widget borders and in the content-header label above the preview.

Pane Classification

discover_panes() in tmux_monitor.py categorizes every window in the monitored tmux session:

Agent panes whose window name contains a task ID (e.g., agent-t42-claudecode) are linked to the corresponding task file — that is what powers the i (Task Info) and n (Next Sibling) shortcuts.

Preview Size Presets

Pressing z cycles through three preview size presets:

A notification shows the new size label when you cycle.

Configuration

Monitor reads its configuration from aitasks/metadata/project_config.yaml. The relevant keys live under tmux and tmux.monitor:

tmux:
  default_session: aitasks
  default_split: horizontal
  prefer_tmux: true
  git_tui: lazygit
  monitor:
    refresh_seconds: 3
    idle_threshold_seconds: 5
    capture_lines: 30
    agent_window_prefixes:
      - agent-
    tui_window_names:
      - board
      - codebrowser
      - settings
      - brainstorm
      - monitor
      - minimonitor

All of these can be edited interactively via ait settings → Tmux tab, which writes the same keys in project_config.yaml.

Command-line Options

ait monitor is a thin wrapper around monitor_app.py. The underlying script accepts:

ait ide always passes --session with the configured default, which is why it never triggers the Session Rename Dialog.

Session-Name Fallback Dialog

When monitor starts, it resolves which tmux session to watch using this decision logic:

1. If --session NAME was passed on the command line, use that name.
2. Otherwise, detect the current tmux session name from $TMUX.
3. Compare the detected name against tmux.default_session from project_config.yaml.
4. If the names match, proceed normally.
5. If they differ and the configured session does not already exist, open the SessionRenameDialog offering to rename the current session to the configured name.
6. If they differ and the configured session exists, proceed watching the current session without prompting.

When the dialog fires: inside a tmux session whose name does not match the configured default (typical when you ran tmux without -s NAME).

What the dialog does: offers a one-click rename of the current session to the configured name; you can also dismiss the dialog to keep the current name.

How to avoid it:

• Launch monitor via ait ide, which always passes an explicit session name.
• Manually rename the session before launching monitor: tmux rename-session -t "$OLD" "$NEW".

Environment Variables

Related Commands and TUIs