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 Modes

The View Selector widget at the top-left of the filter area provides three task filtering modes. The active mode is highlighted in bold cyan; inactive modes appear dimmed. View modes combine with text search using AND logic.

Implementing view auto-expansion: When Implementing mode is activated, parent tasks that have at least one child with status “Implementing” are automatically expanded (their child cards are displayed). When switching away from Implementing mode, these auto-expanded parents are collapsed back unless they were manually expanded before entering the mode.

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": 5,
    "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 5)
• 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.