How-To Guides
Task-oriented guides for reading implementation trails with ait trails
Trails
Stand-alone reader for implementation trails — the board’s By-Trail view as its own TUI
Maturity:
Depth:
ait trails is a stand-alone reader for implementation trails: it shows a stored trail as wave columns, with each member’s classification, confidence, status and drift, and the trail’s summary underneath. You can keep several trails open, one tab each, and switch between them instantly. It is the board’s By-Trail view (z) running on its own — the same lanes, cards and keys, without the Kanban board around them. The By-Trail view stays inside the board as well, and both read the same stored trails.
Customizable keys: every shortcut here can be rebound. Press
?in this TUI for the in-place editor, or open Settings → Shortcuts. The trail keys are the board’s ownboardentries, so a rebind applies in bothait trailsand the board’s By-Trail view.
Purpose
A trail answers “in what order should this group of tasks land, and why”. Reading one does not need the board: ait trails starts directly in the trail selector, loads nothing but the task files and the trail itself, and never writes your board layout. Use it when you want to follow a trail — which wave is next, which members have landed, what has drifted — without the whole board in front of you.
The TUI is read-only. It never writes a trail and never changes a task. The two keys that start trail authoring — T to create a trail for the focused task, R to re-author the one on screen — open the /aitask-trail workflow in a code agent, and that workflow asks you to confirm before it writes anything. p is the other agent launch: it opens /aitask-pick for the focused task, and the task is claimed by that workflow, not by the TUI. L searches the other projects for linked trails and can start a tmux session for one of them and open the trail in that project’s own ait trails — it writes nothing either.
Relationship to the board
| Aspect | ait board (By-Trail view, z) | ait trails |
|---|---|---|
| Opening a trail | z, then the selector opens when no trail is active yet | The selector opens on launch |
Trail keys (s, r, d, R, v, L, Enter) | Yes | Yes — the same bindings |
| Several trails open at once | No — one trail; choosing another replaces it | Yes — one tab each ([ / ], 1–9, Ctrl+W) |
T | Hidden in By-Trail; used from the kanban and By-Topic views | Opens the trail-creation workflow for the focused live card |
p (pick the focused task) | Yes | Yes — the same launch dialog, for a live local card |
Move to a column (m / M) | Yes | No — there are no board columns here |
Sync with remote (S) | Yes | No — sync from the board or with ait sync |
Writes board_config.json | Yes (board layout and settings) | Never |
TUI switcher (j) | Yes | Yes |
The two TUIs keep separate trail selections. Switching between them with j does not carry the open tabs or the focused card across — see How to move a wave onto the board.
Launching
ait trailsfrom a shell in the project.ait trails --trail <handle>opens that trail directly instead of the selector;<handle>is the trail’sart:<id>handle. Add--task <id>to also focus that task’s card. A jump from a linked trail in another project startsait trailsthis way — see Launch and environment.jthenifrom any TUI, through the TUI switcher. The switcher’s bottom hint row does not advertisei, but the entry is listed in the switcher and the key works.jthenbfromait trailsgoes back to the board.
ait trails reads the task directory from TASK_DIR (default aitasks), the same as the other ait commands.
Next: How-To Guides — opening a trail, keeping it current, and handing a wave to the board.