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 three-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 header label above each preview column, which shows a green LIVE badge for the zone that currently receives keystrokes.

The SHADOW zone is skipped by Tab unless the selected agent has a bound shadow companion and the side-by-side split fits: the shadow column is sized to the real shadow pane’s width so its content renders unwrapped, and the split is suppressed when it would leave the agent column narrower than 40 columns. If the shadow disappears while the zone is focused, the column holds for a short grace window (2 refreshes) showing a (shadow unavailable) placeholder before falling back to PREVIEW; keystrokes are dropped — never redirected to the agent — while it is absent.

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.

Agent Card Status Row

For a linked agent pane, the status row ends with two task-derived fields, in this order:

Phase values are PLAN, IMPLEMENT, POSTIMPL, or an unknown (…) variant that names why the phase could not be determined (gate recording off, ledger-only, or waiting). A trailing ⏸ means the agent is waiting for input; it can appear on any phase, including an unknown one.

Both fields are advisory — nothing in the monitor is gated on them. Monitor renders the phase in its labelled form; minimonitor merges the same two fields onto one label-free line to fit its narrower pane.

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) 1 awaiting 2 done 1 idle. Single-session title: tmux Monitor — session: aitasks (5 panes) 1 idle.
• 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 awaiting 2d 1 idle. Single-session title: aitasks 5 agents 2d 1 idle.

Status counters. Both title bars carry up to three counters — awaiting, done (compressed to Nd in minimonitor’s narrow bar), and idle. Each is omitted entirely when it is zero. The three partition the agents on the same precedence the card badges use — waiting for input, then done, then idle — so every agent is counted exactly once. An agent whose task is finished but which is sitting on a prompt counts as awaiting, matching its PROMPT badge.

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.