How-To Guides

How Minimonitor Is Auto-Spawned

Minimonitor is meant to be auto-spawned — you almost never start it yourself. Every ait TUI that launches a new code agent window also creates a minimonitor split next to it:

• ait board — when you pick a task and launch its agent (action menu or agent command screen).
• ait codebrowser — when you launch an agent from a code file or the history screen.
• ait monitor — when you press n on an agent card to pick its next ready sibling task, which creates a new agent window.
• The TUI switcher’s explore launch — when it creates an agent window for an explore target.

In every case the flow is the same: the launching TUI creates a new tmux window named agent-..., then the auto-spawn helper creates a horizontal right-split inside that window and runs ait minimonitor in it. The helper skips the split if the window name does not start with the configured agent prefix (default agent-) or if a monitor/minimonitor is already running in the window.

Other TUI windows (board, trails, codebrowser, settings, stats, syncer, brainstorm and the rest) get no minimonitor automatically. You can add one on request from the TUI switcher, which has no window-name requirement — see How to Add a Minimonitor Beside Any TUI.

Auto-despawn: minimonitor closes itself automatically when the agent pane it sits next to exits. On every refresh cycle it checks the panes in its own tmux window; the first refresh after the agent pane has gone (so there is no pane left other than minimonitor itself) triggers an exit() and the minimonitor pane closes. A 5-second grace period after startup prevents premature exit on cold launch. You never need to ait minimonitor after an agent finishes — a new one will spawn with the next agent you launch.

How to Start Minimonitor Manually

Manual launch is an escape hatch for edge cases (an agent pane you started by hand, a killed sidebar you want to bring back). From inside a tmux session, run:

ait minimonitor

This starts minimonitor in the current tmux pane.

Single-instance guard: ait minimonitor checks the current tmux window for any existing monitor or minimonitor process. If one is already running in the same window, the new invocation prints a short message and exits. The guard is per-window, so you can still have minimonitor split alongside each of several agent windows in the same session.

How to Add a Minimonitor Beside Any TUI

From any ait TUI except monitor and minimonitor, press j to open the TUI switcher, then Shift+M (M). A minimonitor split opens on the right of the TUI you opened the switcher from, and focus returns to that TUI. Its agent list then gets you back to any code agent without reopening the switcher.

• The switcher shows the key as (Shift+M) minimonitor on its second hint line, and only when that window has no monitor or minimonitor yet. Plain m still opens the full monitor.
• The split always lands in the window you opened the switcher from, even after you browse another session with Left/Right.
• tmux.minimonitor.auto_spawn: false does not block it: that setting covers automatic splits only. The window limit still applies — a window that already holds three real panes gets a warning instead of a split. Helper panes, such as a shadow agent or a scratchpad, do not count toward the three.
• Quitting the TUI closes the minimonitor too, unless another pane you added still uses the window.

How to Read the Agent List

Minimonitor shows a single scrollable list, agent panes first (windows whose names match the configured agent prefix — default agent-). By default the list aggregates agents from every aitasks tmux session on the current tmux server; ── <session_name> ── divider rows separate agents that belong to different sessions.

Within each session, agents are ordered by their tmux window name — not by the order the windows sit in the session, which is just the order you happened to launch them in. The comparison is natural rather than alphabetical, so runs of digits compare as numbers: agent-pick-2 comes before agent-pick-9, agent-pick-10 and agent-pick-20. A child task’s window follows its parent’s (agent-pick-100, then agent-pick-100_1, then agent-pick-101), and two windows that share a name fall back to window index and then pane index, so the order is always stable across refreshes. The session is what groups first: an agent in a later session never rises above an earlier session’s agents, however its name sorts. ait monitor uses the same rule — the two TUIs share one ordering key and cannot disagree.

Any pane that is not an agent — a shell, a log, a window you renamed off the agent- prefix — follows below them under a bold ── other (n) ── section header. Only that section is headed; the agent list needs none, because the bar at the top already carries the agent count. Session dividers still apply within each section. Windows classified as TUIs (board, codebrowser, settings, brainstorm, and the monitors themselves) are not listed, and neither are companion panes — a shadow agent, or another minimonitor.

Each agent card in the list shows:

• An agent mark: ★ when the agent is prioritized, P when it is parked, dim ☆ when neither. In the list this is display only — it shows marks set from ait monitor or from another project, and Space here marks the followed agent instead (see How to Mark an Agent as Prioritized). A parked card shows only the P, the name and a dim parked; a frozen card shows the mark plus a cyan F, the name and a dim frozen. Press P to hide parked and frozen agents from this list
• A status dot: green when the agent has produced recent output, magenta when it is waiting for your input, blue when its task is finished, yellow when it is idle
• The agent window name without the agent prefix — agent-pick-42 shows as pick-42, since every card in this list carries that prefix. A name too long for the row is shortened at its end with …. The pinned card for the agent you follow, and cards in the other section, show the full window name
• A matching label: PROMPT <t> when the agent is waiting for you, DONE <t> when its task is finished, or IDLE <t> when the pane has been quiet longer than tmux.monitor.idle_threshold_seconds (default 5 seconds). <t> is the time since the pane’s output last changed — not how long it has been in that state — in at most four characters: seconds up to 999s, then whole minutes up to 240m, then whole hours up to 999h, always rounded down. DONE reflects the pane’s task — its status reads Done, or it has been archived — so an agent still printing output after its task landed reads DONE, while an agent waiting on you reads PROMPT even when its task is done
• For agents whose window name carries a task ID, a second dimmed line showing the task’s title
• For those same agents, a third line carrying the task’s workflow phase and its gate summary together — ◕ IMPLEMENT ⏸ · 1/4 1p 1f. The phase leads with its own symbol and is drawn in its own colour, so it stands out from the dimmed gate counts beside it. Either half may be empty; the line is omitted only when both are

The phase is advisory: it is a hint about where the task sits in its workflow, and it never gates a key, a spawn, or anything else you can do here.

The symbol fills up as the task moves through its workflow; the dotted ◌ marks every “cannot tell” value.

A trailing ⏸ on any phase means the agent is waiting for your input. The unknown (…) values are a real “cannot tell” state, named so you can see why — they are not the same as having no phase. When no phase resolves at all and the task has no gate counts either, the line is simply absent.

At narrow pane widths the line sheds detail in a fixed order, so the counts are what survive: first the gate summary abbreviates (1/4 pass, 1 pending, 1 failed → 1/4 1p 1f), then the phase text is clipped while its symbol stays, then the phase is dropped entirely, symbol included.

A card in the other section is deliberately much plainer — a dim ○, the window name, and the pane’s current command (○ zsh nvim). It carries no mark, status dot, status label, task title or gate line, because none of those mean anything for a pane that is not an agent, and the ~40-column sidebar has no room to spare for them.

The header bar at the top of the pane shows either multi: 2s · 5a 1 awaiting 2d 1 idle when the multi-session view is active, or <session> 5 agents 2d 1 idle when the view is restricted to the attached session. The three counters — waiting for input, done (shown compactly as Nd), and idle — each disappear when zero, and every agent still being watched falls into exactly one of them. Two further terms sit beside them for agents that are not being watched: Np parked and Nf frozen. Both are disjoint from the three above and from each other (an agent that is both frozen and marked parked is counted once, as frozen), and both are shown whether or not P is hiding those rows — they are the one place a hidden agent is still accounted for. See How to Toggle the Multi-Session View below.

Mouse Support

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

• Click an agent card — focus that card (alternative to Up / Down).
• Scroll wheel — scroll the agent list.
• Drag the scrollbar — drag the thumb to move through a list too long for the pane.
• Click dialog buttons — buttons in the task-info dialog and TUI switcher overlay are clickable.

Scrolling to the bottom pins the list there. Once you reach the end of the list — by wheel, or by dragging the scrollbar thumb to the end of its track — minimonitor keeps you at the bottom as the list refreshes, so agents appearing, disappearing, or growing an extra status row do not push the view away from the newest entries. Scrolling back up releases the pin and your position is held instead; reaching the bottom again re-engages it.

All keyboard actions documented below remain available.

How to Navigate the Agent List

• Up / Down — Move focus between agent cards within the list.
• Shift+Up / Shift+Down — Jump to the previous / next project’s agents — see How to Jump Between Projects.
• Shift+Left / Shift+Right — Narrow the list to one workflow phase or to parked / frozen agents — see How to Filter the List by Phase or State.
• The key-hint band at the bottom summarizes the navigation and action keys — see How to Collapse the Key Hints or Open the Full Key Help.

When minimonitor is shown as a side split next to an agent, it auto-selects the card for that agent whenever the minimonitor pane regains terminal focus — so the focused card always reflects the neighbor you are working with, unless you explicitly moved focus somewhere else.

How to Focus the Sibling Agent Pane

Minimonitor is designed to live beside an agent pane in the same tmux window. Pressing Tab moves tmux focus to that sibling pane (the first non-minimonitor pane in the same window), so your next keystrokes go directly to the agent. This is the fastest way to jump from glancing at the status sidebar to typing into the agent it sits next to.

If minimonitor is the only pane in its window (no sibling to target), Tab shows a notification and does nothing.

How to Focus Minimonitor from the Agent Pane (native tmux)

Tab only goes one way: minimonitor → agent pane. There is no built-in shortcut for the opposite direction. Because minimonitor lives as a second pane inside the agent’s tmux window, you move focus the other way (agent pane → minimonitor) with tmux’s own pane-switching keys — the same keys you would use to move between any two panes in one window:

• Ctrl-b o — cycle tmux focus to the next pane in the window.
• Ctrl-b + an arrow key — move focus directionally to the adjacent pane.

This also saves you from clicking the minimonitor pane to activate it. Ctrl-b is the default tmux prefix; if you remapped your prefix, substitute your own. Once you are comfortable with these native shortcuts you can use them for both directions instead of Tab if you prefer.

This intra-window pane switching is specific to the minimonitor split — the other ait TUIs each occupy their own full tmux window, which you reach with the TUI switcher (press j).

How to Send Enter to the Sibling Agent

When a code agent is waiting for you to press Enter (for example, it just asked a clarifying question), you can unblock it without moving tmux focus:

1. Make sure minimonitor has terminal focus
2. Press Enter

Minimonitor sends a single Enter keystroke to the sibling pane via tmux send-keys. Tmux focus stays on minimonitor, so you can keep watching the agent status while it processes the input.

How to Switch to the Selected Agent

To jump your tmux session focus to the selected card’s agent (which may be in a different window from the minimonitor you’re in):

1. Focus the agent’s card with Up/Down
2. Press s

Minimonitor asks tmux to switch focus to the agent’s window (preferring the companion pane when the card is next to its own minimonitor). A notification confirms the switch.

How to Show Task Info for an Agent

For agent panes whose window name carries a task ID (e.g., agent-t42-claudecode), minimonitor can open the same task detail dialog used by the other TUIs:

1. Focus the agent’s card with Up/Down
2. Press i

The task cache is refreshed and the task detail dialog appears with the task’s metadata and content. If the focused card has no task ID in its window name, a warning notification is shown instead.

The pane minimonitor follows — the one pinned at the top — is never selectable, so i cannot reach it. Press I (Shift+i) instead: it always opens the task detail dialog for the followed agent, whichever card happens to be highlighted. If this window has no agent to follow, a warning notification is shown instead.

The pinned card’s header names what it is following: ── this agent ── when that pane is classified as an agent, and ── this window ── when it is not. A window you renamed off the agent- prefix still gets a panel, headed ── this window ──, so the uncategorized state is visible rather than looking like a missing agent.

Note: the pinned card is a static identity line — it shows the window name and task title, but never a live status badge, so it does not turn DONE when the followed agent’s task lands. Use the scrollable list, or ait monitor, to see that. The header and name are fixed when the panel is first built, so renaming the window afterwards does not change them.

Two things on the pinned card do stay current. Its agent mark (★ / P / ☆) is not a status badge but a note you left yourself, and it can change without the agent changing at all — you marked it from another project, or it expired. Its workflow phase is kept current too: this panel is the followed agent, and the shadow companion you launch from it picks its review mode from that phase, so showing it only on the list rows — which exclude the followed agent by construction — would put it everywhere except the one place it is for. The panel carries the phase — with the same symbol and colour as the list rows — and deliberately not the gate summary that shares that line on the list rows. At narrow widths the phase text is clipped to fit its one line, keeping its symbol.

When the followed agent is frozen the pinned card says so directly: its mark gains a cyan F, and a second indented line reads a dim frozen followed by the timestamp the record was frozen at. The workflow phase is dropped rather than left showing its last value — there is no process to have a phase — so an empty phase line here means “frozen”, not “unknown”.

How to Pick a Task by Number

When an agent finishes it usually names the tasks it created, or the one to pick next, as bare numbers. Press p to act on one without leaving the window:

1. Press p and type the task number (1310, or 1310_2 for a child task — a leading t is accepted)
2. Press Enter; the task’s details open, with OK, Move to column and Cancel buttons and a kill followed agent checkbox
3. Choose OK, and the usual launch dialog appears so you can pick the coding agent, model, and where the new window goes

The checkbox is unchecked by default. Tick it to close down the agent this minimonitor follows once the new one has launched — the new agent always starts first, so the window teardown can never strand it. Leave it unticked to run both side by side.

Moving the task to a board column instead. Not every task you look up is one to start now. Move to column opens a picker listing the board’s columns, including “Unsorted / Inbox”, with the task’s current column marked, plus a ＋ New column… entry. Choosing an existing column moves the task to the bottom of it; choosing ＋ New column… asks only for a title — the color is assigned automatically and the column is added at the right-hand end of the board — and then moves the task into it. The move is written straight to the task file, so it appears in ait board on its next refresh. The button is offered for parent tasks only: child tasks have no card on the board. When the multi-session view is on, the move targets the followed pane’s own project, not the one this minimonitor was started in.

Unlike n, which only offers the followed task’s next ready sibling, p reaches any task. That includes tasks that are not cleanly pickable: if the target is not Ready, or is still waiting on an unfinished dependency, the dialog says so and the confirm button reads Launch anyway instead of OK. Minimonitor still lets you launch it — it just never does so silently. It also warns when an agent for that task is already running in this session.

If the number does not look like a task id, or no such task exists, a warning notification is shown and nothing is launched.

How to Launch a Shadow Agent

Press e to launch a shadow agent next to the code agent you are following — 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 followed 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 followed agent’s pane. You stay the driver.

Like minimonitor itself, 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 followed agent — if a shadow is already running for the agent you are following, a second e is refused with a notification.

For what the shadow can do and how to drive it once it is running, see the Shadow Agent workflow guide; for what a shadow is and why you would use one, see the Shadow agent concept page.

How to Open a Scratchpad

Press o to open a scratchpad — a small notes editor — in a split of the followed agent’s pane, below it by default (tmux.scratchpad_position and tmux.scratchpad_height change that). If the agent is working on a task (its window is agent-pick-<id>, agent-qa-<id> or agent-resume-<id>), the scratchpad holds that task’s notes: they are saved as you type, come back when you press o again after re-picking the task, and are deleted when the task is archived. Any other agent gets an unsaved pad, and minimonitor warns Not a task agent — notes will not be saved first.

Like the shadow, the scratchpad is a companion: it never appears in the agent list, and it closes when the agent it belongs to exits or is killed. It stays open while that agent is frozen and restored. Only one scratchpad opens per task and per agent — a second o reports A scratchpad is already open for t<id>. See the scratchpad how-to guides for copying notes into the agent and for what to do when a pad opens read-only.

How to Pick Shadow Concerns

When the shadow agent interrogates a plan, reviews an implementation, or diagnoses errors, it emits a structured concern block alongside its prose. You can forward a subset of those concerns to the followed agent without retyping them:

1. Make sure a shadow is running for the agent (press e if not)
2. Press c

Minimonitor reads the shadow pane, parses its concern block, and opens a checklist modal of the concerns — each tagged with a priority (high, medium, or low) and the plan region it targets. For a concern that priced itself, that badge is derived from the concern’s own impact vector rather than the priority the shadow typed, and a ≠ beside it means the two disagree; a concern that priced nothing keeps its stated priority and shows no ≠. Tick the ones you want, confirm, and minimonitor copies them — with a short preamble — to your clipboard, ready to paste into the followed agent. Nothing is written to the clipboard until you confirm, and minimonitor never types into the agent itself: you stay the driver.

When the block classifies its concerns — plan reviews and implementation reviews both do — the modal splits the list into Needs addressing and Informational. The second section holds findings the shadow reports for your judgement without asking for a change; they are dimmed so what needs attention reads first, and you tick them individually like any other row. A review with no informational findings shows no section headers at all. If some lines in the block could not be parsed, a warning above the list says how many, so a short list is never mistaken for a complete one. If none of them could be parsed, minimonitor says the shadow emitted a block that yielded nothing forwardable — rather than reporting no concerns at all.

Reading a row’s trade profile. A concern that priced itself carries a compact trade profile — ▲robus ▼simpl E:lo: what it would improve, what that would cost, and the effort. In minimonitor’s companion pane the row is three lines for exactly this reason — the mark, badge and region on the first, the body on the second, and the profile on its own third line. A concern that priced nothing has no profile and stays a two-line row, exactly as before. The one-line decision reminder that a wide picker prints above the list needs about 80 columns and 24 rows, so a companion pane does not show it; the per-row profile is the data, and Read the trade profile has the glyph key and the forward / spin-off / reject rule.

Seeing the whole vector. The row degrades to one improve entry, one worsen entry and the effort, with five-character labels. Where the dialog has the rows to spare, a detail panel below the list spells out the focused concern’s vector — one line per entry, full dimension names — and re-fills as you move with ↑/↓. It needs rows more than columns, so a tall companion pane gets it while a short one does not: a 40x20 pane keeps the key hints and the compact profile instead. In a narrow pane it shows the names without their magnitude words, since the arrow colour already carries the magnitude. See See the whole impact vector.

Rejecting a concern. Each row carries one of four dispositions, and they are mutually exclusive: unmarked (□), marked to forward with Space (✓), marked rejected with r (✗, and the row dims), or marked to spin off with t (» — see How to Spin a Concern Off as Its Own Task). 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, minimonitor 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.

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 adapts down to narrow companion panes: 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.

It adapts to short panes separately from narrow ones. The picker normally leaves a margin around itself, but on a pane too short to hold its content that way it uses the full height instead, so the key hints stay on screen for a picker whose content fits the pane at all. A pane carrying both a staleness warning and an unparsed-lines warning in around 20 rows can still run out of room — widen or lengthen the pane if the hints disappear.

If no shadow is running, pressing c tells you to launch one with e; if the shadow has not raised any concerns yet, minimonitor says so and does nothing.

Auto-offer: when the shadow produces a fresh concern block, minimonitor proactively surfaces a Shadow raised 2 concern(s) — press 'c' to pick toast — once per block — so you don’t have to poll the shadow pane for it. The count is of concerns needing attention; any informational ones are noted separately in the same toast, and the review round is named as a (round N) suffix when the block carries one.

A new round re-offers concerns you have already seen, and that is the point. Each review round re-derives the shadow’s findings from scratch, so the offer is keyed on the round as well as the concerns themselves. A repeat round raising an identical list means the shadow re-reviewed and still stands by it — news, not noise — so it is offered again rather than silently suppressed.

Clean and unreadable rounds. A review that finds nothing still records the round, and pressing c then reports Clean review (round 3) — no concerns. If the shadow emitted a block that carries a round but no readable concerns — still mid-stream, or with content minimonitor had to drop — you get a warning and the raw block instead. That is deliberate: reporting it as “no concerns” would hide output the shadow did produce, and the raw view is what lets you tell a rendering mishap from a real mistake in what it wrote.

Configuration: two settings control the shadow, both editable in ait settings:

• Placement — tmux.shadow_same_window (Tmux tab): true (default) splits the shadow into the followed agent’s window; false opens it in its own window.
• Agent and model — the shadow row on the Agent Defaults tab selects which coding agent and model the shadow runs as.

How to Spin a Concern Off as Its Own Task

Not every concern belongs in the plan you are reviewing. Some are real but secondary, and folding all of them in is how a steerable plan turns into a sprawling one. In the concern picker, t marks the focused concern » — keep this, but as its own task. It is mutually exclusive with forwarding and rejecting, and unlike a rejection the row is not dimmed: the concern is being kept, just somewhere else.

When you confirm the picker, each marked concern becomes a draft task in aitasks/new/, carrying the concern’s own priority, a shadow-concern label, and a link back to the task under review. Drafts are not tasks yet — they claim no number and touch no branch, so nothing is committed and an unwanted one is removed with rm. Finalize the ones you want with ait create.

Minimonitor reports the paths it created, because drafts have no id to report. aitasks/new/ is a shared drop directory, so the toast also gives you a selector for exactly this batch:

2 concern(s) parked as drafts — finalize with 'ait create':
  aitasks/new/shadow_error_handling_a1b2c3d4_1.md
  aitasks/new/shadow_retry_logic_a1b2c3d4_2.md
(this batch: ls aitasks/new/*a1b2c3d4*)

A spun-off concern is also recorded as handled for this task, so the shadow stops raising it in later rounds — it is being tracked elsewhere now. If the drafts are created but that record cannot be written, minimonitor says so explicitly rather than reporting success: the drafts exist, the concern will come back next round, and spinning it off again would create duplicates.

How to Edit the Payload Before It Is Copied

Ticking rows decides which concerns are forwarded. What actually gets pasted into the coding agent is prose, and prose sometimes needs a hand: a concern’s body may be twice as long as the part that matters, the preamble may not suit this particular hand-off, or you may want to add a sentence of your own (“only the second one — the first is already handled in the plan”).

Press e in the concern picker to open the outgoing payload in an editor, showing exactly the text that will land on the clipboard. It is a normal text box: arrow keys move, shift+arrows select, typing replaces the selection, and ctrl+z undoes. ctrl+s saves and returns to the picker; Esc returns without keeping the edit. Confirming the picker then copies your text rather than the generated payload, and the toast says “Edited payload copied to clipboard” so you can tell which one you got.

Three behaviours are worth knowing:

• e needs something to edit. With no row ticked to forward there is no payload, so e says so instead of opening an empty box.
• An emptied editor is refused. Saving a blank buffer would silently fall back to the generated text, so ctrl+s declines and tells you; use Esc if you want to abandon the edit.
• Changing the ticks after editing discards the edit. Your text was written against a particular selection, so if you tick or untick a row afterwards the picker copies the regenerated payload and warns you that the edit was dropped — it never quietly pastes text that disagrees with the rows you marked. (Toggling a row off and straight back on changes nothing, so the edit survives that.)

Editing only affects the clipboard. Rejections and spin-offs always record the concern’s original text, because the shadow matches its own records against freshly parsed concerns on the next round.

How to Run the Auto-Recheck Loop

Reviewing a plan with a shadow is a loop: the shadow raises concerns, you forward some, the agent revises, and then the shadow has to re-read and review again. Press L to have minimonitor drive that last step for you. While the loop is armed, minimonitor watches the followed agent; once it has produced real work and settled back at a prompt, minimonitor sends a single-line recheck into the shadow pane, naming the round to review next.

Press L again to disarm. A status line shows the loop’s state the whole time it is armed:

When the loop holds instead of sending. Sometimes the loop is ready to send but the shadow pane is not safe to type into at that moment. It then holds: the delivery is called off, the loop stays armed, and the status line says why. A hold is not a failure. A toast explains it once, when it starts, and the banner stays up until a recheck is delivered or you disarm:

Minimonitor never takes the shadow out of scroll-back for you — you are reading it. The two Enter withheld banners describe what happened, not what the input box holds now, so they stay accurate after you submit or clear the text. A few routine holds show no banner at all; every hold, shown or not, is recorded in the loop log described below.

When the loop disarms itself, the banner clears and a warning names the reason. It disarms only when something is definitely wrong: the followed agent’s pane or the shadow pane has gone, the shadow was swapped for an agent minimonitor cannot read, or a delivery failed outright — for example an Enter that never landed, which leaves the recheck text in the shadow’s input box for you to submit or clear there. An uncertain reading holds rather than disarms, and an open picker pauses the loop.

Finding out why after the warning has gone. Every disarm and every hold is also written to a log. Run ait minimonitor --loop-log from any shell — it works while minimonitor is running — to print the 20 most recent events, newest first; ait minimonitor --loop-log 100 shows more. Each event gives its time, whether the loop disarmed or held, the same reason the warning gave, and the followed agent / shadow pair it happened to, which matters when several pairs are running. An event that ended a delivery also shows what the shadow pane looked like at that moment (pre_enter_verdict, pane_in_mode, pane_mode) — include those when reporting a problem. A warning that ends in (not recorded) means the event could not be written to the log. The log lives in ~/.config/aitasks/review_loop_events/ (override with AITASKS_REVIEW_LOOP_LOG_DIR).

Minimonitor only ever writes into the shadow pane. The followed agent is never typed into: the loop automates asking the shadow to look again, not answering on your behalf. Forwarding concerns stays a clipboard step you confirm.

Where the loop can run. Two independent requirements, and both are checked when you press L:

• The followed agent can be any of the supported coding agents — Claude Code, Codex CLI, or OpenCode. Each one had to be qualified separately, because the loop injects keystrokes rather than merely reading: minimonitor has to be able to tell real work from a redraw caused by moving the selection in whatever dialog that agent is showing. Arming for an agent that has not been qualified refuses, and the message names the ones that have.
• The shadow can likewise be any of the supported coding agents, so any pairing works — a Codex agent watched by a Claude shadow, or the reverse. Minimonitor needs to recognise when that shadow is idle before it will type into it.

Other refusals are about state rather than support, and each says which: no followed agent pane; no shadow pane yet (launch one with e); or the shadow’s agent could not be identified yet, which is usually a timing answer worth retrying a moment later rather than a permanent no.

The manual recheck still works, and is sometimes needed. The loop notices the agent working by watching its pane, and a revision that leaves the visible output byte-identical and grows no scrollback is invisible to it. When that happens the loop simply does not fire — just ask the shadow to refetch and recheck yourself.

How to Mark an Agent as Prioritized

When you are following many agents, some matter more than others. Press Space to cycle the mark on the agent this minimonitor follows — the one pinned at the top under ── this agent ── — through prioritized (★), parked (P) and unmarked (dim ☆). It does not matter which card in the list is highlighted; Space here always means “the agent I am watching”. The column is always present, so rows never shift when you change one.

Parking the followed agent does not stop this minimonitor watching it. Parking is a signal to other monitors’ lists — it takes the agent out of them and stops them checking it. This pane is bound to that one agent, so its pinned card keeps updating, and L, c and the shadow companion all keep working exactly as before. The pinned card simply shows P instead of ★ or ☆.

Press P to hide parked and frozen agents from the scrollable list, and P again to show them — it is one filter over both kinds of set-aside agent, not two. With them hidden you cannot unpark from the list — reveal them first, then use Space in ait monitor, where Space acts on the focused card.

The cards in the scrollable list show marks but cannot be toggled from here — to mark some other agent, use ait monitor, where Space acts on the focused card.

If this window has no agent to follow — including a window you have renamed off the agent- prefix — Space shows a warning and writes nothing, and the pinned card shows no mark at all. The card itself is still there, headed ── this window ──; what a rename switches off is the agent-only actions (k, n, e, E, I and this mark), which is the point of taking a window out of the agent rotation.

The marks are stored per user, outside every repository, in ~/.config/aitasks/agent_marks.json (override the path with AITASKS_AGENT_MARKS_FILE). That means a mark you set here is visible from every other project’s minimonitor and monitor — usually within one refresh cycle (about 3 seconds). Marks survive restarting the TUI.

Each mark is keyed by the pair (project root, tmux window name), so two projects that happen to run identically-named agent windows never share a mark.

A prioritized mark is purely visual: it does not reorder the list or change any counter. A parked mark is not — it takes the agent out of the three watched counters and into the Np term, and P hides its row.

Automatic cleanup. You never have to unmark stale entries by hand:

• Age — a mark older than about 2 days is dropped automatically. Set AITASKS_AGENT_MARK_TTL_DAYS to change the window (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. This check is deliberately conservative: if a project’s session cannot be seen at all — it is not running, or lives on a different tmux server — its marks are always left alone. A project you simply have not opened today never loses its marks.

Note: marking the agent you are already watching is exactly the point — the mark is per user and cross-project, so it is how you tell every other view that this is the agent that matters. Check ait monitor, or another project’s minimonitor, and the agent you flagged from here stands out there.

How to Freeze the Agent You Are Done With

Parking keeps the agent running. Freezing ends it and keeps its output instead — the cheaper choice once an agent has said everything you needed.

Press f to freeze the followed agent. A dialog confirms (Freeze this agent?) and explains what happens: the process ends, its terminal output is captured and kept, and it can be restored or re-picked later. The button reads Freeze and is styled as an ordinary action, because nothing is lost.

The agent’s pane does not close. It is taken over by the frozen-agent viewer, which replays the captured output in place, so the window keeps its name and its layout.

In the scrollable list a frozen agent renders as its mark followed by a cyan F, the window name without its agent prefix, and a dim frozen:

☆F pick-1705  frozen
★F qa-1699  frozen

There is no state dot and no captured preview — a frozen agent has no current answer to show. Frozen coexists with the priority/parked mark rather than replacing it: the mark cell stays where it was, so rows never shift, and Space still cycles the mark on the followed agent even while it is frozen.

Restore and re-pick are the viewer’s own keys, not minimonitor’s. Press Tab to move into the viewer’s pane, then R restores the agent there and P re-picks its task with a fresh agent (often cheaper). Every other minimonitor key keeps its usual meaning, so p still picks a task by number while the followed agent is frozen — the confirmation then offers no “kill followed agent” checkbox, because the frozen agent is retired with k instead.

k drops the frozen agent. It confirms with a red Drop button, because it deletes the captured output along with the record: Its captured output is deleted along with the record, and the stand-in pane is closed. This cannot be undone. A verified restore or re-pick deletes it too — copy it first.

Z freezes everything, and it reaches further than this list. Freeze-All covers every aitasks session on the machine — other projects included, and parked agents included — not just the agents shown here. The confirmation says so and names the real count, which is why that number is usually larger than what you can see.

How to Jump to Another TUI

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

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

Select a target and the switcher focuses the existing tmux window running that TUI or creates a new window and launches it.

How the Agent List Refreshes

The agent list refreshes on its own every tmux.monitor.refresh_seconds seconds (default 3) — there is no manual refresh key. Actions that change the agent set (launching or killing an agent) schedule a refresh themselves, so the list catches up immediately rather than at the next tick.

Minimonitor reads the agent list from the same shared status server as monitor, so ait monitor --restart-server refreshes it too — run it when the list still behaves the way it did before a framework change.

How to Toggle the Multi-Session View

By default, minimonitor aggregates agents from every aitasks tmux session on the current tmux server. Press M (uppercase, Shift+m) to toggle to a single-session view that shows only the agents in the tmux session this minimonitor is running in. Press M again to restore the aggregated view.

The toggle is in-memory only — it applies to the current minimonitor process and is not persisted to configuration. It is also independent of the main monitor’s M toggle; switching modes in one TUI does not affect the other.

When the multi-session view is ON, agents are grouped under ── <session_name> ── divider rows. The divider rows are display-only — they cannot be focused, and Up/Down navigation skips over them.

For the full cross-TUI story (auto-discovery, rendering details, cross-session focus from the main monitor), see Multi-session view in the monitor reference.

How to Jump Between Projects

Each project’s agents sit together under their own ── <session_name> ── divider in the multi-session view. With many agents the list is longer than the pane, so press Shift+Down to jump to the next project and Shift+Up to jump to the previous one. The list scrolls so that project’s divider sits at the top, and its first agent card is selected — ready for s, i or another jump.

• The jump wraps around: Shift+Down on the last project goes to the first, and Shift+Up on the first goes to the last.
• “The current project” is the one whose card is selected. With no card selected, it is the project at the top of the visible list.
• Only the agent section’s projects are jump targets. The other section below them is not.
• When the whole list already fits in the pane there is nothing to scroll, and the keys do nothing. They also do nothing in the single-session view, which has only one project.
• A jump counts as scrolling away from the bottom, so it releases the bottom pin described under Mouse Support, exactly as the scroll wheel does.

How to Filter the List by Phase or State

Press Shift+Right to narrow the list to one kind of agent, and press it again to move on to the next kind:

all → PLAN → IMPLEMENT → POSTIMPL → parked → frozen → back to all

Shift+Left walks the same cycle backwards, so from all it goes straight to frozen.

• PLAN / IMPLEMENT / POSTIMPL show only the live agents whose task is in that workflow phase. An agent whose phase cannot be told (unknown), or that has no task, matches none of them, and neither do parked or frozen agents. The phase is advisory: the filter narrows what you see and never changes what any key does.
• parked shows only parked agents and frozen only frozen ones. An agent that is both is shown under frozen, the same way its card reads frozen. These two show their agents even while P is hiding parked and frozen agents — the filter you picked wins.
• Under any filter other than all, the other section is hidden, since those panes have no phase or state.

While a filter is active, a line just above the list names it together with the keys that change it — filter: IMPLEMENT ⇧←→. At all the line disappears and the list gets its row back. Each change also shows a short notice.

Changing the filter selects the first agent of the new list and scrolls it into view, even if you were scrolled far down or pinned to the bottom before.

The filter is in-memory only: a new minimonitor always starts at all, so a filter you forgot about can never hide agents after a restart. It is separate from P, which keeps its own on/off state.

How to Collapse the Key Hints or Open the Full Key Help

Minimonitor has no footer: the band at the bottom of the pane lists every key, and it costs about ten rows of a short companion pane. Press x to collapse it to a single line that names only the two keys you need to get it back — x:keys H:help — and the agent list takes the rows. Press x again to bring the full band back.

The choice is remembered per user, as minimonitor_key_hints: collapsed (or full) in aitasks/metadata/userconfig.yaml, so every minimonitor you open afterwards — including the ones auto-spawned beside new agents — starts the same way. If that file cannot be written (for example, it is not valid YAML), the band still collapses for this minimonitor and a warning says the choice was not saved.

Press H (Shift+h) to open the full key help: a scrollable list of every minimonitor key, each with a short explanation. Scroll it with the arrow keys or Page Up / Page Down, and close it with Esc, q or H. It fits the narrow companion pane, down to about 24 columns.

Both keys can be rebound like any other with ?, the shortcut editor. The band, the collapsed line and the help list always show the keys you actually bound. A long rebind such as ctrl+y is shown in the compact ^y form, and when even that does not fit the collapsed line beside its labels, the line shows the two keys alone.

When a pane is short and the advisory banners above the list need room, the full band compacts to its first two rows on its own. The band lists x and H first, so with the default keys they stay visible when it does.

How to Quit

Press q to quit minimonitor manually. The pane running minimonitor closes; the rest of your tmux session is unaffected. Because auto-despawn already closes minimonitor whenever its companion agent exits, manual quit is mainly useful when you want to reclaim the sidebar column while the agent is still running.

Freezing the agent is not one of those exits. A frozen agent’s pane is still occupied — by the frozen-agent viewer standing in for it — so minimonitor stays open beside it, which is what lets you restore or re-pick the agent from here.

Pairing Minimonitor with Monitor

Minimonitor and monitor are complementary and can run side by side. A productive layout looks like this:

• Window 0 — monitor: full dashboard via ait monitor (or ait ide), with pane list, preview, and all controls.
• Window 1 — agent-t42-...: a code agent window. Split horizontally so that the left pane runs the agent and the right pane runs minimonitor.
• Window 2 — agent-t43-...: another agent window with its own minimonitor split.
• Window 3+ — other TUIs: board, codebrowser, settings, brainstorm, all reachable from any monitor via j.

From any of the agent windows, Tab jumps into the code agent pane and j opens the TUI switcher to hop back to the full monitor dashboard. From monitor, s on an agent card brings you to the companion minimonitor alongside it. See How to Switch tmux to the Focused Pane in the monitor docs for the reverse direction.

Configuring Auto-Spawn

Auto-spawn (from board, codebrowser, monitor’s next-sibling launch, and the TUI switcher’s explore launch) is controlled by two keys in aitasks/metadata/project_config.yaml:

tmux:
  minimonitor:
    auto_spawn: true   # set to false to disable automatic side splits
    width: 40          # width (in columns) of the minimonitor side pane

You can edit these directly, or use ait settings → Tmux tab, which writes the same keys.

auto_spawn: false turns off the automatic splits only. The TUI switcher’s Shift+M still adds a minimonitor on request — see How to Add a Minimonitor Beside Any TUI.

Key Bindings Quick Reference

All actions below are also available via mouse — see Mouse Support.

Minimonitor inherits config keys (tmux.default_session, tmux.monitor.refresh_seconds, tmux.monitor.idle_threshold_seconds, tmux.monitor.capture_lines, tmux.monitor.agent_window_prefixes, tmux.monitor.tui_window_names) from the same project_config.yaml section monitor uses — see the monitor reference for the full list.

Next: Code Browser — review diffs with task-aware annotations.