How-To Guides

How to Organize Tasks into Columns

Moving a task to a different column:

1. Focus the task card using arrow keys
2. Press Shift+Right to move it to the next column, or Shift+Left to move it to the previous column

The task is appended to the end of the target column. Column order follows the configured order, with “Unsorted / Inbox” on the far left. Collapsed columns are skipped when moving tasks.

Reordering tasks within a column:

1. Focus the task card
2. Press Shift+Up to swap it with the task above, or Shift+Down to swap it with the task below
3. Press Ctrl+Up to jump the task to the top of the column, or Ctrl+Down to jump it to the bottom

Task positions are stored in the boardidx field of each task file’s frontmatter. After any move, indices are automatically normalized to 10, 20, 30, etc. to prevent drift.

Note: Child tasks cannot be moved between columns or reordered — only parent tasks can be repositioned.

How to Customize Columns

×

The column operations — add, edit, delete, reorder, collapse, expand — are all available via keyboard, mouse, or the command palette (Ctrl+Backslash).

Notes:

• Column IDs are auto-generated from the title (lowercased, non-ASCII stripped, spaces replaced with underscores). Editing a column preserves the ID.
• The “Unsorted / Inbox” column always appears on the far left when it contains tasks — it cannot be reordered.
• Collapse/expand state is saved in board_config.json and persists across restarts. Tasks in collapsed columns are not rendered (improves performance on large boards).
• Arrow-key navigation can reach collapsed columns (they show a focusable placeholder). Task movement (Shift+Left/Right) skips collapsed columns.

How to Edit Task Metadata

1. Focus a task card and press Enter to open the detail dialog
2. Use Up/Down arrows to navigate between fields
3. For editable fields (Priority, Effort, Status, Type), press Left/Right arrows to cycle through options:
   • Priority: low ↔ medium ↔ high
   • Effort: low ↔ medium ↔ high
   • Status: Ready → Editing → Implementing → Postponed (cycles)
   • Type: Loaded from aitasks/metadata/task_types.txt (defaults: bug, chore, documentation, feature, performance, refactor, style, test)
4. When you’ve made changes, the “Save Changes” button becomes enabled
5. Click “Save Changes” or navigate to it and press Enter

The current option is highlighted with bold reverse text. Arrows (◀ ▶) on either side indicate that you can cycle.

Important: The board reloads the task file from disk before saving, then applies only the fields you changed. This prevents overwriting changes made externally (e.g., by another code agent session) to other fields.

Note: Tasks with status “Done” or “Folded” are displayed in read-only mode — the cycle fields are replaced with static text and action buttons are disabled.

How to Search and Filter Tasks

1. Press Tab to focus the search box (or click it)
2. Type your search query — filtering happens in real-time as you type
3. Cards that don’t match are hidden; matching cards remain visible
4. Press Escape to return focus to the board (the filter stays active)
5. Clear the search box text to show all tasks again

The search is case-insensitive and matches against both the task filename and the entire metadata dictionary. This means you can search by task number (e.g., “t47”), title words, labels, status, assigned person, or any other metadata value.

Note: View mode filters (described below) combine with text search using AND logic. A task must match both the active view mode and the search text to be visible.

How to Filter by View Mode

The board provides three view modes that control which tasks are displayed. The active mode is shown in the View Selector widget at the top-left of the filter area, displayed as a All │ g Git │ i Impl. The active mode is highlighted in bold cyan; inactive modes appear dimmed.

Switching view modes (keyboard):

1. Press a to show all tasks (default)
2. Press g to show only git-linked tasks
3. Press i to show only implementing tasks

Switching view modes (mouse):

Click the desired mode label directly in the View Selector widget.

All view (a):

The default view. Shows every task regardless of metadata. Press a to return to this view from any other mode.

Git view (g):

Shows only tasks that have an issue: or pull_request: field in their frontmatter — i.e., tasks linked to a GitHub issue, GitLab merge request, Bitbucket pull request, or other external tracker URL. This applies to both parent and child tasks.

This mode is useful for focusing on tasks that originate from or are tracked by your git platform. Tasks created by ait pr-import (the PR import workflow) automatically have a pull_request: field and will appear in this view.

Implementing view (i):

Shows only tasks with status “Implementing”, plus contextual related tasks:

• Parent tasks that have at least one implementing child are shown
• All siblings of an implementing child task are shown (so you can see the full subtask list)
• Parents with implementing children are auto-expanded — their child cards appear automatically without pressing x

When you switch away from Implementing view, auto-expanded parents are collapsed back (unless you had manually expanded them before entering the view).

Combining with text search:

View modes combine with the search box using AND logic. For example, if you are in “Git” view and type “auth” in the search box, you see only git-linked tasks that also match “auth”. Clear the search box to show all tasks matching the current view mode.

How to Commit Changes from the Board

When you edit task metadata from the board, the changes are saved to disk but not committed to git. Modified files are indicated by an orange asterisk (*) next to the task number.

Committing a single task:

1. Focus the modified task card (the one with *)
2. Press c
3. A commit dialog appears showing the file to commit and a pre-filled message (e.g., “Update t47: playlists support”)
4. Edit the commit message if needed
5. Click “Commit”

Committing all modified tasks at once:

1. Press C (Shift+c) from anywhere on the board
2. The commit dialog shows all modified files and a combined message
3. Click “Commit”

Note: The “Commit” and “Commit All” keybindings only appear in the footer when applicable — i.e., when the focused task is modified or when any tasks are modified, respectively.

How to Revert a Task

If you want to discard changes to a task file and restore it to the last committed version:

1. Open the task detail dialog (Enter)
2. Click the “Revert” button

This runs git checkout -- <filepath> to restore the file. The button is only enabled when the task has uncommitted modifications. It is disabled for tasks with status “Done” or “Folded”.

How to Create a New Task

Press n to create a new task. The board will:

1. Detect an available terminal emulator (checking $TERMINAL, then common emulators like gnome-terminal, konsole, xterm, etc.)
2. If a terminal is found, open ait create in a new terminal window
3. If no terminal is available, suspend the board and run ait create in the current terminal

After creation, the board refreshes automatically to show the new task.

How to Delete a Task

1. Open the task detail dialog (Enter)
2. Click the “Delete” button
3. A confirmation dialog shows all files that will be deleted:
   • The task file itself
   • Associated plan file (if it exists in aiplans/)
   • All child task files and their plans (for parent tasks)
4. Click “Delete” to confirm

Deletion performs git rm on all listed files and creates an automatic commit. If any task had folded tasks, those folded tasks are unfolded (their status is reset to “Ready” and folded_into is cleared).

Delete is disabled for:

• Tasks with status “Done”, “Folded”, or “Implementing”
• Child tasks (must delete the parent instead)
• Read-only views

How to Work with Child Tasks

Parent tasks can have child subtasks stored in aitasks/t<N>/. The board supports expanding and collapsing child tasks inline.

Expanding children:

1. Focus a parent task that shows “👶 N children”
2. Press x to expand — child task cards appear below the parent, indented with a “↳” connector

Collapsing children:

1. Press x again on the parent (or on any of its child cards) to collapse

Navigating children:

• Use Up/Down arrows to move between child cards
• Child cards show the same information as parent cards
• Press Enter on a child card to view its full details
• In the child detail dialog, a “Parent” field links back to the parent task

Restrictions:

• Child tasks cannot be moved between columns or reordered with Shift+arrows
• Child tasks cannot be deleted individually from the board (delete the parent to remove all)

How to Navigate Task Relationships

The task detail dialog shows several relationship fields. Each is focusable — use Up/Down to navigate to them, then press Enter to follow the link:

How to Pick a Task for Implementation

From the task detail dialog:

1. Click the “Pick” button
2. The board launches ait codeagent invoke task-pick <task_number> in a terminal emulator (or suspends and runs it in the current terminal if no emulator is found)

The code agent wrapper resolves which agent and model to use for the task-pick operation based on your configuration, so the board respects whatever agent you have configured (Claude Code, Gemini CLI, Codex, or OpenCode). This starts the full aitask-pick workflow: assignment, planning, implementation, and archival. The board refreshes after the pick session completes (when running in suspend mode).

The “Pick” button is disabled for tasks with status “Done” or “Folded”.

How to Lock and Unlock Tasks

Task locks are a lightweight reservation mechanism that signals to other users and AI agents that you intend to work on a task. Locks do not change task metadata — they are stored on the aitask-locks branch and fetched on every board refresh (manual r, auto-refresh, or after lock/unlock operations).

Note: You do not need to manually lock a task before using /aitask-pick or /aitask-pickrem. These skills acquire the lock, set status to Implementing, and update assigned_to in one step. Board locks are a manual pre-reservation tool — useful for reserving a task ahead of time (including before sending it to /aitask-pickweb, which cannot acquire locks from Claude Code Web), or coordinating without the pick workflow. See the ait lock command reference for the full decision guide.

Locking: open the task detail dialog (Enter) → click “🔒 Lock” → confirm the email (defaults to userconfig.yaml or emails.txt) → Save. A notification confirms the lock. The button is disabled when the task is already locked or has status Done / Folded.

Unlocking: open the task detail dialog → click “🔓 Unlock”. If the lock belongs to you, it is released immediately. If it belongs to someone else, a confirmation dialog shows the lock details (owner, hostname, timestamp, staleness) and asks whether to force-unlock.

Identifying locks: task cards display a 🔒 user@example.com line when locked. In the detail dialog, the lock field shows 🔒 Locked: user@example.com on hostname since <timestamp> (locks older than 24 hours are annotated “(may be stale)”).

Multi-agent coordination: ait lock --list shows all locks across the team; the board’s search box filters by lock-owner email (owner strings are searchable along with other card metadata). Locks are advisory — they do not prevent force-unlocking, so coordinate with the owner before overriding a stale lock.

For the underlying mechanism, CLI usage, and the Claude Code Web pre-locking workflow, see the ait lock command reference.

Caution: Locks are advisory – they do not prevent force-unlocking. If a lock appears stale (older than 24 hours, marked with “(may be stale)”), coordinate with the lock owner before force-unlocking.

How to Use the External Editor

To edit a task file in your preferred text editor:

1. Open the task detail dialog (Enter)
2. Click the “Edit” button
3. The board suspends and opens the file in your $EDITOR (defaults to nano on Linux/macOS, notepad on Windows)
4. Make your changes, save, and exit the editor
5. The board resumes and reloads the task data

The “Edit” button is disabled for tasks with status “Done” or “Folded”.

How to Open Linked Issues

If a task has an issue field in its frontmatter (a URL to a GitHub, GitLab, or Bitbucket issue):

1. Open the task detail dialog (Enter)
2. Navigate to the “Issue” field (it shows the URL with “(Enter to open)” hint)
3. Press Enter to open the URL in your default web browser

How to Configure Auto-Refresh

The board can periodically reload task files from disk so that changes made externally (e.g., by an AI agent or on another machine) appear automatically without pressing r.

Opening the settings dialog:

• Press O from the board, or
• Open the command palette (Ctrl+Backslash) and select “Options”

Changing the auto-refresh interval:

1. In the settings dialog, use Left/Right arrows on the “Auto-refresh (min)” field to cycle through the available intervals: 0, 1, 2, 5, 10, 15, 30 minutes
2. Select 0 to disable auto-refresh entirely
3. Click “Save” to apply

Changes take effect immediately — the timer is restarted (or stopped) as soon as you save. The setting is persisted to aitasks/metadata/board_config.json, so it survives restarts.

The default interval is 5 minutes.

Note: Auto-refresh is skipped when a modal dialog is open (e.g., task detail, column editor). The refresh will occur at the next interval after the modal is closed. You can always press r to refresh manually at any time.

How to Sync with Remote

When working across multiple machines, task files can get out of sync. The board integrates with ait sync to push local changes and pull remote changes automatically.

Manual sync:

1. Press s from the board, or open the command palette (Ctrl+Backslash) and select “Sync with Remote”
2. A notification appears showing the result: “Synced (pushed N, pulled M)”, “Pushed N commits”, “Pulled M commits”, “Already up-to-date”, or an error message

Enabling auto-sync:

1. Press O to open the options/settings dialog
2. Toggle “Sync on refresh” to yes
3. Click “Save”

When enabled, the board runs ait sync silently on each auto-refresh interval instead of just reloading from disk. The subtitle bar shows “+ sync” to indicate auto-sync is active.

Note: Auto-sync requires the data branch mode (.aitask-data worktree). If task data lives on the main branch (legacy mode), the sync option is not available.

Handling conflicts:

If the sync detects merge conflicts (e.g., the same task was edited on two machines), a conflict dialog appears listing the affected files. You have two options:

• Resolve Interactively — Opens ait sync in a terminal where you can edit each conflicted file in $EDITOR and complete the rebase
• Dismiss — Closes the dialog without resolving; the conflicts remain for the next sync attempt

No network:

If the remote is unreachable (timeout after 10 seconds), the board shows a warning notification and continues working with local data. No partial state is left behind.

tmux integration

When you run ait board inside tmux, press j to open the TUI switcher dialog and jump to another integrated TUI (Monitor, Code Browser, Settings, a running code agent window, or a brainstorm session) — the switcher either focuses the existing tmux window or creates a new one.

A typical flow from the board: triage a task, press j, switch to monitor to watch the agents running on other panes or to codebrowser to review the diff produced for a completed task.

The switcher requires a tmux session — see Terminal Setup for how to launch one with ait ide.

Next: Reference — keybindings, configuration, and internals.