How-To Guides

How to Start the Monitor

Recommended — via ait ide:

ait ide

This is the one-command path to the ait tmux IDE. ait ide resolves the tmux session name from tmux.default_session in project_config.yaml (defaulting to aitasks), creates or attaches to that session, and opens a monitor window inside it. Because it always passes an explicit session name, the session-rename dialog never fires.

Standalone — from inside an existing tmux session:

ait monitor

Run this from within a tmux session you already have open. Monitor attaches to the current session.

Note: If you launched tmux without specifying a session name (or with a name that does not match tmux.default_session), monitor offers to rename the session on startup. See How to handle a session-name mismatch.

How to Read the Pane List

The pane list zone renders two sections:

• CODE AGENTS (N) — windows whose names start with a configured agent prefix (default agent-). These are running code agents started via ait codeagent. When the window name contains a task ID (e.g., agent-t42-<...>), the card shows the task number.
• OTHER (N) — shells, logs, and any other window that is not an agent.

Each section appears only when it has something in it. Windows classified as TUIs — those in the configured TUI list (board, codebrowser, settings, monitor, minimonitor, brainstorm) or starting with brainstorm- — are not listed in either section, and neither are companion panes (a minimonitor sidebar, or a shadow agent). See Pane Classification in the reference for the classification rules themselves.

Each card shows:

• Window name and category badge

• A status badge and a matching colored dot, showing which of four states the pane is in:

  Badge	Color	Means
  Active	green	The pane is producing output
  PROMPT <n>s	magenta	The agent is waiting for your input
  DONE <n>s	blue	The pane’s task is finished
  IDLE <n>s	yellow	Quiet for longer than tmux.monitor.idle_threshold_seconds (default 5 seconds)

  A pane that is waiting on you always reads PROMPT, even when its task is already done — that prompt is the thing you can act on now. DONE is a property of the task, not the terminal: the task’s status reads Done, or its file has moved into aitasks/archived/. So an agent still printing output after its task was archived reads DONE, while a stuck agent whose task is still open reads IDLE. Only agent panes that carry a task ID can ever read DONE — exploration and raw panes have no task to finish.

  The badge follows the task, so it settles on its own: a task archived while monitor is open flips to DONE on a later refresh, and a slow or interrupted archive still resolves without restarting the TUI.

• For agent panes carrying a task ID in the window name, the associated task number

• A shadow marker ◆ when a shadow agent is bound to that pane, colored by the shadow’s own state. It gains a ! (◆!) when the shadow has raised concerns you have not picked yet — see How to Pick Shadow Concerns. Panes with no shadow show nothing at all here.

• A prioritized mark at the far left: ★ when you have marked the agent, dim ☆ when you have not — see How to Mark an Agent as Prioritized.

• For agent panes carrying a task ID, the end of the status row carries the task’s gate summary and then its workflow phase — gates: 1/4 pass phase: IMPLEMENT. A trailing ⏸ on the phase means the agent is waiting on your input, and an unknown (…) phase is a “cannot tell” state that names its own cause rather than a missing one. Either part is omitted when there is nothing to say. The phase is advisory — it never gates anything. The minimonitor how-to lists the phase values in full.

The CODE AGENTS (N) header above the agent cards repeats the same four states as a color legend, so you can read a card’s dot without memorizing the colors:

CODE AGENTS (5)  ⟳ AUTO  (● active ● prompt ● idle ● done)

Classification rules are config-driven — you can change the agent prefixes and the TUI list by editing aitasks/metadata/project_config.yaml directly or via ait settings → Tmux tab. See the Reference for details.

Mouse Support

Monitor supports full mouse interaction in addition to the keyboard shortcuts:

• Click a pane card — focus that card in the pane list (alternative to Up / Down).
• Click inside the preview pane — move focus into the preview zone (alternative to Tab); subsequent keystrokes are forwarded to the underlying tmux pane.
• Scroll wheel — scroll the pane list or preview content in the focused zone.
• Click dialog buttons — confirmation buttons in the kill (k), next-sibling (n), and task-info (i) dialogs are clickable.

All keyboard actions documented below remain available.

How to Navigate Between Zones

Monitor uses a zone model with two zones: the pane list and the preview.

1. Press Tab to move focus from the pane list to the preview, or vice versa. Shift+Tab cycles in the opposite direction.
2. In the pane list zone, Up and Down move focus between cards.
3. Whenever you focus a card, the preview updates to show that pane’s live content.

The active zone is reflected in the widget borders and the footer.

How to Interact with a Pane From the Preview

The preview zone is not a passive viewer — when it has focus, every keystroke is forwarded to the focused tmux pane in real time. This lets you interact with whatever is running in the pane (a code agent, a shell, a TUI) without switching tmux windows.

1. Focus the pane you want to interact with in the pane list (Up/Down)
2. Press Tab to move focus into the preview zone
3. Type normally — characters, Ctrl-combinations, arrow keys, and Escape are all forwarded
4. Press Tab again to return focus to the pane list

Note: Pressing Enter while the pane list zone is focused also sends an Enter keystroke to the focused pane. This is a shortcut for unblocking agents that are waiting for input, without having to move into the preview zone first.

How to Send Enter to a Blocked Agent

A common workflow pattern: an agent has asked a clarifying question and is waiting for you to press Enter to continue (for example, after an /aitask-pick prompt).

1. Focus the agent’s card in the pane list zone
2. Press Enter

This sends a single Enter keystroke to that pane via tmux send-keys without moving focus into the preview zone. A delayed refresh then updates the preview so you can see the agent’s response.

How to Switch tmux to the Focused Pane

To move your tmux focus to the pane you are currently previewing (so that your next keystrokes go there natively):

1. Focus the pane’s card in the pane list
2. Press s

Monitor calls tmux switch-client/select-window to bring that pane to the front. A notification confirms the switch.

How to Jump to Another TUI

Press j from any zone to open the TUI switcher overlay. The overlay lists the TUIs integrated with the tmux workflow:

• board — ait board
• monitor — ait monitor (the current TUI)
• minimonitor — the minimal monitor variant
• codebrowser — ait codebrowser
• settings — ait settings
• brainstorm — ait brainstorm

Select a target and the switcher either focuses the existing tmux window running that TUI or creates a new window and launches it. This is the fastest way to move between the monitor dashboard and any other ait TUI without leaving tmux.

How to Show Task Info for an Agent Pane

For agent panes whose window name carries a task ID (e.g., agent-t42-claudecode), you can open the full task detail dialog directly from the monitor:

1. Focus the agent’s card in the pane list
2. Press i

Monitor refreshes the task cache and opens the same task detail dialog used by ait board, showing the task’s metadata, lock status, and content.

How to Kill a Pane

To terminate a tmux pane from monitor:

1. Focus the pane’s card
2. Press k
3. A confirmation dialog appears showing the window name and, if it is an agent pane, the associated task information
4. Confirm the kill

Monitor calls tmux kill-pane and refreshes the pane list.

How to Pick the Next Sibling Task

When an agent pane finishes a child task, you can have monitor suggest and launch the next ready sibling without leaving the window:

1. Focus the agent’s card (it must carry a task ID in the window name)
2. Press n
3. A dialog appears showing the current task and the suggested next sibling (or child) — confirm to launch it

Monitor resolves the next ready sibling via the task cache and starts a new agent window for the chosen target using the standard pick workflow.

How to Launch a Shadow Agent

Press e with an agent selected in the pane list to launch a shadow agent beside it — an advisory companion that reads that agent’s terminal output and helps you make sense of it. By default the shadow opens as a new pane in the same tmux window as the selected agent, so it sits right beside the work it is watching.

The shadow is read-only and advisory: it can explain what the agent is doing, help you answer a prompt the agent is stuck on, critically interrogate a plan before you approve it, or review the code the agent actually wrote — but it never types into the selected agent’s pane. You stay the driver.

Launching from monitor keeps your focus in monitor — the new pane is created without switching your tmux client to it, so the shadow preview column keeps showing the shadow rather than pulling you away to another window.

Press E instead to choose the code agent and model before the shadow starts; cancelling the dialog launches nothing.

The shadow pane is a companion: it never appears in the agent list, and it closes automatically when the agent it shadows exits. Only one shadow runs per selected agent — if one is already running, a second e is refused with a notification. e and E apply to agent panes only; on any other kind of pane monitor says so and does nothing.

For what the shadow can do and how to drive it once it is running, see the Shadow Agent workflow guide.

How to Pick Shadow Concerns

A shadow agent that reviews a plan emits a structured concern block alongside its prose. Monitor reads that block so you can forward a subset of the concerns to the agent without retyping them.

1. Make sure a shadow is running for the agent (press e if not)
2. Select the agent whose shadow you want to read
3. Press c

Monitor reads the bound shadow pane, parses the block, and opens a checklist modal. Each concern is tagged with a priority (high / medium / low) and the plan region it refers to. Tick the ones you want, confirm, and monitor copies them with a short preamble to your clipboard. Nothing is written to the clipboard until you confirm, and monitor never types into the agent itself: you stay the driver.

The list is split into Needs addressing and Informational. Informational findings are dimmed so what needs attention reads first, and you tick them individually like any other row. Neither header appears when there are no informational findings. If some marker lines in the block could not be parsed, the modal says how many, and if none of them parsed you get a message saying so rather than a misleading “no concerns”.

Rejecting a concern. Each row carries one of three mutually exclusive dispositions: unmarked (☐), marked to forward with Space (☑), or marked rejected with r (✗, and the row dims). Rejecting says stop raising this for this task, so the shadow drops it from later review rounds — see Reject a concern so it does not come back for what the shadow does with it.

Press R to review what is already rejected for this task: Space marks an entry to bring back, Enter hands those marks to the picker, and q or Esc closes the view. R does not always open a list — if nothing is rejected for this task yet it says so, and if the pane has no task id it warns that the rejection store is unavailable, which tells you before you confirm that rejections made here cannot be kept.

Nothing is written until you confirm the picker. Rejections and un-rejections are staged while you work; confirming with Enter or OK is what saves them, and cancelling with Esc discards both. When the pane has no resolvable task id, monitor warns that the rejections were not persisted rather than dropping them quietly. A busy or unusable store is reported too, so a rejection never fails silently.

These keys belong to the picker, not to monitor. Inside the concern modal, r rejects and R opens the rejected list. Monitor’s own r (refresh) and R (restart task) are not reachable while the modal is open, so there is no conflict — but the same key does different things depending on whether the picker has focus.

Seeing what was lost. When that warning appears, press u to open a read-only view of the exact lines the parser could not use, together with the raw block they came from. That is what lets you tell a marker the shadow wrapped across too many rows from a genuine mistake in what it wrote — and report the latter. When no line parsed there is no checklist to show the warning beside, so u’s view opens straight away instead. Press q or Esc to close it and return to the checklist with your ticks intact.

The picker sizes itself from its own measured width, so a monitor running in a narrow terminal gets the compact treatment too: at 30 columns and below it drops its OK/Cancel buttons and switches to a compact key hint (confirm with Enter, cancel with Esc). 24 columns is the narrowest width it is designed for — below that the concern block’s own markers wrap in the shadow pane and there is nothing left to parse.

If the selected agent has no shadow bound, monitor tells you so — and points you at e to launch one. If the shadow has not emitted a block yet, it says that instead.

Badge and auto-offer: every agent whose shadow has an un-picked block is marked with ◆! on its card, so nothing is missed across many agents at once. A toast — Shadow raised 2 concern(s) — press 'c' to pick — fires only for the currently selected agent, so there is at most one popup no matter how many agents are running. The count is of concerns needing attention; any informational ones are noted separately in the same toast, and (⚠ STALE — agent moved on) is appended when the agent has produced output since the shadow last analyzed it. A block whose markers cannot be parsed still raises the badge but deliberately does not toast — pressing c then tells you exactly what went wrong.

Where shadows come from: launch one right here with e (see How to Launch a Shadow Agent), or from minimonitor with the same key.

How to Mark an Agent as Prioritized

With the pane list focused, press Space to toggle a prioritized mark on the focused agent. Marked agents show a bright ★; unmarked agents show a dim ☆, so the column is always present and rows never shift when you toggle one.

This is the place to mark any agent. ait minimonitor binds the same key, but — being a companion pane tied to one agent — it always marks the agent it follows, whatever its list highlights.

Marks are stored per user, outside every repository, in ~/.config/aitasks/agent_marks.json (override the path with AITASKS_AGENT_MARKS_FILE). A mark you set here is therefore visible from every other project’s monitor and minimonitor, usually within one refresh cycle, and survives restarting the TUI. Each mark is keyed by the pair (project root, tmux window name), so two projects running identically-named agent windows never share a mark.

Marks are purely visual — they do not reorder the list or change the session-bar counters.

Automatic cleanup keeps the list honest without any manual unmarking:

• Age — a mark older than about 2 days is dropped. Override the window with AITASKS_AGENT_MARK_TTL_DAYS; a missing or invalid value falls back to the default, so a typo cannot wipe your marks.
• Departed agents — when a project’s tmux session is visible and the marked window is gone, its mark is dropped. The check is deliberately conservative: a project whose session cannot be seen at all — not running, or on a different tmux server — never loses its marks.

Outside the pane list zone, Space behaves as it always has: it is forwarded to the focused tmux pane along with every other unhandled key.

How to Cycle the Preview Size

Press z to cycle the preview zone through six size presets — S, M, L, XL_9, XL_6, XL_3 — for quickly adjusting how much pane output vs. agent-list you see at once. The S/M/L presets set a fixed preview height; the XL_N presets size the pane-list to fit N agents and give the rest of the screen to the preview. A notification shows the new size label. The default is M.

How to Refresh the Pane List

Press r (or F5) to force an immediate refresh of the pane list and preview content. Monitor also refreshes automatically every tmux.monitor.refresh_seconds seconds (default 3), so manual refresh is only needed when you want an immediate update.

How to Toggle Auto-Switch Mode

Press a to toggle auto-switch mode. When auto-switch is on, monitor automatically focuses agent panes that need attention, so you don’t have to scan the pane list manually. Press a again to turn it off. The session bar shows [AUTO] and the agents header shows ⟳ AUTO while it is on.

Auto-switch prefers a pane that is waiting for your input over one that is merely idle — a prompt is blocked on you right now, while an idle pane may just be thinking. Agents whose task is already done are skipped entirely: a finished agent stays idle forever and would otherwise capture focus permanently, hiding a live agent that actually needs you.

How to Quit

Press q to quit monitor. The tmux window running monitor closes; the rest of your tmux session is unaffected.

How to Handle a Session-Name Mismatch

Monitor expects the current tmux session name to match tmux.default_session from project_config.yaml. If the names do not match and the configured session does not already exist, monitor opens the Session Rename Dialog on startup, offering to rename the current tmux session to the configured name.

Recommended fix: launch monitor via ait ide, which always passes an explicit session name and bypasses the dialog entirely.

Manual workaround: rename the session yourself before launching monitor:

tmux rename-session -t "$OLD" "$NEW"
ait monitor

See the Session-name fallback dialog in the reference for the full decision logic.

Next: Reference — full keybinding list, configuration keys, and internals.