Feature Reference

Keyboard Shortcuts

Board Navigation

Task Operations

Column Operations

Modal Navigation

Task Card Anatomy

┌─────────────────────────────────┐  ← Border color = priority
│ t47 *  playlists support        │  ← Task number (cyan), * if modified (orange), title (bold)
│ 💪 medium | 🏷️ ui,api | GH | PR:GH | @alice │  ← Effort, labels, issue/PR indicator, contributor
│ 🔒 alice@example.com            │  ← Lock indicator (if locked)
│ 🚫 blocked | 👤 alice           │  ← Status/blocked, assigned to
│ 🔗 t12, t15                     │  ← Blocking dependency links
│ 📎 folded into t42              │  ← Folded indicator (if applicable)
│ 👶 3 children                   │  ← Child task count (if parent)
└─────────────────────────────────┘

Not all lines are shown on every card — lines only appear when the corresponding data exists.

Priority Color Coding

The focused card always shows a double cyan border, regardless of priority.

Issue Platform Indicators

The board detects the issue tracking platform from the URL hostname:

PR Platform Indicators

Tasks created from pull requests (via ait pr-import) display a pull request indicator on the task card info line:

GitLab uses “MR” (Merge Request) terminology, which the indicator reflects.

View Filters

The View Selector widget at the top-left of the filter area renders as:

[a All | l Locked | f Free | i In-Flight | y By-Topic]   g Git   t Type

It splits filtering into a base radio (mutually exclusive — exactly one is always active) and two independent add-on toggles. The active base and any active toggle are highlighted in bold cyan; inactive segments are dimmed. All filters compose with text search using AND logic.

Base filters (radio)

Pressing the key for the currently active base is a no-op. Locked and Free are leaf-level inverses (Locked ∪ Free = All, Locked ∩ Free = ∅) — the Locked view additionally includes parent/sibling cards as context.

By-Topic lanes: The By-Topic view uses the task’s anchor field when set; otherwise a child falls back to its parent topic and a standalone task falls back to its own id. If the root task is archived or not currently loaded, the anchor id still remains the stable lane key. Topics with only one visible task are collected in the trailing Ungrouped lane. See Topic anchoring for creation flags, inheritance rules, and when to use anchors instead of parent-child tasks or dependencies.

By-Topic lane sort order: Lanes are ordered most-recently-touched first by default. In the By-Topic view, press o to open a picker and choose the lane sort mode:

The Ungrouped lane stays pinned last in every mode. The choice persists per-user (in your local board settings), so it survives restarts without affecting teammates.

Add-on filters (toggle)

Add-ons compose with the active base. Example: l + g shows busy tasks linked to an issue/PR; f + t (with bug selected) shows free bug tasks ready to pick.

Locked view auto-expansion: When the base filter switches to Locked, parent tasks that have at least one busy child are automatically expanded (their child cards are displayed). When switching away, these auto-expanded parents are collapsed back unless they were manually expanded before entering the view.

Column Configuration

Columns are stored in aitasks/metadata/board_config.json:

{
  "columns": [
    {"id": "now", "title": "Now", "color": "#FF5555"},
    {"id": "next", "title": "Next Week", "color": "#50FA7B"},
    {"id": "backlog", "title": "Backlog", "color": "#BD93F9"}
  ],
  "column_order": ["now", "next", "backlog"],
  "settings": {
    "auto_refresh_minutes": 0,
    "sync_on_refresh": false
  }
}

• id — Unique identifier (auto-generated from title on creation)
• title — Display name (can include emojis)
• color — Hex color code for the column header and border
• column_order — Controls left-to-right display order
• settings.auto_refresh_minutes — Interval in minutes for periodic board refresh (0 to disable, default 0)
• settings.sync_on_refresh — Enable automatic sync with remote on each auto-refresh interval (default false). Requires .aitask-data worktree (data branch mode). When enabled, the board subtitle shows “+ sync”
• settings.collapsed_columns — List of column IDs that are currently collapsed (default: empty). Collapsed columns show only their title and task count in a narrow strip. Tasks in collapsed columns are not rendered, which improves performance for boards with many tasks

The “Unsorted / Inbox” column is a special dynamic column (ID: unordered) that appears automatically when tasks exist without a boardcol assignment.

Color Palette

When adding or editing a column, you can choose from 8 predefined colors:

Task Metadata Fields

The board reads and displays the following frontmatter fields from task files:

Board Data Fields

Two metadata fields are managed internally by the board:

• boardcol — The column ID where the task is placed (e.g., "now", "backlog", "unordered"). Tasks without this field appear in the “Unsorted / Inbox” column.
• boardidx — The sort index within a column. Lower values appear higher. After any movement operation, indices are normalized to 10, 20, 30, etc.

These fields are always written last in the frontmatter and are updated using a reload-and-save mechanism that prevents overwriting other metadata fields changed externally.

Lock Status Display

Lock information is not stored in task files – it is fetched from the remote aitask-locks branch via aitask_lock.sh --list and maintained in memory as a lock map. The board refreshes the lock map on startup, on every manual/auto refresh, and after lock/unlock operations.

Locks older than 24 hours show a (may be stale) warning in the detail view.

Button states in detail dialog:

For details on the underlying lock mechanism, see the ait lock command reference.

Modal Dialogs Reference

Git Integration Details

The board auto-detects whether task data lives on a separate aitask-data branch (via the .aitask-data/ worktree) or on the current branch (legacy mode). All git operations are routed through a worktree-aware helper, so the board works transparently in both modes.

Modified file detection:

The board queries git status --porcelain -- aitasks/ on startup and after each refresh to identify modified .md files. Modified tasks show an orange asterisk (*) next to their task number. In branch mode, this targets the aitask-data worktree automatically.

Commit workflow:

1. Selected files are staged with git add <filepath>
2. A commit is created with the user-provided message
3. The board refreshes git status after commit

In branch mode, commits target the aitask-data branch, not the main code branch.

Revert workflow:

Runs git checkout -- <filepath> to discard local changes and restore the last committed version.

Delete workflow:

1. Files are removed with git rm -f <filepath> (falls back to os.remove for untracked files)
2. Empty child task/plan directories are cleaned up
3. An automatic commit is created: “Delete task t and associated files”

Configuration Files

Both files are auto-created with defaults if they don’t exist.

Environment Variables

Terminal auto-detection order: $TERMINAL, then x-terminal-emulator, xdg-terminal-exec, gnome-terminal, konsole, xfce4-terminal, lxterminal, mate-terminal, xterm. If none found, the board suspends to run commands in the current terminal.

Next: Monitor — the dashboard of every pane in your tmux session.