Feature Reference

Keybindings

Every key below can be rebound. Press ? for the in-place editor, or open Settings → Shortcuts. See Shortcut scope for the scope each screen uses.

A key whose condition does not hold is hidden from the footer and does nothing. r and the request keys are greyed out instead (shown, but disabled) while their own run or request is in progress. While a dialog is open, none of the keys below apply.

Main list

x, p, b, z, P and the item requests t, a, w, T are also hidden while todo.md cannot be read. All request keys are hidden when the TUI does not run in a pane of the aitasks tmux server.

Item details

On a details screen, z uses the highlighted trail row; with none highlighted it opens the task’s only trail, or a picker when there are several.

Source viewer

Q&A log and Q&A entry

Dialogs

Dialogs have no footer; Escape cancels each of them.

A click in any list only selects the row; Enter opens it.

Shortcut scope

The dialogs have no scope of their own. The pick dialog is the shared agent command dialog of the other TUIs. A rebind of p, b, P, x, r, t, a or T changes the key the items’ How lines name.

The main list

Header

The first line is Sitrep · <repository root>. The second line is <state> · read HH:MM:SS · <agent>, followed by · refreshed HH:MM ok (or with errors) once a collect-and-re-check run has finished:

• <state>: no items yet, or N items · M open in Now (1 item for one). While the done and dismissed groups are hidden it adds · N done, M dismissed hidden. While a label filter is on it adds · filtered by: <labels> · N hidden (F clears).
• read: the time of the last read of the list.
• <agent>: agent: running, agent: not running — press A, or agent: unknown (the tmux query failed, or the TUI does not run in a pane of the aitasks tmux server).

When todo.md cannot be read and no good copy was read earlier, <state> is store unusable.

Groups

In this order: Now (stored as Pick now), Next, Waiting, then Recently done and Dismissed while d shows them. Each group heading shows its count, (0) included.

Columns

What to do

Each item gets one “What to do” line (the list column and the first line of its details) and one “How” line (in its details). They depend on the item’s kind and state. The keys named are the default ones; a rebind changes them.

The How lines name the request keys even while the agent is not running; the keys themselves appear only once it runs.

Item details

The title is c<N> · <title>. The body, in order:

• Item: What to do, How, and About when the item has a reference (push of branch <b> (commit <sha>), task <N> in project <p>, or the reference itself).
• For a task item: Priority (<priority> · effort <effort>), Task status ((archived) when the task is archived) and Created (the stored created_at), or task file not found; and Trails: the trails with their waves, none, looking… until the first scan, or unknown (<reason>). A failed or partial scan never reads as none.
• Checked (never, or the time and its age) and Outcome.
• Context: Background, Origin (Agent, Task, Commit, Date, Skill, Pane), Theme, and for an unparsed-output review its case and the ait sitrep case show <case> command. No context entry. when the item has none.

Links

A source that points at lines (, line N, , lines A–B) or that fails to open starts as raw text with line numbers, scrolled to the line. Links inside a rendered file are never followed. A file larger than 256 KiB shows its first 256 KiB. A source the TUI will not open shows Not followed: <reason>. The harvest’s identity receipts (KEY sources) stay in the store but are not listed.

Requests

These are the request lines the /aitask-sitrep skill documents. The question in the ask dialog is one line of at most 300 characters, with no tabs or control characters, and it may not end with an @mention (that would open the agent’s file picker, which would take the Enter). Runs of spaces are collapsed to one.

A request key works only while the agent is running, and one request at a time: a second press while one is being delivered is refused, never queued. Every key re-checks the item first: when it changed since the details were opened, nothing is sent.

Supported agents are Claude Code, Codex CLI and OpenCode, whose input boxes the TUI knows how to read. Any other agent is refused before anything is typed.

Request results

Every result shows a short message. Every result except submitted also opens a panel with the request line, the result and its detail. The panel border is red only for unknown.

Refusal reasons:

Recovering from a result

The how-to gives the same rules in steps: never press Enter in the agent’s pane without reading its whole input box first; treat unknown as possibly sent; and after identity_changed, look for a leftover line before you retry.

Action results

The collect-and-re-check panel has one line for each half: Harvested: N added, M existing, Nothing new to harvest or Harvest failed: <why>, then Refreshed: N checked, M changed, Nothing to refresh (<reason>) or Refresh failed: <reason>. The re-check runs even when the collection failed.

Timing

• The list is re-read every 2 seconds; it is parsed again only when todo.md or qa.md changed. The age labels update on every read.
• The agent’s state is checked every 3 seconds.
• Trail membership is scanned in the background after the list changes, when a task item’s details open, and every 60 seconds.
• Collect-and-re-check runs once at startup (reported in a short message, no panel) and on r.

Launch and environment

• Store — <main worktree>/.aitask-sitrep/ (todo.md, qa.md), the same store the sitrep agent and the harvest use. The TUI writes it only through the list’s writer.
• Damaged files — the TUI keeps the last good view, and a red banner says Store unusable: <error> (or Q&A log unusable: <error>) and Press R to restore the last good generation.
• Missing packages — when textual or pyyaml is missing, the launcher stops and tells you to run ait setup.
• Outside tmux — the header reads agent: unknown, and the request keys and A are hidden (the agent’s state cannot be read there). Run ait sitrep from inside tmux to start or reach the sitrep agent. b and z still work and name the command to run (./ait board --focus <id>, ./ait trails --trail <handle> --task <id>).