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.

Mouse Interactions

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.

Multi-session view

By default both ait monitor and ait minimonitor aggregate every active code agent across every aitasks tmux session on this tmux server into a single unified list. Sessions are auto-discovered via:

1. The AITASKS_PROJECT_<session> tmux global environment variable (set by ait ide on startup).
2. Pane-cwd walk-up: any pane whose current working directory has an ancestor containing aitasks/metadata/project_config.yaml.

Press M inside either TUI to toggle the multi-session view ON/OFF for that TUI instance. The toggle is in-memory only and applies to the current TUI process; it is not persisted to configuration and is not shared with the other TUI (toggling M in the main monitor does not affect a running minimonitor, and vice versa).

How each TUI renders the unified list:

• ait monitor — groups agents belonging to the same session under a thin ── <session_name> ── divider row, and prefixes each agent row with a short magenta [project] tag derived from the project-root basename. Title bar example: tmux Monitor — 2 sessions · 5 panes · multi (attached: aitasks). Single-session title: tmux Monitor — session: aitasks (5 panes).
• ait minimonitor — groups agents belonging to the same session under a ── <session_name> ── divider row; rows themselves stay in default color with no inline tag prefix (the narrow sidebar layout favors vertical scanning of window names). Title bar example: multi: 2s · 5a 1 idle. Single-session title: aitasks 5 agents 1 idle.

Cross-session focus from the main monitor: pressing Enter on a pane that belongs to another session teleports the attached tmux client to that pane via switch-client + select-window + select-pane.

Handoff between the two TUIs: pressing m (lowercase) inside a minimonitor switches tmux focus to the main monitor window but does not alter the main monitor’s multi-session flag. Each TUI’s M toggle is independent — if you want both TUIs in the same mode, toggle each one.

If no second aitasks session exists on the tmux server, both TUIs’ multi-session view is visually identical to the single-session view (one project, one session’s worth of agents).

Preview Size Presets

Pressing z cycles through six preview size presets:

The XL_N presets are terminal-aware: they compute the section height from the current terminal height so the pane-list always has room for N agent cards (2 lines each). Resizing the terminal while in an XL_N preset re-applies the sizing. 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: 200
    agent_window_prefixes:
      - agent-
    # Optional — additional window names to classify as TUIs. The framework
    # TUIs (board, codebrowser, settings, brainstorm, monitor, minimonitor,
    # stats, syncer) are always classified regardless of this setting.
    tui_window_names:
      - my_custom_tui
  # Optional — auto-launch the syncer TUI alongside monitor when `ait ide`
  # starts the session. Default: false.
  syncer:
    autostart: true

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

Next: Minimonitor — the narrow sidebar variant of monitor.