Stats

×

Customizable keys: every shortcut here can be rebound. Press ? in this TUI for the in-place editor, or open Settings → Shortcuts.

Launching

ait stats-tui

The Stats TUI requires the shared Python virtual environment (installed by ait setup) with the textual, pyyaml, and plotext packages. All three are installed and version-pinned by ait setup, so the interactive chart panes work out of the box.

Inside tmux you can also reach the TUI via the TUI switcher — press j in any other aitasks TUI and pick Stats.

Purpose

Stats is the interactive, pane-based view of archived task completion data. It reuses the same stats/stats_data.py extraction module that backs the text-only ait stats command — the two share a single source of truth for summary counts, daily/weekly trends, label and issue-type breakdowns, code agent / LLM model histograms, and verified model score rankings.

Use ait stats for a scrollable text report you can pipe or redirect; use ait stats-tui when you want to flip between charts, try different layout combinations, or watch a single pane full-width.

Layout

┌──────────────┬──────────────────┐
│  sidebar     │                  │
│  (active     │   content        │
│   layout     │   (chart or      │
│   panes)     │    summary)      │
├──────────────┤                  │
│  layout      │                  │
│  picker      │                  │
└──────────────┴──────────────────┘

The left column is split into two list panels:

• Pane sidebar (top) — the panes that belong to the currently active layout. Highlighting a row shows that pane immediately on the right; no Enter needed.
• Layout picker (bottom) — the set of available layouts. The active layout is marked with a ● bullet. Press Enter on a row to activate that layout (its panes replace the sidebar contents).

Tab / Shift+Tab flips focus between the two list panels, and the focused panel gets a primary-colored left border as a visual hint.

Built-in layouts (presets)

Four presets ship with the framework, each bundling three panes:

Presets are defined in aitasks/metadata/stats_config.json and are read-only at runtime: editing them happens out of the TUI, by editing that file directly.

Custom layouts

You can define your own layouts on top of the presets. With focus on the layout picker:

• n — create a new custom layout. You are prompted for a name (must be unique across presets and existing customs), then a pane selector opens where you tick the panes you want to include.
• e — edit the highlighted custom layout’s pane list. Opens the same pane selector pre-populated with the current selection.
• d — delete the highlighted custom layout. Only custom layouts can be deleted; presets are protected.

Custom layouts appear below the presets in the picker with a [dim](custom) suffix.

Config persistence

The TUI uses a layered configuration:

• Project layer — aitasks/metadata/stats_config.json ships the four default presets and is checked into git. It is treated as read-only at runtime.
• User layer — aitasks/metadata/stats_config.local.json is gitignored and holds your runtime choices: the active layout name, your custom layouts, and the days / week_start preferences. Every Enter on the layout picker and every successful custom-layout save writes to this file.

This split keeps shared presets consistent across a team while letting each developer keep their own customizations local.

Mouse Support

The Stats TUI supports full mouse interaction in addition to the keyboard shortcuts:

• Click a pane name in the sidebar — show that pane on the right (mirrors highlighting via ↑ / ↓).
• Click a layout name in the layout picker — highlight it; click again (or press Enter) to activate.
• Scroll wheel — scroll the sidebar, layout picker, or chart content.
• Click dialog buttons — buttons in the new-/edit-/delete-layout dialogs and the pane selector are clickable.

All keyboard actions documented below remain available.

Navigating

Next: Back to the TUI overview or jump to the text command ait stats.